types and constants

The following types are used solely to improve clarity, and are otherwise equivalent to atom.

Types
sqlite3	An opaque pointer/database handle, from sqlite3_open(). Each open SQLite database is represented by a pointer to an instance of the opaque structure named "sqlite3". It is created with sqlite3_open() and destroyed with sqlite3_close(). Many other interfaces such as sqlite3_exec(), sqlite3_get_table(), and sqlite3_prepare(), to name but three, perform futher actions on an sqlite3 object.
sqlite3_stmt	An opaque pointer to a prepared statement, from sqlite3_prepare(). An instance of this object represents a single SQL statement that has been compiled into binary form and is ready to be evaluated. Think of each SQL statement as a separate computer program. The original SQL text is source code. A prepared statement object is the compiled object code. All SQL must be converted into a prepared statement before it can be run. The functions sqlite3_exec() and sqlite3_get_table() do this automatically, but they also do it every time. The life-cycle of a prepared statement object (including inside the above-mentioned routines) usually goes like this: Create the prepared statement object using sqlite3_prepare(). Bind values to parameters, if any, using the sqlite3_bind interfaces. Run the SQL by calling sqlite3_step() one or more times. Zero or more times, reset the prepared statement using sqlite3_reset() and go back to step 2. Destroy the object using sqlite3_finalize().

Types

sqlite3

An opaque pointer/database handle, from sqlite3_open().

Each open SQLite database is represented by a pointer to an instance of the opaque structure named "sqlite3".
It is created with sqlite3_open() and destroyed with sqlite3_close().
Many other interfaces such as sqlite3_exec(), sqlite3_get_table(), and sqlite3_prepare(), to name but three, perform futher actions on an sqlite3 object.

sqlite3_stmt

An opaque pointer to a prepared statement, from sqlite3_prepare().

An instance of this object represents a single SQL statement that has been compiled into binary form and is ready to be evaluated.

Think of each SQL statement as a separate computer program. The original SQL text is source code.
A prepared statement object is the compiled object code.
All SQL must be converted into a prepared statement before it can be run.
The functions sqlite3_exec() and sqlite3_get_table() do this automatically, but they also do it every time.

The life-cycle of a prepared statement object (including inside the above-mentioned routines) usually goes like this:

Create the prepared statement object using sqlite3_prepare().
Bind values to parameters, if any, using the sqlite3_bind interfaces.
Run the SQL by calling sqlite3_step() one or more times.
Zero or more times, reset the prepared statement using sqlite3_reset() and go back to step 2.
Destroy the object using sqlite3_finalize().

Error codes	(obviously, lookup eg 101 from ex.err here, but use SQLITE_DONE when writing code)
0 - SQLITE_OK	Successful result The SQLITE_OK result code means that the operation was successful and that there were no errors. Most other result codes indicate an error.
1 - SQLITE_ERROR	SQL error or missing database The SQLITE_ERROR result code is a generic error code that is used when no other more specific error code is available.
2 - SQLITE_INTERNAL	An internal logic error in SQLite
3 - SQLITE_PERM	Access permission denied
4 - SQLITE_ABORT	Callback routine requested an abort The SQLITE_ABORT result code indicates that an operation was aborted prior to completion, usually be application request. See also: SQLITE_INTERRUPT. If the callback function to sqlite3_exec() returns non-zero, then sqlite3_exec() will return SQLITE_ABORT. If a ROLLBACK operation occurs on the same database connection as a pending read or write, then the pending read or write may fail with an SQLITE_ABORT or SQLITE_ABORT_ROLLBACK error. In addition to being a result code, the SQLITE_ABORT value is also used as a conflict resolution mode returned from the sqlite3_vtab_on_conflict() interface. Also: SQLITE_ABORT_ROLLBACK (516, ie 4+#200): The SQLITE_ABORT_ROLLBACK error code is an extended error code for SQLITE_ABORT indicating that an SQL statement aborted because the transaction that was active when the SQL statement first started was rolled back. Pending write operations always fail with this error when a rollback occurs. A ROLLBACK will cause a pending read operation to fail only if the schema was changed within the transaction being rolled back.
5 - SQLITE_BUSY	The database file is locked The SQLITE_BUSY result code indicates that the database file could not be written (or in some cases read) because of concurrent activity by some other database connection, usually a database connection in a separate process. For example, if process A is in the middle of a large write transaction and at the same time process B attempts to start a new write transaction, process B will get back an SQLITE_BUSY result because SQLite only supports one writer at a time. Process B will need to wait for process A to finish its transaction before starting a new transaction. An SQLITE_BUSY error can occur at any point in a transaction: when the transaction is first started, during any write or update operations, or when the transaction commits. To avoid encountering SQLITE_BUSY errors in the middle of a transaction, the application can use BEGIN IMMEDIATE instead of just BEGIN to start a transaction. The BEGIN IMMEDIATE command might itself return SQLITE_BUSY, but if it succeeds, then SQLite guarantees that no subsequent operations on the same database through the next COMMIT will return SQLITE_BUSY. See also: SQLITE_BUSY_RECOVERY and SQLITE_BUSY_SNAPSHOT. The SQLITE_BUSY result code differs from SQLITE_LOCKED in that SQLITE_BUSY indicates a conflict with a separate database connection, probably in a separate process, whereas SQLITE_LOCKED indicates a conflict within the same database connection (or sometimes a database connection with a shared cache).
6 - SQLITE_LOCKED	A table in the database is locked
7 - SQLITE_NOMEM	A malloc() failed The SQLITE_NOMEM result code indicates that SQLite was unable to allocate all the memory it needed to complete the operation. In other words, an internal call to sqlite3_malloc() or sqlite3_realloc() has failed in a case where the memory being allocated was required in order to continue the operation.
8 - SQLITE_READONLY	Attempt to write a readonly database
9 - SQLITE_INTERRUPT	Operation terminated by sqlite_interrupt() The SQLITE_INTERRUPT result code indicates that an operation was interrupted by the sqlite3_interrupt() interface. See also: SQLITE_ABORT.
10 - SQLITE_IOERR	Some kind of disk I/O error occurred The SQLITE_IOERR result code says that the operation could not finish because the operating system reported an I/O error. A full disk drive will normally give an SQLITE_FULL error rather than an SQLITE_IOERR error. There are many different extended result codes for I/O errors that identify the specific I/O operation that failed.
11 - SQLITE_CORRUPT	The database disk image is malformed
12 - SQLITE_NOTFOUND	(Internal Only) Table or record not found
13 - SQLITE_FULL	Insertion failed because database is full The SQLITE_FULL result code indicates that a write could not complete because the disk is full. Note that this error can occur when trying to write information into the main database file, or it can also occur when writing into temporary disk files. Sometimes applications encounter this error even though there is an abundance of primary disk space because the error occurs when writing into temporary disk files on a system where temporary files are stored on a separate partition with much less space that the primary disk.
14 - SQLITE_CANTOPEN	Unable to open the database file
15 - SQLITE_PROTOCOL	Database lock protocol error
16 - SQLITE_EMPTY	(Internal Only) Database table is empty
17 - SQLITE_SCHEMA	The database schema changed The SQLITE_SCHEMA result code indicates that the database schema has changed. This result code can be returned from sqlite3_step() for a prepared statement that was generated using sqlite3_prepare(). If the database schema was changed by some other process in between the time that the statement was prepared and the time the statement was run, this error can result. If a prepared statement is generated from sqlite3_prepare_v2() [it is] then the statement is automatically re-prepared if the schema changes, up to SQLITE_MAX_SCHEMA_RETRY times (default: 50). The sqlite3_step() interface will only return SQLITE_SCHEMA back to the application if the failure persists after these many retries.
18 - SQLITE_TOOBIG	Too much data for one row of a table
19 - SQLITE_CONSTRAINT	Abort due to constraint violation The SQLITE_CONSTRAINT error code means that an SQL constraint violation occurred while trying to process an SQL statement. Additional information about the failed constraint can be found by consulting the accompanying error message (returned via sqlite3_errmsg()) or by looking at the extended error code.
20 - SQLITE_MISMATCH	Data type mismatch
21 - SQLITE_MISUSE	Library used incorrectly The SQLITE_MISUSE return code might be returned if the application uses any SQLite interface in a way that is undefined or unsupported. For example, using a prepared statement after that prepared statement has been finalized might result in an SQLITE_MISUSE error. SQLite tries to detect misuse and report the misuse using this result code. However, there is no guarantee that the detection of misuse will be successful. Misuse detection is probabilistic. Applications should never depend on an SQLITE_MISUSE return value. If SQLite ever returns SQLITE_MISUSE from any interface, that means that the application is incorrectly coded and needs to be fixed. Do not ship an application that sometimes returns SQLITE_MISUSE from a standard SQLite interface because that application contains potentially serious bugs.
22 - SQLITE_NOLFS	Uses OS features not supported on host
23 - SQLITE_AUTH	Authorization denied
100 - SQLITE_ROW	sqlite_step() has another row ready The SQLITE_ROW result code returned by sqlite3_step() indicates that another row of output is available.
101 - SQLITE_DONE	sqlite_step() has finished executing The SQLITE_DONE result code indicates that an operation has completed. The SQLITE_DONE result code is most commonly seen as a return value from sqlite3_step() indicating that the SQL statement has run to completion. But SQLITE_DONE can also be returned by other multi-step interfaces such as sqlite3_backup_step().

Obviously the actual values may be useful when debugging, which is the only reason they are included here, but source code should always use the human-readable names.

Error handlers
SQLITE3_FATAL, SQLITE3_NON_FATAL	Standard error handlers, that can be switched between by invoking sqlite3_set_fatal_id(integer rid), or you can provide your own, as long as it conforms to the following signature: function handler(string cmd, integer err_no, string err_desc). The default is SQLITE3_FATAL, which produces a proper diagnostic report and call stack, whereas the non-fatal version simply returns the triplet {err_no, err_desc, cmd}, however you will probably also need to store the results of routines such as sqlite3_exec() in an object to avoid typecheck errors.

Error handlers

SQLITE3_FATAL,
SQLITE3_NON_FATAL

Standard error handlers, that can be switched between by invoking sqlite3_set_fatal_id(integer rid), or you can provide your own, as long as it conforms to the following signature: function handler(string cmd, integer err_no, string err_desc). The default is SQLITE3_FATAL, which produces a proper diagnostic report and call stack, whereas the non-fatal version simply returns the triplet {err_no, err_desc, cmd}, however you will probably also need to store the results of routines such as sqlite3_exec() in an object to avoid typecheck errors.