Журнал ошибок и предупреждений

Обзор

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

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 передает этот указатель в качестве первого аргумента функции обратного вызова регистратора ошибок. Указатель можно использовать для передачи информации о настройке или состоянии, специфичной для приложения, при необходимости. Или он может просто быть нулевым указателем, который игнорируется функцией обратного вызова.

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

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

Приложения могут использовать API sqlite3_log(E,F,..) для отправки новых сообщений в журнал, если это необходимо, но это не рекомендуется. Интерфейс 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 для получения дополнительной информации.)

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

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

• При обнаружении повреждения базы данных вызывается обратный вызов регистратора ошибок SQLITE_CORRUPT. Как и при ошибках ввода-вывода, текст сообщения об ошибке содержит номер строки в исходном коде, где ошибка была впервые обнаружена.

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

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

4. Резюме

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