要操作一個數據庫,先得拿到它的句柄。這個詞聽著抽象,其實不必糾結叫法,關鍵是搞清楚它是什麼。
句柄在很多場景都出現過,最常見的是文件句柄:想讀寫一個文件,先取得它的句柄。句柄本質上是一個描述性的結構體,裡面可能記錄著對象的位置、大小、類型等信息。有了這份描述,程序就能定位到目標並對它下指令。
一句話概括:句柄就是描述某個對象的結構體。
先看 SQLite 的句柄定義(初次看到不必細讀,跳過也無妨):
struct sqlite3 {
sqlite3_vfs *pVfs; /* OS Interface */
int nDb; /* Number of backends currently in use */
Db *aDb; /* All backends */
int flags; /* Miscellaneous flags */
unsigned int openFlags; /* Flags passed to sqlite3_vfs.xOpen() */
int errCode; /* Most recent error code (SQLITE_*) */
u8 autoCommit; /* The auto-commit flag */
u8 temp_store; /* 1: file 2: memory 0: default */
u8 mallocFailed; /* True if we have seen a malloc failure */
signed char nextAutovac; /* Autovac setting after VACUUM */
int nTable; /* Number of tables in the database */
CollSeq *pDfltColl; /* The default collating sequence (BINARY) */
i64 lastRowid; /* ROWID of most recent insert */
u32 magic; /* Magic number for detect library misuse */
int nChange; /* Value returned by sqlite3_changes() */
int nTotalChange; /* Value returned by sqlite3_total_changes() */
sqlite3_mutex *mutex; /* Connection mutex */
int aLimit[SQLITE_N_LIMIT]; /* Limits */
char *zErrMsg; /* Most recent error message (UTF-8) */
Lookaside lookaside; /* Lookaside malloc configuration */
BusyHandler busyHandler; /* Busy callback */
int busyTimeout; /* Busy handler timeout, in msec */
Savepoint *pSavepoint; /* List of active savepoints */
/* ……後略,還有大量內部字段 */
};
typedef struct sqlite3 sqlite3;
這個龐大的結構體描述的就是磁盤上的一個數據庫文件。持有它,就能對數據庫下達各種指令。內部細節可以暫時不管,先把 API 用對再說。
所以,操作 SQLite 的第一步永遠是創建句柄:
sqlite3 *pdb;
一行搞定。此後所有針對數據庫的操作,都離不開這個指針。
問題來了:我們只是聲明了一個指向 sqlite3 結構體的指針,裡面的內容全是空的或默認值,怎麼知道它對應磁盤上哪個文件?接下來要做的是讓 SQLite 幫我們申請內存並填充這個結構體。顯然手動填充是不現實的,我們只需要提供最基本的線索,其餘交給 API。
而這唯一的線索,就是數據庫文件的路徑。
SQLITE_API int sqlite3_open(
const char *zFilename, /* 數據庫文件路徑 */
sqlite3 **ppDb /* 二級指針,用來回傳句柄 */
);
注意第二個參數是二級指針,而我們聲明的是一級指針,所以調用時需要取地址:
int ret = sqlite3_open(getFilePath(), &pdb);
這個函數的語義其實很樸素:文件存在就打開,不存在就創建。調用完成後,數據庫與句柄 pdb 就綁定在了一起,後續所有操作都通過 pdb 進行。
路徑建議封裝成獨立函數,這符合「一個函數只做一件事」的原則,後續遷移或改動路徑時只改一處:
const char* getFilePath() {
return [[NSString stringWithFormat:@"%@/Documents/db", NSHomeDirectory()] UTF8String];
}
sqlite3_open 的返回值用來判斷是否成功。SQLite 為我們預定義了一批宏:
#define SQLITE_OK 0 /* 成功 */
#define SQLITE_ERROR 1 /* SQL 錯誤或數據庫缺失 */
#define SQLITE_INTERNAL 2 /* SQLite 內部邏輯錯誤 */
#define SQLITE_PERM 3 /* 訪問權限被拒 */
#define SQLITE_ABORT 4 /* 回調請求中止 */
#define SQLITE_BUSY 5 /* 數據庫文件被鎖定 */
#define SQLITE_LOCKED 6 /* 數據庫中的表被鎖定 */
#define SQLITE_NOMEM 7 /* malloc 失敗 */
#define SQLITE_READONLY 8 /* 嘗試寫入只讀數據庫 */
#define SQLITE_INTERRUPT 9 /* 操作被 sqlite3_interrupt() 終止 */
#define SQLITE_IOERR 10 /* 磁盤 I/O 錯誤 */
#define SQLITE_CORRUPT 11 /* 數據庫映像損壞 */
#define SQLITE_NOTFOUND 12 /* 未知操作碼 */
#define SQLITE_FULL 13 /* 數據庫已滿 */
#define SQLITE_CANTOPEN 14 /* 無法打開數據庫文件 */
#define SQLITE_PROTOCOL 15 /* 鎖定協議錯誤 */
#define SQLITE_EMPTY 16 /* 數據庫為空 */
#define SQLITE_SCHEMA 17 /* 數據庫 schema 發生變化 */
#define SQLITE_TOOBIG 18 /* 字符串或 BLOB 超出大小限制 */
#define SQLITE_CONSTRAINT 19 /* 約束衝突 */
#define SQLITE_MISMATCH 20 /* 數據類型不匹配 */
#define SQLITE_MISUSE 21 /* 庫被錯誤使用 */
#define SQLITE_NOLFS 22 /* 使用了宿主不支持的 OS 特性 */
#define SQLITE_AUTH 23 /* 授權被拒 */
#define SQLITE_FORMAT 24 /* 附屬數據庫格式錯誤 */
#define SQLITE_RANGE 25 /* sqlite3_bind 第二個參數越界 */
#define SQLITE_NOTADB 26 /* 打開的文件不是數據庫 */
#define SQLITE_ROW 100 /* sqlite3_step() 還有一行可取 */
#define SQLITE_DONE 101 /* sqlite3_step() 執行完畢 */
有了這些常量,調試時就能精確定位問題出在哪一步,而不是只對著一個 -1 發愁。
操作完畢後必須關閉,否則文件句柄與內存無法釋放:
SQLITE_API int sqlite3_close(sqlite3 *db);
使用起來非常直白:
sqlite3_close(pdb);
SQLite 數據庫文件本質上是可讀的 ASCII 存儲,安全性並不高,因此不要把敏感信息明文落庫,必要時應結合 SQLCipher 這類方案加密。另外,iOS 中數據庫文件建議放在 Library 或 Documents 目錄,並根據是否需要 iCloud 備份決定是否加入「禁止備份」標記。養成「打開即用、用完即關」的習慣,能有效避免數據庫被鎖定(SQLITE_BUSY)這類惱人問題。