The Core API | SQLite

The core interface to the SQLite library is considered to be just three functions that allow you to open and close a database and to execute a query using a user-defined callback function. In this section we'll also look at the error codes returned from the core API.

Opening and Closing a Database

You can open and close a database as follows:

 sqlite *sqlite_open(   const char *dbname,   int mode,   char **errmsg ); void sqlite_close(sqlite *db);

The return value of sqlite_open() and the argument to sqlite_close() is an opaque sqlite data structure.

 typedef struct sqlite sqlite;

Executing a Query

You can execute a query as follows:

 int sqlite_exec(   sqlite *db,   char *sql,   int (*xCallback)(void *, int, char **, char **),   void pArg,   char **errmsg );

The callback function has the following prototype:

 int callback(void *pArg, int argc, char **argv, char **columnNames) {   return 0; }

Error Codes

This section describes SQLite error codes; each error code is followed by a description of its meaning.

 #define SQLITE_OK           0   /* Successful result */

Returned if everything worked and there were no errors.

 #define SQLITE_ERROR        1   /* SQL error or missing database */

Indicates an error in the SQL statement being executed.

 #define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */

Indicates that an internal consistency check within the SQLite library failed. This code will only ever be returned as a result of a bug, and such occurrences should be reported to the SQLite mailing list.

 #define SQLITE_PERM         3   /* Access permission denied */

Indicates that the database file cannot be opened due to insufficient file permissions.

 #define SQLITE_ABORT        4   /* Callback routine requested an abort */

This value is returned if the callback function returns a non-zero value.

 #define SQLITE_BUSY         5   /* The database file is locked */

Indicates that another program or thread has the database locked. Only one thread can open a database file for writing at a time, though multiple reads can take place simultaneously.

 #define SQLITE_LOCKED       6   /* A table in the database is locked */

Indicates that the database is locked by a recursive call to sqlite_exec(). Calls to sqlite_exec() from within a callback function are permitted as long as they do not attempt to write to the same table.

 #define SQLITE_NOMEM        7   /* A malloc() failed */

This value is returned if a call to malloc() fails due to not enough system memory being available.

 #define SQLITE_READONLY     8   /* Attempt to write a readonly database */

Indicates that an attempt was made to write to a database file that was opened in read-only mode.

 #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */

This value is returned if a database operation is interrupted by the sqlite_interrupt() function being called.

 #define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */

This value is returned if the operating system fails to perform a disk I/O operation, for instance if there is no space left on the device.

 #define SQLITE_CORRUPT     11   /* The database disk image is malformed */

This value would only be returned as a consequence of an unknown error in SQLite or a hardware or operating-system malfunction. It may indicate that the database file has become corrupted, or that a disk I/O error has forced SQLite to leave the database file in a corrupted state.

 #define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */

For internal use only. This value will never be returned by sqlite_exec().

 #define SQLITE_FULL        13   /* Insertion failed because database is full */

This value is returned if an insert operation fails because the database is too big to take any more information, for instance when the size of the database file would exceed the operating system's file size limit.

 #define SQLITE_CANTOPEN    14   /* Unable to open the database file */

This value indicates that that database file could not be opened for some other reason that does not have its own return code.

 #define SQLITE_PROTOCOL    15   /* Database lock protocol error */

Indicates that the file-locking protocol on SQLite's rollback journal files has been violated.

 #define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */

For internal use only. This value will never be returned by sqlite_exec().

 #define SQLITE_SCHEMA      17   /* The database schema changed */

Indicates that another process has altered the database schema since it was first read into memory when the database was initially opened. SQLite will re-read the schema when this happens but will not be able to complete the SQL statement that was being processed. Submitting the statement a second time will usually allow the command to be executed.

 #define SQLITE_TOOBIG      18   /* Too much data for one row of a table */

Indicates that the maximum row size for a table would be exceeded. The limit is defined at compile time by the MAX_BYTES_PER_ROW value in sqliteInt.h.

 #define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */

Indicates that the SQL statement would have violated a database constraint.

 #define SQLITE_MISMATCH    20   /* Data type mismatch */

This value is returned when an attempt is made to insert non-integer data into an INTEGER PRIMARY KEY column.

 #define SQLITE_MISUSE      21   /* Library used incorrectly */

Indicates that the SQLite library has been misused in some way, for instance calling sqlite_exec() after the database has been closed, or calling sqlite_step() after a SQLITE_DONE or SQLITE_ERROR return code.

 #define SQLITE_NOLFS       22   /* Uses OS features not supported on host */

This value is returned if an attempt is made to access a database file larger than 2GB in size on a legacy operating system that does not include large file support.

 #define SQLITE_AUTH        23   /* Authorization denied */

Indicates that the authorizer callback has disallowed the SQL you are attempting to execute.