Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## Assumptions Made By SQLite

This document defines behavior that SQLite expects from the application that is using SQLite. We call these "assumptions", but they might also be called "Application Requirements" since they can be thought of additional requirements that are imposed on any application that uses SQLite.

Another way of looking at these invariants is that they are limitations or constraints on the use of SQLite. If an application fails to abide by the assumptions described here, then the behavior of SQLite will be undefined and probably undesirable.

Yet another way of thinking about these invariants is that all of the statements listed below must be true in order for SQLite to operate correctly.

A10512 | The input to sqlite3_complete() must be a zero-terminated UTF-8 string.
A10513 | The input to sqlite3_complete16() must be a zero-terminated UTF-16 string in native byte order.
A12016 | The C parameter to sqlite3_close(C) must be either a NULL pointer or an sqlite3 object pointer obtained from sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2(), and not previously closed.
A12141 | The first parameter to sqlite3_exec() must be an valid and open database connection.
A12142 | The database connection must not be closed while sqlite3_exec() is running.
A12143 | The calling function should use sqlite3_free() to free the memory that *errmsg is left pointing at once the error message is no longer needed.
A12145 | The SQL statement text in the 2nd parameter to sqlite3_exec() must remain unchanged while sqlite3_exec() is running.
A12232 | If a separate thread performs a new INSERT on the same database connection while the sqlite3_last_insert_rowid() function is running and thus changes the last insert rowid, then the value returned by sqlite3_last_insert_rowid() is unpredictable and might not equal either the old or the new last insert rowid.
A12252 | If a separate thread makes changes on the same database connection while sqlite3_changes() is running then the value returned is unpredictable and not meaningful.
A12264 | If a separate thread makes changes on the same database connection while sqlite3_total_changes() is running then the value returned is unpredictable and not meaningful.
A12279 | If the database connection closes while sqlite3_interrupt() is running then bad things will likely happen.
A12319 | A busy handler must not close the database connection or prepared statement that invoked the busy handler.
A12936 | If another thread changes the autocommit status of the database connection while this routine is running, then the return value is undefined.
A13154 | The database connection pointer D in a call to sqlite3_next_stmt(D,S) must refer to an open database connection and in particular must not be a NULL pointer.
A13751 | If two or more threads call one or more column metadata interfaces for the same prepared statement and result column at the same time then the results are undefined.
A17350 | The pointer arguments to sqlite3_free() and sqlite3_realloc() must be either NULL or else pointers obtained from a prior invocation of sqlite3_malloc() or sqlite3_realloc() that have not yet been released.
A17351 | The application must not read or write any part of a block of memory after it has been released using sqlite3_free() or sqlite3_realloc().
A21001 | If a system failure occurs during or after a "create file" operation, but before the created file has been synced, then SQLite assumes that it is possible that the created file may not exist following system recovery.
A21002 | If a "create file" operation is executed by SQLite, and then the created file synced, then SQLite assumes that the file-system modifications corresponding to the "create file" operation have been committed to persistent media. It is assumed that if a system failure occurs any time after the file has been successfully synced, then the file is guaranteed to appear in the file-system following system recovery.
A21003 | If a system failure occurs at any time after a "delete file" operation (call to the VFS xDelete() method) returns successfully, it is assumed that the file-system will not contain the deleted file following system recovery.
A21004 | If a system failure occurs during a "delete file" operation, it is assumed that following system recovery the file-system will either contain the file being deleted in the state it was in before the operation was attempted, or not contain the file at all. It is assumed that it is not possible for the file to have become corrupted purely as a result of a failure occuring during a "delete file" operation.
A21005 | If a system failure occurs during or after a "truncate file" operation, but before the truncated file has been synced, then SQLite assumes that the size of the truncated file is either as large or larger than the size that it was to be truncated to.
A21006 | If a system failure occurs during or after a "truncate file" operation, but before the truncated file has been synced, then it is assumed that the contents of the file up to the size that the file was to be truncated to are not corrupted.
A21007 | If a "truncate file" operation is executed by SQLite, and then the truncated file synced, then SQLite assumes that the file-system modifications corresponding to the "truncate file" operation have been committed to persistent media. It is assumed that if a system failure occurs any time after the file has been successfully synced, then the effects of the file truncation are guaranteed to appear in the file system following recovery.
A21008 | If a system failure occurs during or after a "write file" operation, but before the corresponding file has been synced, then it is assumed that the content of all sectors spanned by the write file operation are untrustworthy following system recovery. This includes regions of the sectors that were not actually modified by the write file operation.
A21009 | If a system failure occurs during or after a "write file" operation that causes the file to grow, but before the corresponding file has been synced, then it is assumed that the size of the file following recovery is as large or larger than it was before the "write file" operation that, if successful, would cause the file to grow.
A21010 | It is assumed that writing a series of sequential blocks of data to a file in order is faster than writing the same blocks in an arbitrary order.
A21011 | If a system failure occurs on a system that supports the atomic-write property for blocks of size N bytes following an aligned write of N bytes to a file but before the file has been succesfully synced, then is is assumed following recovery that all sectors spanned by the write operation were correctly updated, or that none of the sectors were modified at all.
A21012 | If a system failure occurs on a system that supports the safe-append following a write operation that appends data to the end of the file without modifying any of the existing file content but before the file has been succesfully synced, then is is assumed following recovery that either the data was correctly appended to the file, or that the file size remains unchanged. It is assumed that it is impossible that the file be extended but populated with incorrect data.
A21013 | Following a system recovery, if a device sector is deemed to be untrustworthy as defined by A21008 and neither A21011 or A21012 apply to the range of bytes written, then no assumption can be made about the content of the sector following recovery. It is assumed that it is possible for such a sector to be written correctly, not written at all, populated with garbage data or any combination thereof.
A21014 | If a system failure occurs on a system that supports the sequential-write property, then it is assumed that all operations completed before the last time any file was synced have been successfully committed to persistent media.
A21015 | If a system failure occurs on a system that supports the sequential-write property, then it is assumed that the set of possible states that the file-system may be in following recovery is the same as if each of the write operations performed since the most recent time a file was synced was itself followed by a sync file operation, and that the system failure may have occured during any of the write or sync file operations.

This page last modified 2008/07/22 17:19:32 UTC