3. 定义

所有结果代码都是整数。所有结果代码的符号名称都是使用 sqlite3.h 头文件中的“#define”宏创建的。 sqlite3.h 头文件中有单独的部分用于结果代码定义和扩展结果代码定义。主要结果代码符号名称的格式为“SQLITE_XXXXXX”，其中 XXXXXX 是一系列大写字母字符。扩展结果代码名称的格式为“SQLITE_XXXXXX_YYYYYYY”，其中XXXXXX部分是对应的主要结果代码，YYYYYYY是对结果代码进一步分类的扩展。现有结果代码的名称和数值是固定不变的。但是，新的结果代码，尤其是新的扩展结果代码，可能会出现在 SQLite 的未来版本中。

4. 主要结果代码列表

sqlite3.h 中定义了 31 个结果代码，下面按字母顺序列出：

SQLITE_ABORT (4)

SQLITE_AUTH (23)

SQLITE_BUSY (5)

SQLITE_CANTOPEN (14)

SQLITE_CONSTRAINT (19)

SQLITE_CORRUPT (11)

SQLITE_DONE (101)

SQLITE_EMPTY (16)

SQLITE_ERROR (1)

SQLITE_FORMAT (24)

SQLITE_FULL (13)

SQLITE_INTERNAL (2)

SQLITE_INTERRUPT (9)

SQLITE_IOERR (10)

SQLITE_LOCKED (6)

SQLITE_MISMATCH (20)

SQLITE_MISUSE (21)

SQLITE_NOLFS (22)

SQLITE_NOMEM (7)

SQLITE_NOTADB (26)

SQLITE_NOTFOUND (12)

SQLITE_NOTICE (27)

SQLITE_OK (0)

SQLITE_PERM (3)

SQLITE_PROTOCOL (15)

SQLITE_RANGE (25)

SQLITE_READONLY (8)

SQLITE_ROW (100)

SQLITE_SCHEMA (17)

SQLITE_TOOBIG (18)

SQLITE_WARNING (28)

SQLITE_CANTOPEN_CONVPATH (1038)

SQLITE_CANTOPEN_DIRTYWAL (1294)

SQLITE_CANTOPEN_FULLPATH (782)

SQLITE_CANTOPEN_ISDIR (526)

SQLITE_CANTOPEN_NOTEMPDIR (270)

SQLITE_CANTOPEN_SYMLINK (1550)

SQLITE_CONSTRAINT_CHECK (275)

SQLITE_CONSTRAINT_COMMITHOOK (531)

SQLITE_CONSTRAINT_DATATYPE (3091)

SQLITE_CONSTRAINT_FOREIGNKEY (787)

SQLITE_CONSTRAINT_FUNCTION (1043)

SQLITE_CONSTRAINT_NOTNULL (1299)

SQLITE_CONSTRAINT_PINNED (2835)

SQLITE_CONSTRAINT_PRIMARYKEY (1555)

SQLITE_CONSTRAINT_ROWID (2579)

SQLITE_CONSTRAINT_TRIGGER (1811)

SQLITE_CONSTRAINT_UNIQUE (2067)

SQLITE_CONSTRAINT_VTAB (2323)

SQLITE_CORRUPT_INDEX (779)

SQLITE_CORRUPT_SEQUENCE (523)

SQLITE_CORRUPT_VTAB (267)

SQLITE_ERROR_MISSING_COLLSEQ (257)

SQLITE_ERROR_RETRY (513)

SQLITE_ERROR_SNAPSHOT (769)

SQLITE_IOERR_ACCESS (3338)

SQLITE_IOERR_AUTH (7178)

SQLITE_IOERR_BEGIN_ATOMIC (7434)

SQLITE_IOERR_BLOCKED (2826)

SQLITE_IOERR_CHECKRESERVEDLOCK (3594)

SQLITE_IOERR_CLOSE (4106)

SQLITE_IOERR_COMMIT_ATOMIC (7690)

SQLITE_IOERR_CONVPATH (6666)

SQLITE_IOERR_CORRUPTFS (8458)

SQLITE_IOERR_DATA (8202)

SQLITE_IOERR_DELETE (2570)

SQLITE_IOERR_DELETE_NOENT (5898)

SQLITE_IOERR_DIR_CLOSE (4362)

SQLITE_IOERR_DIR_FSYNC (1290)

SQLITE_IOERR_FSTAT (1802)

SQLITE_IOERR_FSYNC (1034)

SQLITE_IOERR_GETTEMPPATH (6410)

SQLITE_IOERR_LOCK (3850)

SQLITE_IOERR_MMAP (6154)

SQLITE_IOERR_NOMEM (3082)

SQLITE_IOERR_RDLOCK (2314)

SQLITE_IOERR_READ (266)

SQLITE_IOERR_ROLLBACK_ATOMIC (7946)

SQLITE_IOERR_SEEK (5642)

SQLITE_IOERR_SHMLOCK (5130)

SQLITE_IOERR_SHMMAP (5386)

SQLITE_IOERR_SHMOPEN (4618)

SQLITE_IOERR_SHMSIZE (4874)

SQLITE_IOERR_SHORT_READ (522)

SQLITE_IOERR_TRUNCATE (1546)

SQLITE_IOERR_UNLOCK (2058)

SQLITE_IOERR_VNODE (6922)

SQLITE_IOERR_WRITE (778)

SQLITE_LOCKED_SHAREDCACHE (262)

SQLITE_LOCKED_VTAB (518)

SQLITE_NOTICE_RECOVER_ROLLBACK (539)

SQLITE_NOTICE_RECOVER_WAL (283)

SQLITE_OK_LOAD_PERMANENTLY (256)

SQLITE_READONLY_CANTINIT (1288)

SQLITE_READONLY_CANTLOCK (520)

SQLITE_READONLY_DBMOVED (1032)

SQLITE_READONLY_DIRECTORY (1544)

SQLITE_READONLY_RECOVERY (264)

SQLITE_READONLY_ROLLBACK (776)

SQLITE_WARNING_AUTOINDEX (284)

六、结果码含义

所有 105 个结果代码值的含义如下所示，按数字顺序排列。

(0) SQLITE_OK

SQLITE_OK 结果代码表示操作成功并且没有错误。大多数其他结果代码表示错误。

(2) SQLITE_INTERNAL

SQLITE_INTERNAL 结果代码表示内部故障。在 SQLite 的工作版本中，应用程序永远不会看到此结果代码。如果应用程序确实遇到此结果代码，则表明数据库引擎中存在错误。 SQLite 当前不生成此结果代码。但是，应用程序定义的 SQL 函数或虚拟表、 VFSes 或其他扩展可能会导致返回此结果代码。 SQLITE_ABORT 结果代码表示操作在完成之前被中止，通常是应用程序请求。另请参阅： SQLITE_INTERRUPT 。

如果sqlite3_exec() 的回调函数返回非零值，则 sqlite3_exec() 将返回 SQLITE_ABORT。如果 ROLLBACK 操作发生在与挂起的读取或写入相同的数据库连接上，则挂起的读取或写入可能会失败并出现 SQLITE_ABORT 或 SQLITE_ABORT_ROLLBACK 错误。除了作为结果代码，SQLITE_ABORT 值还用作从 sqlite3_vtab_on_conflict() 接口返回的冲突解决模式。

(5) SQLITE_BUSY

SQLITE_BUSY 结果代码表示由于某些其他数据库连接（通常是单独进程中的数据库连接）的并发活动，无法写入（或在某些情况下读取）数据库文件。

例如，如果进程 A 正在处理一个大型写事务，同时进程 B 尝试启动一个新的写事务，则进程 B 将返回一个 SQLITE_BUSY 结果，因为 SQLite 一次只支持一个写入器。在开始新事务之前，进程 B 需要等待进程 A 完成其事务。 sqlite3_busy_timeout ( ) 和 sqlite3_busy_handler() 接口以及 busy_timeout pragma 可用于进程 B 以帮助它处理 SQLITE_BUSY 错误。 SQLITE_BUSY 错误可能发生在事务中的任何时候：事务首次启动时、任何写入或更新操作期间或事务提交时。为了避免在事务中间遇到 SQLITE_BUSY 错误，应用程序可以使用 BEGIN IMMEDIATE 而不是仅仅使用 BEGIN 来启动事务。 BEGIN IMMEDIATE 命令本身可能返回 SQLITE_BUSY，但如果成功，则 SQLite 保证通过下一个 COMMIT 对同一数据库的后续操作不会返回 SQLITE_BUSY。另请参阅： SQLITE_BUSY_RECOVERY 和 SQLITE_BUSY_SNAPSHOT 。 SQLITE_BUSY 结果代码与 SQLITE_LOCKED 的不同之处在于，SQLITE_BUSY 表示与单独的数据库连接发生冲突，可能在单独的进程中，而 SQLITE_LOCKED 表示在同一数据库连接（或有时与共享缓存的数据库连接）内发生冲突。例如，当另一个线程正在同一数据库连接上读取该表时，不能运行 DROP TABLE 语句，因为删除该表会将该表从并发读取器中删除。 SQLITE_LOCKED 结果代码与SQLITE_BUSY 的不同之处在于， SQLITE_LOCKED 表示在同一数据库连接（或与共享缓存的连接）上发生冲突，而 SQLITE_BUSY 表示与不同的数据库连接发生冲突，可能在不同的进程中。 SQLITE_IOERR 结果代码表示操作无法完成，因为操作系统报告了 I/O 错误。完整的磁盘驱动器通常会给出 SQLITE_FULL 错误而不是 SQLITE_IOERR 错误。 I/O 错误有许多不同的扩展结果代码，用于标识失败的特定 I/O 操作。 SQLITE_NOTFOUND 可以由 sqlite3_file_control() 接口返回，以指示作为第三个参数传递的文件控制操作码未被底层 VFS 识别。 SQLITE_NOTFOUND 也可以由 sqlite3_vfs 对象的 xSetSystemCall() 方法返回。 SQLITE_NOTFOUND 由 sqlite3_vtab_rhs_value() 返回，表示约束的右侧操作数不可用于进行调用的 xBestIndex 方法。 SQLITE_NOTFOUND 结果代码也由 SQLite 实现在内部使用，但这些内部使用不会暴露给应用程序。

（13）SQLITE_FULL

SQLITE_FULL 结果代码表示写入无法完成，因为磁盘已满。请注意，尝试将信息写入主数据库文件时可能会发生此错误，也可能会在写入临时磁盘文件时发生。有时即使主磁盘空间充足，应用程序也会遇到此错误，因为在临时文件存储在空间比主磁盘少得多的单独分区上的系统上写入临时磁盘文件时会发生错误。

(14) SQLITE_CANTOPEN

SQLITE_CANTOPEN 结果代码表示 SQLite 无法打开文件。有问题的文件可能是主数据库文件或几个临时磁盘文件之一。

(15) SQLITE_PROTOCOL

SQLITE_PROTOCOL 结果代码表示 SQLite 使用的文件锁定协议存在问题。 SQLITE_PROTOCOL 错误当前仅在使用 WAL 模式并尝试启动新事务时返回。当两个单独的数据库连接都尝试在 WAL 模式下同时启动事务时，可能会出现竞争条件 . 比赛的失败者在短暂的延迟后退出并再次尝试。如果同一个连接在几秒内多次失去锁定竞争，它最终会放弃并返回 SQLITE_PROTOCOL。 SQLITE_PROTOCOL 错误在实践中应该非常、非常少地出现，并且只有在有许多单独的进程都在激烈竞争写入同一个数据库时才会出现。 SQLITE_SCHEMA 结果代码表示数据库模式已更改。对于使用sqlite3_prepare() 或 sqlite3_prepare16() 生成的准备好的语句，可以从 sqlite3_step() 返回此结果代码。如果数据库模式在语句准备和语句运行之间被其他进程更改，则可能会导致此错误。如果从 sqlite3_prepare_v2() 生成准备好的语句，那么如果模式更改，语句将自动重新准备，最多 SQLITE_MAX_SCHEMA_RETRY 次（默认值：50）。如果多次重试后失败仍然存在， sqlite3_step() 接口只会将 SQLITE_SCHEMA 返回给应用程序。

（18）SQLITE_TOOBIG

SQLITE_TOOBIG 错误代码表示字符串或 BLOB 太大。 SQLite 中字符串或 BLOB 的默认最大长度为 1,000,000,000 字节。这个最大长度可以在编译时使用 SQLITE_MAX_LENGTH 编译时选项更改，或者在运行时使用 sqlite3_limit (db, SQLITE_LIMIT_LENGTH ,...) 接口更改。当 SQLite 遇到超过编译时或运行时限制的字符串或 BLOB 时，将导致 SQLITE_TOOBIG 错误。

当将过大的 SQL 语句传递到sqlite3_prepare_v2() 接口之一时，也会导致 SQLITE_TOOBIG 错误代码。 SQL 语句的最大长度默认为 1,000,000,000 字节的小得多的值。最大 SQL 语句长度可以在编译时使用 SQLITE_MAX_SQL_LENGTH 或在运行时使用 sqlite3_limit (db, SQLITE_LIMIT_SQL_LENGTH ,...) 设置。

(19) SQLITE_CONSTRAINT

SQLITE_CONSTRAINT 错误代码表示在尝试处理 SQL 语句时发生了 SQL 约束冲突。通过查阅随附的错误消息（通过sqlite3_errmsg() 或 sqlite3_errmsg16() 返回）或查看扩展错误代码，可以找到有关失败约束的其他信息。 SQLITE_CONSTRAINT 代码也可以用作虚拟表实现的 xBestIndex() 方法的返回值。当 xBestIndex() 返回 SQLITE_CONSTRAINT 时，表示提交给 xBestIndex() 的特定输入组合无法生成可用的查询计划，不应进一步考虑。 SQLITE_MISMATCH 错误代码表示数据类型不匹配。 SQLite 通常对值的类型与存储该值的容器的声明类型之间的不匹配非常宽容。例如，SQLite 允许应用程序将大型 BLOB 存储在声明类型为 BOOLEAN 的列中。但在少数情况下，SQLite 对类型很严格。在类型不匹配的少数情况下，会返回 SQLITE_MISMATCH 错误。表的 rowid 必须是一个整数。尝试将 rowid 设置为整数以外的任何值（或将自动转换为下一个可用整数 rowid 的 NULL）会导致 SQLITE_MISMATCH 错误。

(21) SQLITE_MISUSE

如果应用程序以未定义或不受支持的方式使用任何 SQLite 接口，则可能会返回 SQLITE_MISUSE 返回码。例如，在准备好的语句完成后使用准备好的语句可能会导致 SQLITE_MISUSE 错误。 SQLite 尝试使用此结果代码检测误用并报告误用。但是，不能保证滥用检测一定会成功。误用检测是概率性的。应用程序不应该依赖于 SQLITE_MISUSE 返回值。如果 SQLite 从任何接口返回 SQLITE_MISUSE，这意味着应用程序编码不正确，需要修复。不要发布有时会从标准 SQLite 接口返回 SQLITE_MISUSE 的应用程序，因为该应用程序包含潜在的严重错误。

sqlite3_load_extension() 接口将扩展加载到单个数据库连接中。默认行为是在数据库连接关闭时自动卸载该扩展。但是，如果扩展入口点返回 SQLITE_OK_LOAD_PERMANENTLY 而不是 SQLITE_OK，那么在数据库连接关闭后扩展仍然加载到进程地址空间中。换句话说，当数据库连接关闭时，不会为扩展调用 sqlite3_vfs对象的 xDlClose 方法。

例如，SQLITE_OK_LOAD_PERMANENTLY 返回码对于注册新 VFSes的可加载扩展很有用。

【257】SQLITE_ERROR_MISSING_COLLSEQ

SQLITE_ERROR_MISSING_COLLSEQ 结果代码意味着无法准备 SQL 语句，因为无法找到该 SQL 语句中命名的整理序列。有时遇到此错误代码时， sqlite3_prepare_v2() 例程会将错误转换为 SQLITE_ERROR_RETRY 并再次尝试使用不需要使用未知整理顺序的不同查询计划来准备 SQL 语句。 SQLITE_READONLY_RECOVERY 错误代码是 SQLITE_READONLY 的扩展错误代码。 SQLITE_READONLY_RECOVERY错误码表示无法打开 WAL模式的数据库，因为需要恢复数据库文件，恢复需要写权限，但只有读权限可用。

【266】SQLITE_IOERR_READ

SQLITE_IOERR_READ 错误代码是 SQLITE_IOERR 的扩展错误代码，指示尝试从磁盘上的文件读取时 VFS 层中的 I/O 错误。此错误可能是由于硬件故障或文件系统在文件打开时被卸载引起的。 SQLITE_ABORT_ROLLBACK 错误代码是 SQLITE_ABORT 的扩展错误代码，指示 SQL 语句中止，因为 SQL 语句首次启动时处于活动状态的事务被回滚。当发生回滚时，挂起的写操作总是失败并出现此错误。仅当模式在被回滚的事务中更改时， ROLLBACK才会导致挂起的读取操作失败。

(517) SQLITE_BUSY_SNAPSHOT

SQLITE_BUSY_SNAPSHOT 错误代码是 SQLITE_BUSY 的扩展错误代码，当数据库连接试图将读取事务提升为写入事务但发现另一个数据库连接已写入数据库并因此使先前的读取无效时，它会在 WAL 模式数据库上发生。

以下场景说明了如何出现 SQLITE_BUSY_SNAPSHOT 错误：

进程 A 在数据库上启动读取事务并执行一个或多个 SELECT 语句。进程 A 保持事务打开。

进程 B 更新数据库，更改进程 A 先前读取的值。

进程 A 现在尝试写入数据库。但是进程 A 的数据库内容视图现在已经过时，因为进程 B 在进程 A 读取数据库文件后修改了它。因此进程 A 收到 SQLITE_BUSY_SNAPSHOT 错误。

【518】SQLITE_LOCKED_VTAB

SQLITE_LOCKED_VTAB 结果代码不被 SQLite 核心使用，但它可供扩展使用。虚拟表实现可以返回此结果代码以指示它们由于其他线程或进程持有的锁而无法完成当前操作。当尝试更新 R-Tree 而另一个准备好的语句正在主动读取 R-Tree 时， R-Tree 扩展返回此结果代码。更新无法继续，因为对 R-Tree 的任何更改都可能涉及节点的重新洗牌和重新平衡，这会破坏读取游标，导致重复某些行并省略其他行。

【523】SQLITE_CORRUPT_SEQUENCE

SQLITE_CORRUPT_SEQUENCE 结果代码表示 sqlite_sequence 表的模式已损坏。 sqlite_sequence 表用于帮助实现 AUTOINCREMENT 功能。 sqlite_sequence 表应具有以下格式：

CREATE TABLE sqlite_sequence(name,seq);

如果 SQLite 发现 sqlite_sequence 表有任何其他格式，它会返回 SQLITE_CORRUPT_SEQUENCE 错误。

(531) SQLITE_CONSTRAINT_COMMITHOOK

SQLITE_CONSTRAINT_COMMITHOOK 错误代码是 SQLITE_CONSTRAINT 的扩展错误代码提交挂钩回调返回非零值，从而导致 SQL 语句回滚。 SQLITE_READONLY_ROLLBACK 错误代码是 SQLITE_READONLY 的扩展错误代码。SQLITE_READONLY_ROLLBACK 错误代码表示无法打开数据库，因为它有一个需要回滚的热日志，但不能打开，因为数据库是只读的。

(778) SQLITE_IOERR_WRITE

SQLITE_IOERR_WRITE 错误代码是 SQLITE_IOERR 的扩展错误代码，指示在尝试写入磁盘上的文件时VFS层中的 I/O 错误。此错误可能是由于硬件故障或文件系统在文件打开时被卸载引起的。如果文件系统已满，则不应发生此错误，因为为此目的有一个单独的错误代码 (SQLITE_FULL)。

【787】SQLITE_CONSTRAINT_FOREIGNKEY

SQLITE_CONSTRAINT_FOREIGNKEY 错误代码是 SQLITE_CONSTRAINT 的扩展错误代码，表示外键约束失败。 SQLITE_READONLY_DBMOVED 错误代码是 SQLITE_READONLY 的扩展错误代码。SQLITE_READONLY_DBMOVED 错误代码表示无法修改数据库，因为数据库文件在打开后已被移动，因此如果进程崩溃，则任何修改数据库的尝试都可能导致数据库损坏，因为回滚日志不会被正确命名。

【1288】SQLITE_READONLY_CANTINIT

SQLITE_READONLY_CANTINIT结果码来源于VFS的xShmMap方法，表示WAL模式使用的共享内存区存在，但由于当前进程没有共享内存区的写权限，其内容不可靠，无法被当前进程使用。（WAL 模式的共享内存区域通常是一个映射到进程空间的带有“-wal”后缀的文件。如果当前进程对该文件没有写权限，那么它不能写入共享内存。） SQLite 中更高级别的逻辑通常会拦截错误代码并创建一个临时的内存共享内存区域，以便当前进程至少可以读取数据库的内容。此结果代码不应到达应用程序接口层。

【1299】SQLITE_CONSTRAINT_NOTNULL

SQLITE_CONSTRAINT_NOTNULL 错误代码是 SQLITE_CONSTRAINT 的扩展错误代码，表示NOT NULL 约束失败。

【1555】SQLITE_CONSTRAINT_PRIMARYKEY

SQLITE_CONSTRAINT_PRIMARYKEY 错误代码是 SQLITE_CONSTRAINT 的扩展错误代码，指示PRIMARY KEY 约束失败。 SQLITE_IOERR_FSTAT 错误代码是 SQLITE_IOERR 的扩展错误代码，指示在尝试调用文件上的 fstat()（或等效函数）以确定文件大小或访问权限等信息时 VFS层中的 I/O 错误。

（1811）SQLITE_CONSTRAINT_TRIGGER

SQLITE_CONSTRAINT_TRIGGER 错误代码是 SQLITE_CONSTRAINT 的扩展错误代码，表示触发了触发器中的RAISE 函数，导致 SQL 语句中止。

【3091】SQLITE_CONSTRAINT_DATATYPE

SQLITE_CONSTRAINT_DATATYPE 错误代码是 SQLITE_CONSTRAINT 的扩展错误代码，指示插入或更新尝试将与列声明类型不一致的值存储在定义为 STRICT 的表中。

【3594】SQLITE_IOERR_CHECKRESERVEDLOCK

SQLITE_IOERR_CHECKRESERVEDLOCK 错误代码是 SQLITE_IOERR 的扩展错误代码，指示sqlite3_io_methods对象上的 xCheckReservedLock 方法中的 I/O 错误。

（3850）SQLITE_IOERR_LOCK

SQLITE_IOERR_LOCK 错误代码是 SQLITE_IOERR 的扩展错误代码，指示咨询文件锁定逻辑中的 I/O 错误。通常 SQLITE_IOERR_LOCK 错误表示获取PENDING 锁时出现问题。但是，它也可以指示 Mac 上使用的某些专用VFS上的杂项锁定错误。 SQLITE_IOERR_SHMSIZE 错误代码是 SQLITE_IOERR 的扩展错误代码，指示sqlite3_io_methods对象上的 xShmMap 方法内的 I/O 错误，同时尝试将“shm”文件作为 WAL 模式事务处理的一部分进行放大。此错误可能表明底层文件系统卷空间不足。