Обзор

SQLite может формироваться, чтобы вызвать функцию обратного вызова, содержащую код ошибки и краткое сообщение об ошибке каждый раз, когда аномалии происходят. Этот механизм очень полезен в отслеживании неясных проблем, которые редко происходят. Разработчики приложений поощряются использовать в своих интересах средство для регистрации ошибок SQLite в их продуктах, поскольку это очень мало грузит CPU и память, но может быть огромной помощью для отладки.

1. Подготовка отзыва регистрации ошибок

Может быть только единственный отзыв регистрации ошибок для каждого процесса. Отзыв регистрации ошибок зарегистрирован во время запуска, используя C-код, подобный следующему:

sqlite3_config(SQLITE_CONFIG_LOG, errorLogCallback, pData);

Функция обратного вызова программы регистрации ошибок могла бы выглядеть примерно так:

void errorLogCallback(void *pArg, int iErrCode, const char *zMsg)
{
  fprintf(stderr, "(%d) %s\n", iErrCode, zMsg);
}

Пример выше иллюстрирует сигнатуру отзыва программы регистрации ошибок. Однако, во встраиваемом приложении, обычно не печатают сообщения в stderr. Вместо этого можно было бы хранить сообщения в предварительно ассигнованном кольцевом буфере, где к ним можно получить доступ, когда диагностическая информация необходима во время отладки. Или возможно сообщения можно послать в Syslog. Так или иначе сообщения должны храниться там, где они доступны для разработчиков.

Нет ничего технически неправильно с показом сообщений программы регистрации ошибок конечным пользователям. Сообщения не содержат чувствительную или частную информацию, которая должна быть защищена от несанкционированного просмотра. Скорее сообщения технические по своей природе и не полезные или значащие типичному конечному пользователю. Сообщения, прибывающие из программы регистрации ошибок, предназначаются для гиков базы данных. Покажите их соответственно.

2. Интерфейсные детали

Третий аргумент sqlite3_config( SQLITE_CONFIG_LOG,...) ("pData" в примере выше) является указателем на произвольные данные. SQLite передает этот указатель в первый аргумент отзыва программы регистрации ошибок. Указатель может использоваться, чтобы передать специализированную установку или статусную информацию при желании. Или это может просто быть NULL, который проигнорирован отзывом.

Второй аргумент отзыва программы регистрации ошибок это integer расширенный код ошибки. Третий аргумент программы регистрации ошибок это текст сообщения об ошибке. Текст сообщения об ошибке сохранен в буфере стопки фиксированной длины в функции запроса и будет действителен только на время работы функции обратного вызова программы регистрации ошибок. Программа регистрации ошибок должна превратить копию этого сообщения в постоянное хранение, если сообщение необходимо.

Отзыв программы регистрации ошибок нужно рассматривать как обработчик сигнала. Приложение должно обработать ошибку, затем возвратить управление как можно скорее. Никакой другой API SQLite не должен быть вызван, прямо или косвенно, из программы регистрации ошибок. Отзыв программы регистрации ошибок вызван, когда выделение памяти терпит неудачу, таким образом, обычно плохая идея попытаться ассигновать память в программе регистрации ошибок. Даже не думайте о попытке сохранить сообщение об ошибке в другой базе данных SQLite.

Приложения могут использовать sqlite3_log(E,F,..) API, чтобы послать новые сообщения в регистрацию при желании, но этому препятствуют. sqlite3_log() предназначается для использования только расширениями, не приложениями.

3. Множество сообщений об ошибках

Сообщения об ошибках, которые можно было бы послать в программу регистрации ошибок и их точный формат, подвергаются изменениям от одного выпуска до следующего. Таким образом, приложения не должны зависеть ни от каких конкретных форматов текста сообщения об ошибке или кодов ошибок.

Следующее это частичный список видов сообщений, которые могли бы появиться в отзыве программы регистрации ошибок.

• Любое время там это ошибка любого компилированного SQL-оператора (через sqlite3_prepare_v2()) или запуск SQL-оператора (через sqlite3_step() ), когда ошибка зарегистрирована.

• Когда изменение схемы происходит, который требует, чтобы подготовленный запрос был повторно размечен и подготовлен, то событие зарегистрировано с кодом ошибки SQLITE_SCHEMA. Переразбор и повторная подготовка обычно автоматические (предполагающие, что sqlite3_prepare_v2() использовался, чтобы подготовить запрос первоначально, что рекомендуется), и таким образом эти события регистрации обычно единственный способ знать, что это повторно готовится.

• Сообщения SQLITE_NOTICE зарегистрированы каждый раз, когда база данных должна быть восстановлена потому что предыдущий процесс записи свалился, не заканчивая транзакцию. Код ошибки SQLITE_NOTICE_RECOVER_ROLLBACK, восстанавливая журнал обратной перемотки, и SQLITE_NOTICE_RECOVER_WAL, восстанавливая журнал с упреждающей записью.

• Сообщения SQLITE_WARNING зарегистрированы, когда файлы базы данных переименованы или им назначен псевдоним способами, которые могут привести к повреждению базы данных. См. 1 и 2.

• Ошибка Out of memory (OOM) производит события регистрации ошибок с кодом ошибки SQLITE_NOMEM и сообщением, в котором говорится, сколько байтов памяти требовало неудавшееся распределение.

• Ошибки I/O в интерфейсе OS производят события регистрации ошибок. Сообщение к этим событиям дает номер строки в исходном коде где порождена ошибка и имя файла, связанное с событием, когда есть соответствующий файл.

• Когда повреждение базы данных обнаружено, вызван отзыв программы регистрации ошибок SQLITE_CORRUPT. Как с ошибками I/O, текст сообщения об ошибке содержит номер строки в коде первоисточника, где ошибка была сначала обнаружена.

• Отзыв программы регистрации ошибок вызван на ошибки SQLITE_MISUSE. Это полезно в обнаружении проблем проектирования приложений, когда в кодах возврата не последовательно проверяется код приложения.

SQLite стремится поддержать трафик программы регистрации ошибок на низком уровне и послать сообщения в программу регистрации ошибок только когда действительно что-то не так. Приложения могли бы далее выбрать сообщения об ошибке, сознательно игнорируя определенные классы сообщений об ошибках. Например, приложение, которое вносит частые изменения схемы базы данных, могло бы хотеть проигнорировать все ошибки SQLITE_SCHEMA.

4. Резюме

Использование отзыва программы регистрации ошибок настоятельно рекомендовано. Отладочная информация, которую обеспечивает программа регистрации ошибок, оказалась очень полезной в разыскивании неясных проблем, которые происходят при запросах после того, как они получают данные. Отзыв программы регистрации ошибок также оказался полезным в фиксации случайных ошибок, которые приложение пропускает из-за непоследовательной проверки кодов возврата API. Разработчики поощряются осуществить отзыв программы регистрации ошибок рано в цикле разработки, чтобы быстро определить неожиданное поведение, и оставить отзыв программы регистрации ошибок включенным посредством развертывания. Если программа регистрации ошибок никогда не находит проблему, то никакой вред не причинен. Но отказ настроить соответствующую программу регистрации ошибок мог бы поставить под угрозу диагностические возможности позже.