第四章 iOS 平台 SQLite 集成方案对比

4.1 原生 sqlite3 桥接与 FMDB 封装

iOS 平台下使用 SQLite 的两种主流方案分别是 原生 C 语言 sqlite3 桥接 和 FMDB 封装库。前者直接调用 sqlite3 公开 API，后者基于 Objective-C 运行时对底层做了面向对象封装。下表从集成方式、内存管理、代码量三个维度做了详细对比。

4.1.1 原生 sqlite3 核心操作示例

// 打开数据库
sqlite3 *db;
if (sqlite3_open([dbPath UTF8String], &db) != SQLITE_OK) {
    NSLog(@"打开失败：%s", sqlite3_errmsg(db));
    return;
}

// 编译 SQL
const char *sql = "INSERT INTO user (id, name) VALUES (?, ?)";
sqlite3_stmt *stmt;
if (sqlite3_prepare_v2(db, sql, -1, &stmt, NULL) != SQLITE_OK) {
    NSLog(@"编译失败：%s", sqlite3_errmsg(db));
    sqlite3_close(db);
    return;
}

// 绑定参数 & 执行
sqlite3_bind_int(stmt, 1, 1);
sqlite3_bind_text(stmt, 2, "Alice", -1, SQLITE_TRANSIENT);
if (sqlite3_step(stmt) != SQLITE_DONE) {
    NSLog(@"执行失败：%s", sqlite3_errmsg(db));
}

// 手动释放
sqlite3_finalize(stmt);
sqlite3_close(db);

4.1.2 FMDB 封装等效操作

FMDatabase *db = [FMDatabase databaseWithPath:dbPath];
if (![db open]) {
    NSLog(@"打开失败：%@", [db lastError]);
    return;
}

BOOL success = [db executeUpdate:@"INSERT INTO user (id, name) VALUES (?, ?)",
                @1, @"Alice"];
if (!success) {
    NSLog(@"插入失败：%@", [db lastError]);
}

[db close];

4.2 FMDatabaseQueue 线程安全机制

FMDatabase 实例本身并非线程安全。多个线程同时调用同一个 FMDatabase 实例的 executeUpdate: 方法会导致 database is locked 崩溃或数据损坏。FMDatabaseQueue 通过串行 GCD 队列解决了该问题。

// 创建队列（串行）
FMDatabaseQueue *queue = [FMDatabaseQueue databaseQueueWithPath:dbPath];

// 在队列中执行所有操作
[queue inDatabase:^(FMDatabase *db) {
    [db executeUpdate:@"INSERT INTO user (id, name) VALUES (?, ?)", @1, @"Alice"];
    FMResultSet *rs = [db executeQuery:@"SELECT * FROM user WHERE id = ?", @1];
    while ([rs next]) {
        NSLog(@"name: %@", [rs stringForColumn:@"name"]);
    }
}];

// 事务模式使用 inTransaction
[queue inTransaction:^(FMDatabase *db, BOOL *rollback) {
    BOOL ok1 = [db executeUpdate:@"UPDATE user SET name = ? WHERE id = ?", @"Bob", @1];
    BOOL ok2 = [db executeUpdate:@"UPDATE user SET name = ? WHERE id = ?", @"Charlie", @2];
    if (!ok1 || !ok2) {
        *rollback = YES;
        return;
    }
}];

4.3 数据库迁移脚本执行策略

App 版本迭代中数据库字段变更不可避免。FMDB 配合版本号 + 迁移脚本表（schema_version）是一种轻量可靠的方案。

4.3.1 迁移表结构

CREATE TABLE IF NOT EXISTS schema_version (
    version INTEGER PRIMARY KEY,
    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
);

4.3.2 迁移执行流程

1. 从 schema_version 表读取当前版本号，若表不存在则视为版本 0。
2. 按版本号顺序加载 v1→v2、v2→v3…… 的迁移 SQL 脚本。
3. 每条迁移脚本包裹在 inTransaction: 中执行。
4. 脚本执行成功后插入一条版本记录 INSERT INTO schema_version (version) VALUES (?);。
5. 若某条脚本失败，*rollback = YES 回滚整个事务，版本号不回退。

- (void)migrateIfNeededWithQueue:(FMDatabaseQueue *)queue {
    [queue inTransaction:^(FMDatabase *db, BOOL *rollback) {
        // 获取当前版本
        int currentVersion = 0;
        FMResultSet *rs = [db executeQuery:@"SELECT MAX(version) FROM schema_version"];
        if ([rs next]) {
            currentVersion = [rs intForColumnIndex:0];
        }
        [rs close];

        // 按顺序执行迁移脚本
        NSArray *scripts = [self migrationScripts]; // v1→v2, v2→v3, ...
        for (int i = currentVersion + 1; i <= scripts.count; i++) {
            NSString *sql = scripts[i - 1];
            BOOL ok = [db executeUpdate:sql];
            if (!ok) {
                NSLog(@"迁移 v%d 失败：%@", i, [db lastError]);
                *rollback = YES;
                return;
            }
            // 记录已迁移版本
            [db executeUpdate:@"INSERT INTO schema_version (version) VALUES (?)", @(i)];
        }
    }];
}

4.4 性能对比与选型建议

下图展示了原生 sqlite3、FMDB（单线程）、FMDatabaseQueue（多线程）在 10 万条写入场景下的耗时对比和线程安全边界。

4.5 常见错误与调试清单

• 错误 1 — database is locked
  原因：多线程同时写 FMDatabase 实例。
  解决：替换为 FMDatabaseQueue，所有操作在 inDatabase: block 中执行。
• 错误 2 — 迁移脚本执行一半 App 崩溃
  原因：迁移未包裹在事务中。
  解决：使用 inTransaction:，中途失败自动回滚整批迁移。
• 错误 3 — FMResultSet 在 block 外部使用
  原因：队列内部在 block 结束后关闭了结果集。
  解决：在 block 内将数据转为 NSDictionary 或 Model 对象再传出。
• 错误 4 — schema_version 表未创建导致迁移死循环
  原因：首次迁移 SELECT MAX(version) 返回 0 但插入失败。
  解决：先执行 CREATE TABLE IF NOT EXISTS schema_version 再读取。