<title>SQLite Result Codes</title>
<tcl>hd_keywords {result code} {result codes} {error code} {error codes}</tcl>
<h1 align="center">SQLite Result Codes</h1>
<p>
Many of the routines in the SQLite [C-language Interface] return
numeric result codes indicating either success or failure, and
in the event of a failure, providing some idea of the cause of
the failure. This document strives to explain what each
of those numeric result codes means.
<h2>Result Codes versus Error Codes</h2>
<p>
"Error codes" are a subset of "result codes" that indicate that
something has gone wrong. There are only a few non-error result
codes: [SQLITE_OK], [SQLITE_ROW], and [SQLITE_DONE]. The term
"error code" means any result code other than these three.
<tcl>hd_fragment pve {primary versus extended result codes} \
{*ext-v-prim} </tcl>
<h2>Primary Result Codes versus Extended Result Codes</h2>
<p>
Result codes are signed 32-bit integers.
The least significant 8 bits of the result code define a broad category
and are called the "primary result code". More significant bits provide
more detailed information about the error and are called the
"extended result code"
<p>
Note that the primary result code is always a part of the extended
result code. Given a full 32-bit extended result code, the application
can always find the corresponding primary result code merely by extracting
the least significant 8 bits of the extended result code.
<p>
All extended result codes are also error codes. Hence the terms
"extended result code" and "extended error code" are interchangeable.
<p>
For historic compatibility, the C-language interfaces return
primary result codes by default.
The extended result code for the most recent error can be
retrieved using the [sqlite3_extended_errcode()] interface.
The [sqlite3_extended_result_codes()] interface can be used to put
a [database connection] into a mode where it returns the
extended result codes instead of the primary result codes.
<h2>Definitions</h2>
<p>
All result codes are integers.
Symbolic names for all result codes are created using
"#define" macros in the sqlite3.h header file.
There are separate sections in the sqlite3.h header file for
the [result code definitions] and the [extended result code definitions].
<p>
Primary result code symbolic names are of the form "SQLITE_XXXXXX" where
XXXXXX is a sequence of uppercase alphabetic characters. Extended
result code names are of the form "SQLITE_XXXXXX_YYYYYYY" where
the XXXXXX part is the corresponding primary result code and the
YYYYYYY is an extension that further classifies the result code.
<p>
The names and numeric values for existing result codes are fixed
and unchanging. However, new result codes, and especially new extended
result codes, might appear in future releases of SQLite.
<tcl>
unset -nocomplain resdesc
unset -nocomplain resvalue
proc RESCODE {name value desc} {
set ::resdesc($name) $desc
set ::resvalue($name) $value
}
RESCODE SQLITE_OK 0 {
The SQLITE_OK result code means that the operation was successful and
that there were no errors. Most other result codes indicate an error.
}
RESCODE SQLITE_ERROR 1 {
The SQLITE_ERROR result code is a generic error code that is used when
no other more specific error code is available.
}
RESCODE SQLITE_INTERNAL 2 {
The SQLITE_INTERNAL result code indicates an internal malfunction.
In a working version of SQLite, an application should never see this
result code. If application does encounter this result code, it shows
that there is a bug in the database engine.
<p>
SQLite does not currently generate this result code.
However, [application-defined SQL functions] or
[virtual tables], or [VFSes], or other extensions might cause this
result code to be returned.
}
RESCODE SQLITE_PERM 3 {
The SQLITE_PERM result code indicates that the requested access mode
for a newly created database could not be provided.
}
RESCODE SQLITE_ABORT 4 {
The SQLITE_ABORT result code indicates that an operation was aborted
prior to completion, usually be application request.
See also: [SQLITE_INTERRUPT].
<p>
^If the callback function to [sqlite3_exec()] returns non-zero, then
sqlite3_exec() will return SQLITE_ABORT.
<p>
^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.
<p>
^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.
}
RESCODE SQLITE_BUSY 5 {
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.
<p>
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. The
[sqlite3_busy_timeout()] and [sqlite3_busy_handler()] interfaces and
the [busy_timeout pragma] are available to process B to help it deal
with SQLITE_BUSY errors.
<p>
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.
<p>
See also: [SQLITE_BUSY_RECOVERY] and [SQLITE_BUSY_SNAPSHOT].
<p>
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]).
}
RESCODE SQLITE_LOCKED 6 {
The SQLITE_LOCKED result code indicates that a write operation could not
continue because of a conflict within the same [database connection] or
a conflict with a different database connection that uses a [shared cache].
<p>
For example, a [DROP TABLE] statement cannot be run while another thread
is reading from that table on the same [database connection] because
dropping the table would delete the table out from under the concurrent
reader.
<p>
The SQLITE_LOCKED result code differs from [SQLITE_BUSY] in that
SQLITE_LOCKED indicates a conflict on the same [database connection]
(or on a connection with a [shared cache]) whereas [SQLITE_BUSY] indicates
a conflict with a different database connection, probably in a different
process.
}
RESCODE SQLITE_NOMEM 7 {
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.
}
RESCODE SQLITE_READONLY 8 {
The SQLITE_READONLY result code is returned when an attempt is made to
alter some data for which the current database connection does not have
write permission.
}
RESCODE SQLITE_INTERRUPT 9 {
The SQLITE_INTERRUPT result code indicates that an operation was
interrupted by the [sqlite3_interrupt()] interface.
See also: [SQLITE_ABORT]
}
RESCODE SQLITE_IOERR 10 {
The SQLITE_IOERR result code says that the operation could not finish
because the operating system reported an I/O error.
<p>
A full disk drive will normally give an [SQLITE_FULL] error rather than
an SQLITE_IOERR error.
<p>
There are many different extended result codes for I/O errors that
identify the specific I/O operation that failed.
}
RESCODE SQLITE_CORRUPT 11 {
The SQLITE_CORRUPT result code indicates that the database file has
been corrupted. See the [How To Corrupt Your Database Files] for
further discussion on how corruption can occur.
}
RESCODE SQLITE_NOTFOUND 12 {
The SQLITE_NOTFOUND result code is used in two contexts.
SQLITE_NOTFOUND can be returned by the [sqlite3_file_control()] interface
to indicate that the [file control opcode] passed as the third argument
was not recognized by the underlying [VFS].
SQLITE_NOTFOUND can also be returned by the xSetSystemCall() method of
an [sqlite3_vfs] object.
<p>
The SQLITE_NOTFOUND result code is also used
internally by the SQLite implementation, but those internal uses are
not exposed to the application.
}
RESCODE SQLITE_FULL 13 {
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].
<p>
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.
}
RESCODE SQLITE_CANTOPEN 14 {
The SQLITE_CANTOPEN result code indicates that SQLite was unable to
open a file. The file in question might be a primary database file
or on of several [temporary disk files].
}
RESCODE SQLITE_PROTOCOL 15 {
The SQLITE_PROTOCOL result code indicates a problem with the file locking
protocol used by SQLite. The SQLITE_PROTOCOL error is currently only
returned when using [WAL mode] and attempting to start a new transaction.
There is a race condition that can occur when two separate
[database connections] both try to start a transaction at the same time
in [WAL mode]. The loser of the race backs off and tries again, after
a brief delay. If the same connection loses the locking race dozens
of times over a span of multiple seconds, it will eventually give up and
return SQLITE_PROTOCOL. The SQLITE_PROTOCOL error should appear in practice
very, very rarely, and only when there are many separate processes all
competing intensely to write to the same database.
}
RESCODE SQLITE_EMPTY 16 {
The SQLITE_EMPTY result code is not currently used.
}
RESCODE SQLITE_SCHEMA 17 {
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()] or
[sqlite3_prepare16()]. 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.
<p>
If a [prepared statement] is generated from [sqlite3_prepare_v2()] 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.
}
RESCODE SQLITE_TOOBIG 18 {
The SQLITE_TOOBIG error code indicates that a string or BLOB was
too large. The default maximum length of a string or BLOB in SQLite is
1,000,000,000 bytes. This maximum length can be changed at compile-time
using the [SQLITE_MAX_LENGTH] compile-time option, or at run-time using
the [sqlite3_limit](db,[SQLITE_LIMIT_LENGTH],...) interface. The
SQLITE_TOOBIG error results when SQLite encounters a string or BLOB
that exceeds the compile-time or run-time limit.
<p>
The SQLITE_TOOBIG error code can also result when an oversized SQL
statement is passed into one of the [sqlite3_prepare_v2()] interfaces.
The maximum length of an SQL statement defaults to a much smaller
value of 1,000,000 bytes. The maximum SQL statement length can be
set at compile-time using [SQLITE_MAX_SQL_LENGTH] or at run-time
using [sqlite3_limit](db,[SQLITE_LIMIT_SQL_LENGTH],...).
}
RESCODE SQLITE_CONSTRAINT 19 {
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
[sqlite3_errmsg16()]) or by looking at the [extended error code].
}
RESCODE SQLITE_MISMATCH 20 {
The SQLITE_MISMATCH error code indicates a datatype mismatch.
<p>
SQLite is normally very forgiving about mismatches between the type of
a value and the declared type of the container in which that value is
to be stored. For example, SQLite allows the application to store
a large BLOB in a column with a declared type of BOOLEAN. But in a few
cases, SQLite is strict about types. The SQLITE_MISMATCH error is
returned in those few cases when the types do not match.
<p>
The [rowid] of a table must be an integer. Attempt to set the [rowid]
to anything other than an integer (or a NULL which will be automatically
converted into the next available integer rowid) results in an
SQLITE_MISMATCH error.
}
RESCODE SQLITE_MISUSE 21 {
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 [sqlite3_finalize|finalized] might result in an SQLITE_MISUSE error.
<p>
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.
<p>
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.
}
RESCODE SQLITE_NOLFS 22 {
The SQLITE_NOLFS error can be returned on systems that do not support
large files when the database grows to be larger than what the filesystem
can handle. "NOLFS" stands for "NO Large File Support".
}
RESCODE SQLITE_AUTH 23 {
The SQLITE_AUTH error is returned when the
[sqlite3_set_authorizer | authorizer callback] indicates that an
SQL statement being prepared is not authorized.
}
RESCODE SQLITE_FORMAT 24 {
The SQLITE_FORMAT error code is not currently used by SQLite.
}
RESCODE SQLITE_RANGE 25 {
The SQLITE_RANGE error indices that the parameter number argument
to one of the [sqlite3_bind_blob|sqlite3_bind] routines or the
column number in one of the [sqlite3_column_int|sqlite3_column]
routines is out of range.
}
RESCODE SQLITE_NOTADB 26 {
When attempting to open a file, the SQLITE_NOTADB error indicates that
the file being opened does not appear to be an SQLite database file.
}
RESCODE SQLITE_NOTICE 27 {
The SQLITE_NOTICE result code is not returned by any C/C++ interface.
However, SQLITE_NOTICE (or rather one of its [extended error codes])
is sometimes used as the first argument in an [sqlite3_log()] callback
to indicate that an unusual operation is taking place.
}
RESCODE SQLITE_WARNING 28 {
The SQLITE_WARNING result code is not returned by any C/C++ interface.
However, SQLITE_WARNING (or rather one of its [extended error codes])
is sometimes used as the first argument in an [sqlite3_log()] callback
to indicate that an unusual and possibly ill-advised operation is
taking place.
}
RESCODE SQLITE_ROW 100 {
The SQLITE_ROW result code returned by
[sqlite3_step()] indicates that another row of output is available.
}
RESCODE SQLITE_DONE 101 {
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()].
}
RESCODE SQLITE_IOERR_READ {SQLITE_IOERR | (1<<8)} {
The SQLITE_IOERR_READ error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error in the [VFS] layer
while trying to read from a file on disk. This error might result
from a hardware malfunction or because a filesystem came unmounted
while the file was open.
}
RESCODE SQLITE_IOERR_SHORT_READ {SQLITE_IOERR | (2<<8)} {
The SQLITE_IOERR_SHORT_READ error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating that a read attempt in the [VFS] layer
was unable to obtain as many bytes as was requested. This might be
due to a truncated file.
}
RESCODE SQLITE_IOERR_WRITE {SQLITE_IOERR | (3<<8)} {
The SQLITE_IOERR_WRITE error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error in the [VFS] layer
while trying to write into a file on disk. This error might result
from a hardware malfunction or because a filesystem came unmounted
while the file was open. This error should not occur if the filesystem
is full as there is a separate error code (SQLITE_FULL) for that purpose.
}
RESCODE SQLITE_IOERR_FSYNC {SQLITE_IOERR | (4<<8)} {
The SQLITE_IOERR_FSYNC error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error in the [VFS] layer
while trying to flush previously written content out of OS and/or
disk-control buffers and into persistent storage. In other words,
this code indicates a problem with the fsync() system call in unix
or the FlushFileBuffers() system call in windows.
}
RESCODE SQLITE_IOERR_DIR_FSYNC {SQLITE_IOERR | (5<<8)} {
The SQLITE_IOERR_DIR_FSYNC error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error in the [VFS] layer
while trying to invoke fsync() on a directory. The unix [VFS] attempts
to fsync() directories after creating or deleting certain files to
ensure that those files will still appear in the filesystem following
a power loss or system crash. This error code indicates a problem
attempting to perform that fsync().
}
RESCODE SQLITE_IOERR_TRUNCATE {SQLITE_IOERR | (6<<8)} {
The SQLITE_IOERR_TRUNCATE error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error in the [VFS] layer
while trying to truncate a file to a smaller size.
}
RESCODE SQLITE_IOERR_FSTAT {SQLITE_IOERR | (7<<8)} {
The SQLITE_IOERR_FSTAT error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error in the [VFS] layer
while trying to invoke fstat() (or the equivalent) on a file in order
to determine information such as the file size or access permissions.
}
RESCODE SQLITE_IOERR_UNLOCK {SQLITE_IOERR | (8<<8)} {
The SQLITE_IOERR_UNLOCK error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within xUnlock method on the [sqlite3_io_methods] object.
}
RESCODE SQLITE_IOERR_RDLOCK {SQLITE_IOERR | (9<<8)} {
The SQLITE_IOERR_UNLOCK error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within xLock method on the [sqlite3_io_methods] object while trying
to obtain a read lock.
}
RESCODE SQLITE_IOERR_DELETE {SQLITE_IOERR | (10<<8)} {
The SQLITE_IOERR_UNLOCK error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within xDelete method on the [sqlite3_vfs] object.
}
RESCODE SQLITE_IOERR_BLOCKED {SQLITE_IOERR | (11<<8)} {
The SQLITE_IOERR_BLOCKED error code is no longer used.
}
RESCODE SQLITE_IOERR_NOMEM {SQLITE_IOERR | (12<<8)} {
The SQLITE_IOERR_NOMEM error code is sometimes returned by the [VFS]
layer to indicate that an operation could not be completed due to the
inability to allocate sufficient memory. This error code is normally
converted into [SQLITE_NOMEM] by the higher layers of SQLite before
being returned to the application.
}
RESCODE SQLITE_IOERR_ACCESS {SQLITE_IOERR | (13<<8)} {
The SQLITE_IOERR_ACCESS error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within the xAccess method on the [sqlite3_vfs] object.
}
RESCODE SQLITE_IOERR_CHECKRESERVEDLOCK {SQLITE_IOERR | (14<<8)} {
The SQLITE_IOERR_CHECKRESERVEDLOCK error code is
an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within the xCheckReservedLock method on the [sqlite3_io_methods] object.
}
RESCODE SQLITE_IOERR_LOCK {SQLITE_IOERR | (15<<8)} {
The SQLITE_IOERR_LOCK error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error in the
advisory file locking logic.
Usually an SQLITE_IOERR_LOCK error indicates a problem obtaining
a [PENDING lock]. However it can also indicate miscellaneous
locking errors on some of the specialized [VFSes] used on Macs.
}
RESCODE SQLITE_IOERR_CLOSE {SQLITE_IOERR | (16<<8)} {
The SQLITE_IOERR_ACCESS error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within the xClose method on the [sqlite3_io_methods] object.
}
RESCODE SQLITE_IOERR_DIR_CLOSE {SQLITE_IOERR | (17<<8)} {
The SQLITE_IOERR_DIR_CLOSE error code is no longer used.
}
RESCODE SQLITE_IOERR_SHMOPEN {SQLITE_IOERR | (18<<8)} {
The SQLITE_IOERR_SHMOPEN error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within the xShmMap method on the [sqlite3_io_methods] object
while trying to open a new shared memory segment.
}
RESCODE SQLITE_IOERR_SHMSIZE {SQLITE_IOERR | (19<<8)} {
The SQLITE_IOERR_SHMSIZE error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within the xShmMap method on the [sqlite3_io_methods] object
while trying to resize an existing shared memory segment.
}
RESCODE SQLITE_IOERR_SHMLOCK {SQLITE_IOERR | (20<<8)} {
The SQLITE_IOERR_SHMLOCK error code is no longer used.
}
RESCODE SQLITE_IOERR_SHMMAP {SQLITE_IOERR | (21<<8)} {
The SQLITE_IOERR_SHMMAP error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within the xShmMap method on the [sqlite3_io_methods] object
while trying to map a shared memory segment into the process address space.
}
RESCODE SQLITE_IOERR_SEEK {SQLITE_IOERR | (22<<8)} {
The SQLITE_IOERR_SEEK error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within the xRead or xWrite methods on the [sqlite3_io_methods] object
while trying to seek a file descriptor to the beginning point of the
file where the read or write is to occur.
}
RESCODE SQLITE_IOERR_DELETE_NOENT {SQLITE_IOERR | (23<<8)} {
The SQLITE_IOERR_DELETE_NOENT error code
is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating that the
xDelete method on the [sqlite3_vfs] object failed because the
file being deleted does not exist.
}
RESCODE SQLITE_IOERR_MMAP {SQLITE_IOERR | (24<<8)} {
The SQLITE_IOERR_MMAP error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating an I/O error
within the xFetch or xUnfetch methods on the [sqlite3_io_methods] object
while trying to map or unmap part of the database file into the
process address space.
}
RESCODE SQLITE_IOERR_GETTEMPPATH {SQLITE_IOERR | (25<<8)} {
The SQLITE_IOERR_GETTEMPPATH error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] indicating that the [VFS] is unable to determine
a suitable directory in which to place temporary files.
}
RESCODE SQLITE_IOERR_CONVPATH {SQLITE_IOERR | (26<<8)} {
The SQLITE_IOERR_CONVPATH error code is an [ext-v-prim|extended error code]
for [SQLITE_IOERR] used only by Cygwin [VFS] and indicating that
the cygwin_conv_path() system call failed.
See also: [SQLITE_CANTOPEN_CONVPATH]
}
RESCODE SQLITE_LOCKED_SHAREDCACHE {SQLITE_LOCKED | (1<<8)} {
The SQLITE_LOCKED_SHAREDCACHE error code is
an [ext-v-prim|extended error code] for [SQLITE_LOCKED]
indicating that the locking conflict has occurred due to contention
with a different [database connection] that happens to hold a
[shared cache] with the database connection to which the error was
returned. For example, if the other database connection is holding
an [exclusive lock] on the database, then the database connection
that receives this error will be unable to read or write any part
of the database file unless it has the [read_uncommitted pragma]
enabled.
<p>
The SQLITE_LOCKED_SHARECACHE error code works very much like the
[SQLITE_BUSY] error code except that SQLITE_LOCKED_SHARECACHE is
for separate database connections that share a cache whereas
SQLITE_BUSY is for the much more common case of separate database
connections that do not share the same cache. Also, the
[sqlite3_busy_handler()] and [sqlite3_busy_timeout()] interfaces
do not help in resolving SQLITE_LOCKED_SHAREDCACHE conflicts.
}
RESCODE SQLITE_BUSY_RECOVERY {SQLITE_BUSY | (1<<8)} {
The SQLITE_BUSY_RECOVERY error code is an [ext-v-prim|extended error code]
for [SQLITE_BUSY] that indicates that an operation could not continue
because another process is busy recovering a [WAL mode] database file
following a crash. The SQLITE_BUSY_RECOVERY error code only occurs
on [WAL mode] databases.
}
RESCODE SQLITE_BUSY_SNAPSHOT {SQLITE_BUSY | (2<<8)} {
The SQLITE_BUSY_SNAPSHOT error code is an [ext-v-prim|extended error code]
for [SQLITE_BUSY] that occurs on [WAL mode] databases when a database
connection tries to promote a read transaction into a write transaction
but finds that another [database connection] has already written to the
database and thus invalidated prior reads.
<p>
The following scenario illustrates how an SQLITE_BUSY_SNAPSHOT error
might arise:
<ol>
<li> Process A starts a read transaction on the database and does one
or more SELECT statement. Process A keeps the transaction open.
<li> Process B updates the database, changing values previous read by
process A.
<li> Process A now tries to write to the database. But process A's view
of the database content is now obsolete because process B has
modified the database file after process A read from it. Hence
process A gets an SQLITE_BUSY_SNAPSHOT error.
</ol>
}
RESCODE SQLITE_CANTOPEN_NOTEMPDIR {SQLITE_CANTOPEN | (1<<8)} {
The SQLITE_CANTOPEN_NOTEMPDIR error code is no longer used.
}
RESCODE SQLITE_CANTOPEN_ISDIR {SQLITE_CANTOPEN | (2<<8)} {
The SQLITE_CANTOPEN_ISDIR error code is an [ext-v-prim|extended error code]
for [SQLITE_CANTOPEN] indicating that a file open operation failed because
the file is really a directory.
}
RESCODE SQLITE_CANTOPEN_FULLPATH {SQLITE_CANTOPEN | (3<<8)} {
The SQLITE_CANTOPEN_FULLPATH error code is an [ext-v-prim|extended error code]
for [SQLITE_CANTOPEN] indicating that a file open operation failed because
the operating system was unable to convert the filename into a full pathname.
}
RESCODE SQLITE_CANTOPEN_CONVPATH {SQLITE_CANTOPEN | (4<<8)} {
The SQLITE_CANTOPEN_CONVPATH error code is an [ext-v-prim|extended error code]
for [SQLITE_CANTOPEN] used only by Cygwin [VFS] and indicating that
the cygwin_conv_path() system call failed while trying to open a file.
See also: [SQLITE_IOERR_CONVPATH]
}
RESCODE SQLITE_CORRUPT_VTAB {SQLITE_CORRUPT | (1<<8)} {
The SQLITE_CORRUPT_VTAB error code is an [ext-v-prim|extended error code]
for [SQLITE_CORRUPT] used by [virtual tables]. A [virtual table] might
return SQLITE_CORRUPT_VTAB to indicate that content in the virtual table
is corrupt.
}
RESCODE SQLITE_READONLY_RECOVERY {SQLITE_READONLY | (1<<8)} {
The SQLITE_READONLY_RECOVERY error code is an [ext-v-prim|extended error code]
for [SQLITE_READONLY]. The SQLITE_READONLY_RECOVERY error code indicates
that a [WAL mode] database cannot be opened because the database file
needs to be recovered and recovery requires write access but only
read access is available.
}
RESCODE SQLITE_READONLY_CANTLOCK {SQLITE_READONLY | (2<<8)} {
The SQLITE_READONLY_CANTLOCK error code is an [ext-v-prim|extended error code]
for [SQLITE_READONLY]. The SQLITE_READONLY_CANTLOCK error code indicates
that SQLite is unable to obtain a read lock on a [WAL mode] database
because the shared-memory file associated with that database is read-only.
}
RESCODE SQLITE_READONLY_ROLLBACK {SQLITE_READONLY | (3<<8)} {
The SQLITE_READONLY_ROLLBACK error code is an [ext-v-prim|extended error code]
for [SQLITE_READONLY]. The SQLITE_READONLY_ROLLBACK error code indicates
that a database cannot be opened because it has a [hot journal] that
needs to be rolled back but cannot because the database is readonly.
}
RESCODE SQLITE_READONLY_DBMOVED {SQLITE_READONLY | (4<<8)} {
The SQLITE_READONLY_DBMOVED error code is an [ext-v-prim|extended error code]
for [SQLITE_READONLY]. The SQLITE_READONLY_DBMOVED error code indicates
that a database cannot be modified because the database file has been
moved since it was opened, and so any attempt to modify the database
might result in database corruption if the processes crashes because the
[rollback journal] would not be correctly named.
}
RESCODE SQLITE_ABORT_ROLLBACK {SQLITE_ABORT | (2<<8)} {
The SQLITE_ABORT_ROLLBACK error code is an [ext-v-prim|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.
}
RESCODE SQLITE_CONSTRAINT_CHECK {SQLITE_CONSTRAINT | (1<<8)} {
The SQLITE_CONSTRAINT_CHECK error code is an [ext-v-prim|extended error code]
for [SQLITE_CONSTRAINT] indicating that a [CHECK constraint] failed.
}
RESCODE SQLITE_CONSTRAINT_COMMITHOOK {SQLITE_CONSTRAINT | (2<<8)} {
The SQLITE_CONSTRAINT_COMMITHOOK error code
is an [ext-v-prim|extended error code]
for [SQLITE_CONSTRAINT] indicating that a
[sqlite3_commit_hook|commit hook callback] returned non-zero that thus
caused the SQL statement to be rolled back.
}
RESCODE SQLITE_CONSTRAINT_FOREIGNKEY {SQLITE_CONSTRAINT | (3<<8)} {
The SQLITE_CONSTRAINT_FOREIGNKEY error code
is an [ext-v-prim|extended error code]
for [SQLITE_CONSTRAINT] indicating that a [foreign key constraint] failed.
}
RESCODE SQLITE_CONSTRAINT_FUNCTION {SQLITE_CONSTRAINT | (4<<8)} {
The SQLITE_CONSTRAINT_FUNCTION error code is not currently used
by the SQLite core. However, this error code is available for use
by extension functions.
}
RESCODE SQLITE_CONSTRAINT_NOTNULL {SQLITE_CONSTRAINT | (5<<8)} {
The SQLITE_CONSTRAINT_NOTNULL error code
is an [ext-v-prim|extended error code]
for [SQLITE_CONSTRAINT] indicating that a [NOT NULL constraint] failed.
}
RESCODE SQLITE_CONSTRAINT_PRIMARYKEY {SQLITE_CONSTRAINT | (6<<8)} {
The SQLITE_CONSTRAINT_PRIMARYKEY error code
is an [ext-v-prim|extended error code]
for [SQLITE_CONSTRAINT] indicating that a [PRIMARY KEY constraint] failed.
}
RESCODE SQLITE_CONSTRAINT_TRIGGER {SQLITE_CONSTRAINT | (7<<8)} {
The SQLITE_CONSTRAINT_TRIGGER error code
is an [ext-v-prim|extended error code]
for [SQLITE_CONSTRAINT] indicating that a [RAISE function] within
a [CREATE TRIGGER|trigger] fired, causing the SQL statement to abort.
}
RESCODE SQLITE_CONSTRAINT_UNIQUE {SQLITE_CONSTRAINT | (8<<8)} {
The SQLITE_CONSTRAINT_UNIQUE error code
is an [ext-v-prim|extended error code]
for [SQLITE_CONSTRAINT] indicating that a [UNIQUE constraint] failed.
}
RESCODE SQLITE_CONSTRAINT_VTAB {SQLITE_CONSTRAINT | (9<<8)} {
The SQLITE_CONSTRAINT_VTAB error code is not currently used
by the SQLite core. However, this error code is available for use
by application-defined [virtual tables].
}
RESCODE SQLITE_CONSTRAINT_ROWID {SQLITE_CONSTRAINT |(10<<8)} {
The SQLITE_CONSTRAINT_ROWID error code
is an [ext-v-prim|extended error code]
for [SQLITE_CONSTRAINT] indicating that a [rowid] is not unique.
}
RESCODE SQLITE_NOTICE_RECOVER_WAL {SQLITE_NOTICE | (1<<8)} {
The SQLITE_NOTICE_RECOVER_WAL result code is
passed to the callback of
[sqlite3_log()] when a [WAL mode] database file is recovered.
}
RESCODE SQLITE_NOTICE_RECOVER_ROLLBACK {SQLITE_NOTICE | (2<<8)} {
The SQLITE_NOTICE_RECOVER_ROLLBACK result code is
passed to the callback of
[sqlite3_log()] when a [hot journal] is rolled back.
}
RESCODE SQLITE_WARNING_AUTOINDEX {SQLITE_WARNING | (1<<8)} {
The SQLITE_WARNING_AUTOINDEX result code is
passed to the callback of
[sqlite3_log()] whenever [automatic indexing] is used.
This can serve as a warning to application designers that the
database might benefit from additional indexes.
}
#############################################################################
# Code to process the RESCODE values
#
# Convert formula RESCODE values into numerics
set nResCode 0
set nPrimCode 0
set nExtCode 0
set nNonError 3
unset -nocomplain prim_rc
unset -nocomplain ext_rc
foreach name [array names resvalue] {
set val $resvalue($name)
if {[regexp {^(SQLITE_[^ ]+) *\| *\((\d+)<<8\)$} $val all basename hival]} {
set val [expr {$resvalue($basename)+($hival<<8)}]
set resvalue($name) $val
}
set valtoname($val) $name
incr nResCode
if {$val<256} {
incr nPrimCode
set prim_rc($name) $val
} else {
incr nExtCode
set ext_rc($name) $val
}
}
hd_puts "<h2>Primary Result Code List</h2>\n"
hd_puts "<p>The $nPrimCode result codes"
</tcl>
are [result code definitions|defined in sqlite3.h] and are
listed in alphabetical order below:
<table border=0 width="100%" cellpadding=10>
<tr><td valign="top" align="left"><ul>
<tcl>
set nrow [expr {($nPrimCode+2)/3}]
set i 0
foreach name [lsort [array names prim_rc]] {
if {$i==$nrow} {
hd_puts "</ul></td><td valign=\"top\" align=\"left\"><ul>\n"
set i 0
}
incr i
hd_resolve "<li> \[$name\] ($prim_rc($name))\n"
}
hd_puts "</td></td></table>\n\n"
hd_fragment extrc {extended result code} {extended result codes} \
{extended error code} {extended error codes}
hd_puts "<h2>Extended Result Code List</h2>\n"
hd_puts "<p>The $nExtCode extended result codes"
</tcl>
are [extended result code definitions|defined in sqlite3.h] and are
listed in alphabetical order below:
<table border=0 width="100%" cellpadding=10>
<tr><td valign="top" align="left"><ul>
<tcl>
set nrow [expr {($nExtCode+1)/2}]
set i 0
foreach name [lsort [array names ext_rc]] {
if {$i==$nrow} {
hd_puts "</ul></td><td valign=\"top\" align=\"left\"><ul>\n"
set i 0
}
incr i
hd_resolve "<li> \[$name\] ($ext_rc($name))\n"
}
hd_puts "</td></td></table>\n\n"
hd_puts "
<h2>Result Code Meanings</h2>
<p>
The meanings for all $nResCode result code values are shown below,
in numeric order.
"
# Generate the table of result codes
#
foreach val [lsort -int [array names valtoname]] {
set name $valtoname($val)
regsub {sqlite_} [string tolower $name] {} tag
hd_puts "<!--------------------------------------------------------------->\n"
hd_fragment $tag --override $name
hd_puts "<h3>($val) $valtoname($val)</h3>\n"
hd_resolve $resdesc($name)\n\n
}
</tcl>