*** DRAFT ***
SQLite can be configured to invoke a callback function containing an error code and a terse error message whenever anomalies occur. This mechanism is very helpful in tracking obscure problems that occur rarely and in the field. Application developers are encouraged to take advantage of the error logging facility of SQLite in their products, as it is very low CPU and memory cost but can be a huge aid for debugging.
There can only be a single error logging callback per process. The error logging callback is registered at start-time using C-code similar to the following:
sqlite3_config(SQLITE_CONFIG_LOG, errorLogCallback, pData);
The error logger callback function might look something like this:
void errorLogCallback(void *pArg, int iErrCode, const char *zMsg){
fprintf(stderr, "(%d) %s\n", iErrCode, zMsg);
}
The example above illustrates the signature of the error logger callback. However, in an embedded application, one usually does not print messages on stderr. Instead, one might store the messages in a preallocated circular buffer where they can be accessed when diagnostic information is needed during debugging. Or perhaps the messages can be sent to Syslog. Somehow, the messages need to be stored where they are accessible to developers, not displayed to end users.
Do not misunderstand: There is nothing technically wrong with displaying the error logger messages to end users. The messages do not contain sensitive or private information that must be protected from unauthorized viewing. Rather the messages are technical in nature and are not useful or meaningful to the typical end user. The messages coming from the error logger are intended for database geeks. Display them accordingly.
The third argument to the sqlite3_config(SQLITE_CONFIG_LOG,...) interface (the "pData" argument in the example above) is a pointer to arbitrary data. SQLite passes this pointer through to the first argument of the error logger callback. The pointer can be used to pass application-specific setup or state information, if desired. Or it can simply be a NULL pointer which is ignored by the callback.
The second argument to the error logger callback is an integer extended error code. The third argument to the error logger is the text of the error message. The error message text is stored in a fixed-length stack buffer in the calling function and so will only be valid for the duration of the error logger callback function. The error logger should make a copy of this message into persistent storage if retention of the message is needed.
The error logger callback should be treated like a signal handler. The application should save off or otherwise process the error, then return as soon as possible. No other SQLite APIs should be invoked, directly or indirectly, from the error logger. SQLite is not reentrant through the error logger callback. In particular, the error logger callback is invoked when a memory allocation fails, so it is generally a bad idea to try to allocate memory inside the error logger. Do not even think about trying to store the error message in another SQLite database.
Applications can use the sqlite3_log(E,F,..) API to send new messages to the log, if desired, but this is discouraged. The sqlite3_log() interface is intended for use by extensions only, not by applications.
The error messages that might be sent to the error logger and their exact format is subject to changes from one release to the next. So applications should not depend on any particular error message text formats or error codes. Things do not change capriciously, but they do sometimes changes.
The following is a partial list of the kinds of messages that might appear in the error logger callback.
Any time there is an error either compiling an SQL statement (using sqlite3_prepare_v2() or its siblings) or running an SQL statement (using sqlite3_step()) that error is logged.
When a schema change occurs that requires a prepared statement to be reparsed and reprepared, that event is logged with the error code SQLITE_SCHEMA. The reparse and reprepare is normally automatic (assuming that sqlite3_prepare_v2() has been used to prepare the statements originally, which is recommended) and so these logging events are normally the only way to know that reprepares are taking place.
SQLITE_NOTICE messages are logged whenever a database has to be recovered because the previous writer crashed without completing its transaction. The error code is SQLITE_NOTICE_RECOVER_ROLLBACK when recovering a rollback journal and SQLITE_NOTICE_RECOVER_WAL when recovering a write-ahead log.
SQLITE_WARNING messages are logged when database files are renamed or aliased in ways that can lead to database corruption. (See 1 and 2 for additional information.)
Out of memory (OOM) error conditions generate error logging events with the SQLITE_NOMEM error code and a message that says how many bytes of memory were requested by the failed allocation.
I/O errors in the OS-interface generate error logging events. The message to these events gives the line number in the source code where the error originated and the filename associated with the event when there is a corresponding file.
When database corruption is detected, an SQLITE_CORRUPT error logger callback is invoked. As with I/O errors, the error message text contains the line number in the original source code where the error was first detected.
An error logger callback is invoked on SQLITE_MISUSE errors. This is useful in detecting application design issues when return codes are not consistently checked in the application code.
SQLite strives to keep error logger traffic low and only send messages to the error logger when there really is something wrong. Applications might further cull the error message traffic by deliberately ignoring certain classes of error messages that they do not care about. For example, an application that makes frequent database schema changes might want to ignore all SQLITE_SCHEMA errors.
The use of the error logger callback is highly recommended. The debugging information that the error logger provides has proven very useful in tracking down obscure problems that occur with applications after they get into the field. The error logger callback has also proven useful in catching occasional errors that the application misses because of inconsistent checking of API return codes. Developers are encouraged to implement an error logger callback early in the development cycle in order to spot unexpected behavior quickly, and to leave the error logger callback turned on through deployment. If the error logger never finds a problem, then no harm is done. But failure to set up an appropriate error logger might compromise diagnostic capabilities later on.