要在 iOS 中使用 SQLite3,第一步是加入 libsqlite3.dylib 這個庫文件,然後引入主標頭檔。引入之後就能直接呼叫庫內提供的純 C 介面。
建一個新專案,在主畫面放四顆按鈕,分別對應新增、刪除、修改、查詢。本文先完成「開啟資料庫 → 建表 → 插入 → 查詢」這條主線,刪除與修改留給讀者依相同模式補上。
函式簽名為 sqlite3_open(const char *filename, sqlite3 **ppDb)。
作用:傳入一個檔案名稱,它會自動檢測該檔案是否存在;不存在就自動建立(這裡指資料庫檔,剛建立時是空的)。
參數:第一個是檔案名稱(需轉為 C 字串),第二個是資料庫實例的位址。
型別說明:sqlite3 是一個型別,db 是資料庫的 handle,也就是資料庫的象徵;後續所有增刪改查都得操作這個實例。
返回值:int。若回傳 SQLITE_OK 代表成功,否則失敗。
// 1. 開啟資料庫檔(若不存在會自動建立)
int result = sqlite3_open(cfileName, &db);
if (result == SQLITE_OK) {
NSLog(@"成功打開數據庫");
// 2. 建表
const char *sql = "CREATE TABLE IF NOT EXISTS t_students ("
"id integer PRIMARY KEY AUTOINCREMENT,"
"name text NOT NULL,"
"age integer NOT NULL);";
char *errmsg = NULL;
result = sqlite3_exec(db, sql, NULL, NULL, &errmsg);
if (result == SQLITE_OK) {
NSLog(@"創表成功");
} else {
NSLog(@"創表失敗----%s", errmsg);
}
} else {
NSLog(@"打開數據庫失敗");
}
sqlite3_exec 的五個參數依序是:資料庫 handle、SQL 語句、回呼函式指標(把 * 換成 ^ 就是 block)、可傳 NULL 的 context、以及錯誤訊息的輸出參數(除錯時很有用)。
把錯誤訊息搭配檔案與行號一起印出來,定位問題會快很多:
if (result == SQLITE_OK) {
NSLog(@"創表成功");
} else {
// NSLog(@"創表失敗----%s", errmsg);
printf("創表失敗---%s----%s---%d", errmsg, __FILE__, __LINE__);
}
__FILE__ 印出檔名,__LINE__ 印出行號。
- (IBAction)insert {
for (int i = 0; i < 20; i++) {
// 1. 拼接 SQL
NSString *name = [NSString stringWithFormat:@"文曉--%d", arc4random_uniform(100)];
int age = arc4random_uniform(20) + 10;
NSString *sql = [NSString stringWithFormat:@"INSERT INTO t_students (name, age) VALUES ('%@', %d);", name, age];
// 2. 執行
char *errmsg = NULL;
sqlite3_exec(self.db, sql.UTF8String, NULL, NULL, &errmsg);
if (errmsg) {
NSLog(@"插入數據失敗--%s", errmsg);
} else {
NSLog(@"插入數據成功");
}
}
}
這裡刻意用字串拼接 SQL 來示範最直觀的寫法,但正式專案請改用 prepared statement 綁定參數。拼接字串不僅有 SQL injection 風險,遇到含單引號的內容也會直接出錯。
select 也可以用 sqlite3_exec 完成,但實務上通常走 prepare + step 這條路。
sqlite3_prepare_v2 的四個參數:資料庫 handle、SQL 語句、SQL 長度(填 -1 代表由系統自行計算)、用來取資料的 statement 指標,最後一個一般傳 NULL。
- (IBAction)select {
const char *sql = "SELECT id, name, age FROM t_students WHERE age < 20;";
sqlite3_stmt *stmt = NULL;
// 進行查詢前的準備
if (sqlite3_prepare_v2(self.db, sql, -1, &stmt, NULL) == SQLITE_OK) {
NSLog(@"查詢語句沒有問題");
// 每呼叫一次 sqlite3_step,stmt 就指向下一筆記錄
while (sqlite3_step(stmt) == SQLITE_ROW) {
int ID = sqlite3_column_int(stmt, 0); // 第 0 欄(int)
const unsigned char *name = sqlite3_column_text(stmt, 1); // 第 1 欄(text)
int age = sqlite3_column_int(stmt, 2); // 第 2 欄(int)
printf("%d %s %d\n", ID, name, age);
}
} else {
NSLog(@"查詢語句有問題");
}
}
使用完 statement 後記得呼叫 sqlite3_finalize(stmt) 釋放,否則會造成資源洩漏。
YYViewController.m:
#import "YYViewController.h"
@interface YYViewController ()
// db 是資料庫的 handle,要進行增刪改查就得操作這個實例
@property (nonatomic, assign) sqlite3 *db;
- (IBAction)insert;
- (IBAction)delete;
- (IBAction)update;
- (IBAction)select;
@end
@implementation YYViewController
- (void)viewDidLoad {
[super viewDidLoad];
// 取得資料庫檔案路徑
NSString *doc = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) lastObject];
NSString *fileName = [doc stringByAppendingPathComponent:@"students.sqlite"];
// OC 字串轉 C 字串
const char *cfileName = fileName.UTF8String;
// 1. 開啟資料庫(不存在則自動建立)
int result = sqlite3_open(cfileName, &_db);
if (result == SQLITE_OK) {
NSLog(@"成功打開數據庫");
// 2. 建表
const char *sql = "CREATE TABLE t_students ("
"id integer PRIMARY KEY AUTOINCREMENT,"
"name text NOT NULL,"
"age integer NOT NULL);";
char *errmsg = NULL;
result = sqlite3_exec(self.db, sql, NULL, NULL, &errmsg);
if (result == SQLITE_OK) {
NSLog(@"創表成功");
} else {
printf("創表失敗---%s----%s---%d", errmsg, __FILE__, __LINE__);
}
} else {
NSLog(@"打開數據庫失敗");
}
}
- (IBAction)insert {
for (int i = 0; i < 20; i++) {
NSString *name = [NSString stringWithFormat:@"文曉--%d", arc4random_uniform(100)];
int age = arc4random_uniform(20) + 10;
NSString *sql = [NSString stringWithFormat:@"INSERT INTO t_students (name, age) VALUES ('%@', %d);", name, age];
char *errmsg = NULL;
sqlite3_exec(self.db, sql.UTF8String, NULL, NULL, &errmsg);
if (errmsg) {
NSLog(@"插入數據失敗--%s", errmsg);
} else {
NSLog(@"插入數據成功");
}
}
}
- (IBAction)delete {
// TODO
}
- (IBAction)update {
// TODO
}
- (IBAction)select {
const char *sql = "SELECT id, name, age FROM t_students WHERE age < 20;";
sqlite3_stmt *stmt = NULL;
if (sqlite3_prepare_v2(self.db, sql, -1, &stmt, NULL) == SQLITE_OK) {
NSLog(@"查詢語句沒有問題");
while (sqlite3_step(stmt) == SQLITE_ROW) {
int ID = sqlite3_column_int(stmt, 0);
const unsigned char *name = sqlite3_column_text(stmt, 1);
int age = sqlite3_column_int(stmt, 2);
printf("%d %s %d\n", ID, name, age);
}
} else {
NSLog(@"查詢語句有問題");
}
}
@end
關於資料庫位置。放在 Documents 目錄的資料庫會被 iCloud/iTunes 備份;如果只是暫存性質的資料,Cache 或 tmp 目錄更合適。
關於連線管理。把 sqlite3 handle 當成單例在整個 App 生命週期中 reuse,比每次操作都開一次連線有效率得多。同時要注意 SQLite 預設不支援多執行緒共用同一個連線,若要在背景佇列操作,記得開啟 serialized 模式或改用連線池。
關於型別。SQLite 是動態型別系統,integer、text 這些宣告只是「型別親和性」提示,寫入時仍可能存入不符合宣告的型別。跨層取值時務必用對應的 sqlite3_column_xxx 系列函式,並留意 sqlite3_column_text 回傳的是 C 字串指標,轉成 NSString 時要指定編碼。
如果專案規模較大,可以考慮 FMDB 這類 Objective-C 封裝,或直接使用 Core Data,把 SQL 細節交給框架處理。