要操作一個資料庫,就得先有它的句柄。這個詞聽起來抽象,其實不必糾結命名——你只要清楚它是什麼、能拿它做什麼就好,就像「鞋子」為什麼叫鞋子並不重要,知道它能穿、能走路就夠了。
句柄到處可見,最常見的是檔案句柄:要讀寫檔案,先取得它的句柄。本質上,句柄就是一個描述用的結構體,裡頭記錄了目標物件的各項資訊,例如位置、大小、型別等等。有了這份描述,程式就能定位並操作對應的資源。
一句話總結:句柄是描述某個物件的結構體。
SQLite 的句柄定義如下(篇幅很長,看不懂可直接跳過):
struct sqlite3 {
sqlite3_vfs *pVfs; /* 作業系統介面 */
int nDb; /* 目前使用的後端數量 */
Db *aDb; /* 所有後端 */
int flags; /* 各類旗標 */
unsigned int openFlags; /* 傳給 xOpen() 的旗標 */
int errCode; /* 最近一次錯誤碼 */
u8 autoCommit; /* 自動提交旗標 */
u8 temp_store; /* 1: 檔案 2: 記憶體 0: 預設 */
/* ……其餘欄位從略,涵蓋快取、鎖、交易、模組、錯誤訊息與衝突函式等 */
};
typedef struct sqlite3 sqlite3;
這個龐大的結構體就是磁碟上資料庫檔案的描述符。有了它,我們便能對資料庫進行種種操作。內部細節暫且不必深究,先把 API 用熟;日後遇到效能或交易議題時再回頭理解ldb其餘欄位即可。
廢話這麼多,目的只有一個:不要對句柄心存畏懼。
操作 SQLite 的第一步就是宣告一個句柄變數,後續所有資料庫操作都要靠它:
sqlite3 *pdb;
到這裡我們只是宣告了一個指向 sqlite3 結構體的指標,裡面的內容尚未配置。接下來要做的,是向 SQLite 申請記憶體並填入實際資訊——但這一切都不必自己動手,只要透過 API 告訴它最基本的資訊即可。
目前唯一必須提供的資訊是資料庫檔案的路徑:
SQLITE_API int sqlite3_open(
const char *zFilename, /* 資料庫檔案路徑 */
sqlite3 **ppDb /* 二級指標:接收句柄 */
);
注意第二個參數是二級指標,而我們宣告的是一級指標,因此呼叫時要加上取位址運算子:
int ret = sqlite3_open(getFilePath(), &pdb);
所謂「開啟資料庫」,其實就是把檔案資訊載入並與句柄綁定;此後所有操作都透過 pdb 進行。這個函式的行為是:檔案存在就開啟,不存在就建立。
路徑建議獨立封裝成一個函式,這符合「一個函式只做一件事」的原則,後續要換位置或遷移平台時也好修改:
const char *getFilePath() {
return [[NSString stringWithFormat:@"%@/Documents/db", NSHomeDirectory()] UTF8String];
}
這裡用到了 iOS 的沙盒路徑寫法;若換到 Android 或嵌入式 Linux,只要改回對應的路徑即可。
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 /* 記憶體配置失敗 */ #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 /* 結構描述已變更 */ #define SQLITE_TOOBIG 18 /* 字串或 BLOB 超過大小上限 */ #define SQLITE_CONSTRAINT 19 /* 約束條件衝突 */ #define SQLITE_MISMATCH 20 /* 資料型別不相符 */ #define SQLITE_MISUSE 21 /* API 使用方式錯誤 */ #define SQLITE_NOLFS 22 /* 用到主機不支援的 OS 特性 */ #define SQLITE_AUTH 23 /* 授權被拒 */ #define SQLITE_FORMAT 24 /* 輔助資料庫格式錯誤 */ #define SQLITE_RANGE 25 /* bind 的第二個參數超出範圍 */ #define SQLITE_NOTADB 26 /* 開啟的檔案並非資料庫 */ #define SQLITE_ROW 100 /* sqlite3_step() 還有一列可讀 */ #define SQLITE_DONE 101 /* sqlite3_step() 執行完畢 */
值得補充的是,SQLite 的資料庫檔本質上就是一個純文字/二進位混合的檔案,因此它並不適合承載需要加密的敏感資料;作為本地端的輕量儲存則綽綽有餘。
操作完成後就該關閉連線,讓資源得以釋放:
SQLITE_API int sqlite3_close(sqlite3 *db);
sqlite3_close(pdb);
實務上建議檢查回傳值:若還有未完成的 statement 尚未 finalize,sqlite3_close 會回傳 SQLITE_BUSY,此時可改用 sqlite3_close_v2 做優雅關閉。