SQLite 核心错误码完整列表及含义解析

什么是 SQLite 状态码

SQLite 作为一个轻量级嵌入式数据库引擎，其底层函数调用均通过整数返回值来反馈执行结果。这些值通常定义为宏常量，最高位（bit 31）用于指示是否为错误。理解这些代码有助于在日志分析或调试过程中迅速判断故障根源，例如区分是因为权限不足还是磁盘空间已满导致的操作失败。

标准状态码对照表

以下列表涵盖了 sqlite3.h 头文件中定义的主要状态码。实际开发中，最常遇到的是前 26 个错误码以及 SQLITE_ROW 和 SQLITE_DONE 两个迭代状态。

#define SQLITE_OK       0     /* 成功 | Successful result */
/* 错误码开始 */
#define SQLITE_ERROR    1     /* SQL错误 或 丢失数据库 | SQL error or missing database */
#define SQLITE_INTERNAL 2     /* SQLite 内部逻辑错误 | Internal logic error in SQLite */
#define SQLITE_PERM     3     /* 拒绝访问 | Access permission denied */
#define SQLITE_ABORT    4     /* 回调函数请求取消操作 | Callback routine requested an abort */
#define SQLITE_BUSY     5     /* 数据库文件被锁定 | The database file is locked */
#define SQLITE_LOCKED   6     /* 数据库中的一个表被锁定 | A table in the database is locked */
#define SQLITE_NOMEM    7     /* 某次 malloc() 函数调用失败 | A malloc() failed */
#define SQLITE_READONLY 8     /* 尝试写入一个只读数据库 | Attempt to write a readonly database */
#define SQLITE_INTERRUPT 9    /* 操作被 sqlite3_interrupt() 函数中断 | Operation terminated by sqlite3_interrupt() */
#define SQLITE_IOERR    10    /* 发生某些磁盘 I/O 错误 | Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT  11    /* 数据库磁盘映像不正确 | The database disk image is malformed */
#define SQLITE_NOTFOUND 12    /* sqlite3_file_control() 中出现未知操作数 | Unknown opcode in sqlite3_file_control() */
#define SQLITE_FULL     13    /* 因为数据库满导致插入失败 | Insertion failed because database is full */
#define SQLITE_CANTOPEN 14    /* 无法打开数据库文件 | Unable to open the database file */
#define SQLITE_PROTOCOL 15    /* 数据库锁定协议错误 | Database lock protocol error */
#define SQLITE_EMPTY    16    /* 数据库为空 | Database is empty */
#define SQLITE_SCHEMA   17    /* 数据结构发生改变 | The database schema changed */
#define SQLITE_TOOBIG   18    /* 字符串或二进制数据超过大小限制 | String or BLOB exceeds size limit */
#define SQLITE_CONSTRAINT 19  /* 由于约束违例而取消 | Abort due to constraint violation */
#define SQLITE_MISMATCH 20    /* 数据类型不匹配 | Data type mismatch */
#define SQLITE_MISUSE   21    /* 不正确的库使用 | Library used incorrectly */
#define SQLITE_NOLFS    22    /* 使用了操作系统不支持的功能 | Uses OS features not supported on host */
#define SQLITE_AUTH     23    /* 授权失败 | Authorization denied */
#define SQLITE_FORMAT   24    /* 附加数据库格式错误 | Auxiliary database format error */
#define SQLITE_RANGE    25    /* 传递给sqlite3_bind()的第二个参数超出范围 | 2nd parameter to sqlite3_bind out of range */
#define SQLITE_NOTADB   26    /* 被打开的文件不是一个数据库文件 | File opened that is not a database file */
#define SQLITE_ROW      100   /* sqlite3_step() 已经产生一个行结果 | sqlite3_step() has another row ready */
#define SQLITE_DONE     101   /* sqlite3_step() 完成执行操作 | sqlite3_step() has finished executing */
/* 错误码结束 */

第1步：识别基础成功与通用错误

在处理查询语句时，开发者首先需关注 SQLITE_OK 表示正常执行。若涉及预编译语句（Prepared Statement）的行提取循环，SQLITE_ROW 表示还有数据可读，而 SQLITE_DONE 表示语句执行完毕且无更多数据。通用的 SQLITE_ERROR (1) 通常出现在 SQL 语法错误或引用的数据库文件丢失时。

第2步：诊断并发与锁定问题

在多进程或多线程环境下，高频率出现的错误码往往与锁定机制有关。SQLITE_BUSY (5) 表明其他连接正在持有写锁，数据库当前不可用；SQLITE_LOCKED (6) 则更具体地指出某个特定表已被锁定。此时应检查应用是否未正确释放事务，或适当延长重试等待时间。

第3步：排查文件系统与硬件异常

当错误码指向外部存储环境时，需重点检查系统层面。SQLITE_IOERR (10) 代表磁盘读写失败，SQLITE_CORRUPT (11) 暗示文件头损坏或碎片化严重，而 SQLITE_CANTOPEN (14) 则是路径错误或权限不足导致无法创建/打开文件。此外，SQLITE_FULL (13) 提醒用户检查配额限制，SQLITE_NOMEM (7) 则直接关联内存耗尽问题。

第4步：验证数据完整性与约束

业务逻辑层面的错误常由数据本身引起。SQLITE_CONSTRAINT (19) 是最常见的业务阻断，通常由主键冲突、唯一索引限制或非空约束触发。SQLITE_TOOBIG (18) 警告数据长度超过设定上限，而 SQLITE_MISMATCH (20) 则表示类型转换失败。若发生 SQLITE_SCHEMA (17)，说明表结构在事务进行中发生了变更，可能导致当前预编译语句失效。

总结

掌握上述 SQLite 错误码能显著提升本地数据库应用的稳定性。建议在实际项目中结合日志系统将具体错误码映射为人类可读的消息。以上就是 SQLite 核心错误码整理的详细内容，更多关于 SQLite 编程优化的资料请关注本站其它相关文章！