SQLite与Android

public SQLiteOpenHelper(
    Context context,      // 应用程序上下文，通常传递 Activity 或 Application 对象
    String name,          // 数据库文件名，若传 null 则创建内存数据库（用于测试场景）
    CursorFactory factory,// 自定义 Cursor 工厂，传 null 则使用默认实现
    int version           // 数据库版本号，必须为正整数（从 1 开始）
)

// BookDatabaseHelper.java
// 自定义数据库辅助类，继承 SQLiteOpenHelper
public class BookDatabaseHelper extends SQLiteOpenHelper {
 
    // 数据库文件名
    private static final String DATABASE_NAME = "bookstore.db";
    // 数据库版本号：每次发布新版本需要递增此值
    private static final int DATABASE_VERSION = 1;
 
    // 单例模式：保证全局只有一个数据库Helper实例
    // 这样可以避免多次打开/关闭数据库连接，提升性能
    private static BookDatabaseHelper sInstance;
 
    // 静态工厂方法获取实例，传入 Application Context
    // 使用 Application Context 而非 Activity Context 是最佳实践，
    // 可以避免因 Activity 销毁而导致数据库连接提前关闭的问题
    public static synchronized BookDatabaseHelper getInstance(Context context) {
        if (sInstance == null) {
            sInstance = new BookDatabaseHelper(
                context.getApplicationContext(), // 确保使用 Application 级别上下文
                DATABASE_NAME,
                null,                             // 使用默认 CursorFactory
                DATABASE_VERSION
            );
        }
        return sInstance;
    }
 
    // 私有构造函数：外部代码必须通过 getInstance() 获取实例
    // 这是单例模式的实现细节
    private BookDatabaseHelper(Context context, String name,
                                CursorFactory factory, int version) {
        super(context, name, factory, version);
    }
 
    // ... onCreate() 和 onUpgrade() 方法将在后面详细讲解
}

// BookDatabaseHelper.java
@Override
public void onCreate(SQLiteDatabase db) {
    // onCreate 在数据库文件首次创建时调用
    // 此时 db 参数已经是一个可写的 SQLiteDatabase 对象
    // 开发者需要在此执行所有的 CREATE TABLE 语句
 
    // 创建图书表（books）
    // id: 主键，自增整型
    // name: 书名，最大100字符，非空
    // author: 作者，最大50字符
    // price: 价格，保留两位小数的浮点数
    // category: 分类，可空字符串
    // create_time: 创建时间，存储 Unix 时间戳
    db.execSQL("CREATE TABLE IF NOT EXISTS books (" +
            "id INTEGER PRIMARY KEY AUTOINCREMENT, " +
            "name VARCHAR(100) NOT NULL, " +
            "author VARCHAR(50), " +
            "price REAL DEFAULT 0.0, " +
            "category VARCHAR(50), " +
            "create_time INTEGER NOT NULL" +
            ")");
 
    // 创建作者表（authors）
    // 演示一对多关系：一个作者可以有多本图书
    db.execSQL("CREATE TABLE IF NOT EXISTS authors (" +
            "author_id INTEGER PRIMARY KEY AUTOINCREMENT, " +
            "author_name VARCHAR(50) NOT NULL, " +
            "author_bio TEXT, " +
            "author_country VARCHAR(30)" +
            ")");
 
    // 创建图书-作者关联表（book_author）
    // 演示多对多关系：一本书可以有多个作者，一个作者也可以写多本书
    db.execSQL("CREATE TABLE IF NOT EXISTS book_author (" +
            "book_id INTEGER NOT NULL, " +
            "author_id INTEGER NOT NULL, " +
            "PRIMARY KEY (book_id, author_id), " +
            "FOREIGN KEY (book_id) REFERENCES books(id) ON DELETE CASCADE, " +
            "FOREIGN KEY (author_id) REFERENCES authors(author_id) ON DELETE CASCADE" +
            ")");
}

// BookDatabaseHelper.java
@Override
public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
    // oldVersion: 当前设备上存储的数据库版本号
    // newVersion: 代码中声明的 DATABASE_VERSION
    // db: 可写的数据库连接对象
 
    // 重要原则：onUpgrade 中必须处理从旧版本到新版本的所有路径
    // 不能假设 oldVersion 一定是 newVersion - 1
    // 因为用户可能从版本 1 直接升级到版本 5（跳过中间版本）
 
    // 数据库版本 2: 增加了 publishers 出版商表
    if (oldVersion < 2) {
        db.execSQL("CREATE TABLE IF NOT EXISTS publishers (" +
                "publisher_id INTEGER PRIMARY KEY AUTOINCREMENT, " +
                "publisher_name VARCHAR(100) NOT NULL, " +
                "publisher_country VARCHAR(30)" +
                ")");
    }
 
    // 数据库版本 3: 给 books 表增加了 pages 字段和 edition 字段
    if (oldVersion < 3) {
        // SQLite 不支持直接的 ALTER TABLE ADD COLUMN 语法（早期版本）
        // 但 SQLite 从 3.1.6 开始支持 ADD COLUMN
        // 为了兼容性，可以使用如下方式：
        // 方式一：直接添加列（SQLite 3.1.6+ 支持）
        db.execSQL("ALTER TABLE books ADD COLUMN pages INTEGER DEFAULT 0");
        db.execSQL("ALTER TABLE books ADD COLUMN edition INTEGER DEFAULT 1");
    }
 
    // 数据库版本 4: 给 authors 表增加了 birth_year 字段
    if (oldVersion < 4) {
        db.execSQL("ALTER TABLE authors ADD COLUMN birth_year INTEGER");
    }
 
    // 数据库版本 5: 在 book_author 关联表中增加了权重字段 weight
    // 描述作者对某本书的贡献权重（例如第一作者权重高）
    if (oldVersion < 5) {
        db.execSQL("ALTER TABLE book_author ADD COLUMN weight INTEGER DEFAULT 100");
    }
}

// SQLiteOpenHelper.java 中的默认实现（简化版）
@Override
public void onDowngrade(SQLiteDatabase db, int oldVersion, int newVersion) {
    // 默认实现：抛出异常，拒绝降级
    throw new SQLiteException(
        "Can't downgrade database from version " + oldVersion +
        " to " + newVersion
    );
}

// BookDatabaseHelper.java
@Override
public void onDowngrade(SQLiteDatabase db, int oldVersion, int newVersion) {
    // 降级策略：相对安全的做法是删除旧数据并重建
    // 但这会导致数据丢失，因此大多数应用选择直接拒绝降级
    // 这里展示一个简单的降级实现示例
 
    // 方案一：删除受影响的表并重建
    db.execSQL("DROP TABLE IF EXISTS books");
    db.execSQL("DROP TABLE IF EXISTS authors");
    db.execSQL("DROP TABLE IF EXISTS book_author");
    db.execSQL("DROP TABLE IF EXISTS publishers");
    // 重建所有表
    onCreate(db);
 
    // 方案二：保守策略——直接抛异常，阻止降级（推荐做法）
    // throw new SQLiteException("Database downgrade is not supported");
}

// BookDatabaseHelper.java
@Override
public void onOpen(SQLiteDatabase db) {
    super.onOpen(db);
    // 每次打开数据库时都会执行
    // 适合做一些全局的数据库配置，例如启用外键约束
 
    // SQLite 默认不强制执行外键约束
    // 需要手动开启，否则 FOREIGN KEY 语句不会生效
    if (!db.isReadOnly()) {
        // 启用外键约束检查
        // 这确保了级联删除、更新等外键行为能够正常工作
        db.execSQL("PRAGMA foreign_keys = ON;");
    }
}

// BookDatabaseHelper.java
package com.example.bookstore.db;
 
import android.content.Context;
import android.database.sqlite.SQLiteDatabase;
import android.database.sqlite.SQLiteOpenHelper;
import android.database.sqlite.SQLiteDatabase.CursorFactory;
 
/**
 * 书店应用数据库辅助类
 *
 * 职责说明：
 * 1. 管理数据库的创建（onCreate）
 * 2. 管理数据库的升级（onUpgrade）
 * 3. 管理数据库的降级（onDowngrade，默认拒绝）
 * 4. 配置数据库参数（onOpen）
 *
 * 使用单例模式保证全局唯一实例
 */
public class BookDatabaseHelper extends SQLiteOpenHelper {
 
    // ===================== 常量定义 =====================
    // 数据库文件名
    private static final String DATABASE_NAME = "bookstore.db";
    // 数据库版本号：每次发布新版本应用时递增
    // 重要：此值必须始终大于已发布的任何版本号
    private static final int DATABASE_VERSION = 1;
 
    // 单例实例
    private static volatile BookDatabaseHelper sInstance;
 
    // ===================== 单例获取 =====================
    /**
     * 获取数据库Helper实例
     * 使用双重检查锁定（Double-Checked Locking）确保线程安全
     * @param context 应用程序上下文（推荐使用 Application Context）
     * @return BookDatabaseHelper 实例
     */
    public static BookDatabaseHelper getInstance(Context context) {
        if (sInstance == null) {
            synchronized (BookDatabaseHelper.class) {
                if (sInstance == null) {
                    sInstance = new BookDatabaseHelper(
                        context.getApplicationContext(),
                        DATABASE_NAME,
                        null,
                        DATABASE_VERSION
                    );
                }
            }
        }
        return sInstance;
    }
 
    // ===================== 构造函数 =====================
    /**
     * 私有构造函数
     * 外部必须通过 getInstance() 方法获取实例
     */
    private BookDatabaseHelper(Context context, String name,
                                CursorFactory factory, int version) {
        super(context, name, factory, version);
        // SQLiteOpenHelper 内部会：
        // 1. 检查数据库文件是否存在
        // 2. 比较版本号并决定调用 onCreate 或 onUpgrade
        // 3. 在内部维护数据库连接
    }
 
    // ===================== 生命周期回调 =====================
    /**
     * 数据库首次创建时调用
     * 在此方法中定义所有初始表结构
     * 此方法调用后，数据库版本会被自动设置为构造函数的 version 参数值
     */
    @Override
    public void onCreate(SQLiteDatabase db) {
        // 创建图书表
        db.execSQL("CREATE TABLE IF NOT EXISTS books (" +
                "id INTEGER PRIMARY KEY AUTOINCREMENT, " +
                "name VARCHAR(100) NOT NULL, " +
                "author VARCHAR(50), " +
                "price REAL DEFAULT 0.0, " +
                "category VARCHAR(50), " +
                "pages INTEGER DEFAULT 0, " +
                "edition INTEGER DEFAULT 1, " +
                "create_time INTEGER NOT NULL" +
                ")");
 
        // 创建作者表
        db.execSQL("CREATE TABLE IF NOT EXISTS authors (" +
                "author_id INTEGER PRIMARY KEY AUTOINCREMENT, " +
                "author_name VARCHAR(50) NOT NULL, " +
                "author_bio TEXT, " +
                "author_country VARCHAR(30), " +
                "birth_year INTEGER" +
                ")");
 
        // 创建关联表（多对多）
        db.execSQL("CREATE TABLE IF NOT EXISTS book_author (" +
                "book_id INTEGER NOT NULL, " +
                "author_id INTEGER NOT NULL, " +
                "weight INTEGER DEFAULT 100, " +
                "PRIMARY KEY (book_id, author_id), " +
                "FOREIGN KEY (book_id) REFERENCES books(id) ON DELETE CASCADE, " +
                "FOREIGN KEY (author_id) REFERENCES authors(author_id) ON DELETE CASCADE" +
                ")");
 
        // 创建出版商表
        db.execSQL("CREATE TABLE IF NOT EXISTS publishers (" +
                "publisher_id INTEGER PRIMARY KEY AUTOINCREMENT, " +
                "publisher_name VARCHAR(100) NOT NULL, " +
                "publisher_country VARCHAR(30)" +
                ")");
    }
 
    /**
     * 数据库版本升级时调用
     * 采用累积式升级策略，每个版本只做最小增量变更
     * 这样可以正确处理从任意旧版本到新版本的升级路径
     */
    @Override
    public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
        // 版本 2: 新增 publishers 表
        if (oldVersion < 2) {
            db.execSQL("CREATE TABLE IF NOT EXISTS publishers (" +
                    "publisher_id INTEGER PRIMARY KEY AUTOINCREMENT, " +
                    "publisher_name VARCHAR(100) NOT NULL, " +
                    "publisher_country VARCHAR(30)" +
                    ")");
        }
 
        // 版本 3: books 表增加 pages 和 edition 列
        if (oldVersion < 3) {
            db.execSQL("ALTER TABLE books ADD COLUMN pages INTEGER DEFAULT 0");
            db.execSQL("ALTER TABLE books ADD COLUMN edition INTEGER DEFAULT 1");
        }
 
        // 版本 4: authors 表增加 birth_year 列
        if (oldVersion < 4) {
            db.execSQL("ALTER TABLE authors ADD COLUMN birth_year INTEGER");
        }
 
        // 版本 5: book_author 表增加 weight 列
        if (oldVersion < 5) {
            db.execSQL("ALTER TABLE book_author ADD COLUMN weight INTEGER DEFAULT 100");
        }
 
        // 注意：如果需要在升级过程中迁移数据，
        // 应在 ALTER TABLE 语句之间插入数据迁移的 SQL 逻辑
    }
 
    /**
     * 数据库打开时的回调
     * 每次打开数据库都会执行，适合做全局配置
     */
    @Override
    public void onOpen(SQLiteDatabase db) {
        super.onOpen(db);
        // 启用外键约束
        // 这是 SQLite 数据库管理中最重要的配置之一
        if (!db.isReadOnly()) {
            db.execSQL("PRAGMA foreign_keys = ON;");
        }
    }
}

// BookRepository.java
// 数据仓储层：封装所有数据库操作
public class BookRepository {
 
    private final BookDatabaseHelper mDbHelper;  // 数据库Helper引用
    private final Context mContext;              // 上下文引用
 
    public BookRepository(Context context) {
        mContext = context;
        // 通过单例获取Helper实例
        mDbHelper = BookDatabaseHelper.getInstance(context);
    }
 
    /**
     * 插入一本新书
     * 演示 ContentValues 的用法（下一节将详细展开）
     */
    public long insertBook(String name, String author, double price) {
        // getWritableDatabase() 返回可写的数据库连接
        // 如果数据库不存在会触发创建逻辑
        // 如果数据库版本不匹配会触发升级逻辑
        SQLiteDatabase db = mDbHelper.getWritableDatabase();
 
        // 使用 ContentValues 封装要插入的数据
        // 这是 Android 推荐的插入方式，比直接写 SQL 更安全
        ContentValues values = new ContentValues();
        values.put("name", name);         // 书名
        values.put("author", author);     // 作者
        values.put("price", price);       // 价格
        values.put("create_time", System.currentTimeMillis() / 1000); // Unix时间戳
 
        // insert() 返回新插入行的 rowId，出错返回 -1
        long newRowId = db.insert("books", null, values);
 
        // 注意：insert() 执行后，db 仍然是打开的状态
        // 不需要手动调用 db.close()
        // SQLiteOpenHelper 会自动管理数据库连接的关闭时机
        // 开发者通常不需要也不应该手动关闭数据库连接
 
        return newRowId;
    }
 
    /**
     * 读取所有图书
     * 演示 getReadableDatabase() 和 rawQuery() 的用法
     */
    public void queryAllBooks() {
        // getReadableDatabase() 返回只读的数据库连接
        // 如果数据库不存在，同样会触发创建/升级逻辑
        // 与 getWritableDatabase() 的区别在于：
        //   - getWritableDatabase(): 返回可写连接（用于增删改）
        //   - getReadableDatabase(): 返回只读连接（用于查询）
        // 当磁盘空间不足时，getWritableDatabase() 可能抛出异常，
        // 而 getReadableDatabase() 会尝试返回只读连接
        SQLiteDatabase db = mDbHelper.getReadableDatabase();
 
        // 定义要查询的列（投影），null 表示查询所有列
        String[] projection = {
            "id",
            "name",
            "author",
            "price"
        };
 
        // 使用 rawQuery 执行带占位符的查询语句
        // 第一个参数是 SQL 模板，占位符用 ? 表示
        // 第二个参数是占位符的值数组
        Cursor cursor = db.rawQuery(
            "SELECT id, name, author, price FROM books WHERE price > ? ORDER BY price DESC",
            new String[]{String.valueOf(10.0)}  // 只查询价格大于10元的书
        );
 
        // 使用 Cursor 遍历结果集（下一节将详细展开）
        try {
            // moveToFirst() 将游标移动到第一行
            // 如果结果集为空，返回 false
            while (cursor.moveToNext()) {
                long id = cursor.getLong(cursor.getColumnIndexOrThrow("id"));
                String name = cursor.getString(cursor.getColumnIndexOrThrow("name"));
                String author = cursor.getString(cursor.getColumnIndexOrThrow("author"));
                double price = cursor.getDouble(cursor.getColumnIndexOrThrow("price"));
 
                Log.d("BookRepository", "Book[id=" + id + ", name=" + name +
                      ", author=" + author + ", price=" + price + "]");
            }
        } finally {
            // 重要：使用完 Cursor 后必须关闭
            // 否则会泄漏数据库资源，导致性能下降甚至崩溃
            cursor.close();
        }
    }
 
    /**
     * 更新图书价格
     */
    public int updateBookPrice(long bookId, double newPrice) {
        SQLiteDatabase db = mDbHelper.getWritableDatabase();
 
        ContentValues values = new ContentValues();
        values.put("price", newPrice);
 
        // update() 返回受影响的行数
        // 第一个参数：表名
        // 第二个参数：新的 ContentValues
        // 第三个参数：WHERE 子句的条件
        // 第四个参数：WHERE 子句中占位符的值
        int rowsAffected = db.update(
            "books",
            values,
            "id = ?",
            new String[]{String.valueOf(bookId)}
        );
 
        return rowsAffected;
    }
 
    /**
     * 删除图书
     */
    public int deleteBook(long bookId) {
        SQLiteDatabase db = mDbHelper.getWritableDatabase();
 
        // delete() 返回被删除的行数
        int rowsDeleted = db.delete(
            "books",
            "id = ?",
            new String[]{String.valueOf(bookId)}
        );
 
        return rowsDeleted;
    }
}

// 场景：books 表需要从单作者改为多作者（拆分为独立字段）
// 步骤 1：创建新的表结构
if (oldVersion < 6) {
    // 创建新的 books 表，去掉 author 字段
    db.execSQL("CREATE TABLE books_new (" +
            "id INTEGER PRIMARY KEY AUTOINCREMENT, " +
            "name VARCHAR(100) NOT NULL, " +
            "price REAL DEFAULT 0.0, " +
            "category VARCHAR(50), " +
            "pages INTEGER DEFAULT 0, " +
            "edition INTEGER DEFAULT 1, " +
            "create_time INTEGER NOT NULL" +
            ")");
 
    // 步骤 2：将旧表数据迁移到新表（保留除 author 外的所有字段）
    db.execSQL("INSERT INTO books_new (id, name, price, category, pages, edition, create_time) " +
            "SELECT id, name, price, category, pages, edition, create_time FROM books");
 
    // 步骤 3：删除旧表
    db.execSQL("DROP TABLE books");
 
    // 步骤 4：重命名新表
    db.execSQL("ALTER TABLE books_new RENAME TO books");
 
    // 步骤 5：注意！外键约束在重命名表后可能需要重建关联表
    // 如果 book_author 表中有外键引用 books 表，需要重建触发器
    db.execSQL("PRAGMA foreign_keys = OFF;");
    // 重建外键约束...
    db.execSQL("PRAGMA foreign_keys = ON;");
}

if (oldVersion < 7) {
    // 迁移数据：在升级过程中顺便清理旧数据
    // 使用 UPDATE 语句配合 SQLite 的字符串函数
    db.execSQL("UPDATE books SET name = REPLACE(name, ' ', '')");
 
    // 更复杂的迁移可能需要：
    // 1. 开启事务（确保迁移的原子性）
    // 2. 先查询旧数据
    // 3. 在 Java/Kotlin 代码中处理数据
    // 4. 写入新表
    // 这种情况下需要在 Java 层分批次处理，避免一次性加载过多数据导致 OOM
}

// DatabaseMigrationTest.java
// 伪代码：展示升级测试的思路
public class DatabaseMigrationTest {
 
    @Test
    public void testMigrationFromVersion1ToLatest() {
        // 1. 创建版本 1 的数据库
        SQLiteOpenHelper helperV1 = new BookDatabaseHelper(context, "test.db", null, 1);
        helperV1.getWritableDatabase().close();
 
        // 2. 用最新版本的 Helper 打开它
        BookDatabaseHelper helperLatest = BookDatabaseHelper.getInstance(context);
 
        // 3. 验证升级后的数据库结构和数据完整性
        SQLiteDatabase db = helperLatest.getReadableDatabase();
        // 验证表是否存在...
        // 验证数据是否正确迁移...
        db.close();
    }
 
    @Test
    public void testMigrationFromVersion4ToLatest() {
        // 类似的测试...
    }
}

@Override
public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
    // 开始事务
    // beginTransaction() 会标记事务起点
    db.beginTransaction();
    try {
        if (oldVersion < 2) {
            db.execSQL("CREATE TABLE publishers (...)");
        }
 
        if (oldVersion < 3) {
            db.execSQL("ALTER TABLE books ADD COLUMN pages INTEGER DEFAULT 0");
            db.execSQL("ALTER TABLE books ADD COLUMN edition INTEGER DEFAULT 1");
        }
 
        if (oldVersion < 4) {
            db.execSQL("ALTER TABLE authors ADD COLUMN birth_year INTEGER");
        }
 
        if (oldVersion < 5) {
            db.execSQL("ALTER TABLE book_author ADD COLUMN weight INTEGER DEFAULT 100");
        }
 
        // 所有 SQL 执行成功后，标记事务为成功
        // setTransactionSuccessful() 必须调用在 commit() 之前
        // 否则 commit() 会自动回滚事务
        db.setTransactionSuccessful();
 
    } catch (Exception e) {
        // 如果任何一条 SQL 抛出异常，
        // 由于没有调用 setTransactionSuccessful()，
        // 当 beginTransaction() 不会自动提交，数据库会回滚到事务开始前的状态
        Log.e("BookDatabaseHelper", "数据库升级失败", e);
    } finally {
        // 结束事务：
        // - 如果 setTransactionSuccessful() 被调用过：提交事务
        // - 如果 setTransactionSuccessful() 未被调用：回滚事务
        db.endTransaction();
    }
}

// Room 方式：开发者只需声明版本号和实体类
@Database(
    entities = {Book.class, Author.class, BookAuthor.class, Publisher.class},
    version = 1,
    exportSchema = false  // 是否导出 schema 文件用于迁移
)
public abstract class BookDatabase extends RoomDatabase {
    // Room 会自动生成继承自 SQLiteOpenHelper 的实现类
    // 开发者不需要（也不应该）手动继承 SQLiteOpenHelper
    public abstract BookDao bookDao();
    public abstract AuthorDao authorDao();
}

// kotlin
// android.database.sqlite.SQLiteDatabase
val db = writableDatabase  // 获取可写数据库引用
 
// 执行一条插入语句
db.execSQL(
    "INSERT INTO user (name, age, email) VALUES (?, ?, ?)",
    arrayOf("张三", 25, "zhangsan@example.com")
)
 
// 执行一条更新语句
db.execSQL(
    "UPDATE user SET age = ? WHERE name = ?",
    arrayOf(26, "张三")
)
 
// 执行一条删除语句
db.execSQL(
    "DELETE FROM user WHERE age < ?",
    arrayOf(18)
)

// kotlin
val db = writableDatabase
try {
    db.beginTransaction()  // 开启事务，显式获取 RESERVED 锁
    repeat(1000) { i ->
        db.execSQL(
            "INSERT INTO logs (event, timestamp) VALUES (?, ?)",
            arrayOf("user_action_$i", System.currentTimeMillis())
        )
    }
    db.setTransactionSuccessful()  // 标记事务成功
} finally {
    db.endTransaction()  // 提交或回滚
}

// kotlin
val db = readableDatabase  // 优先使用只读数据库引用，避免不必要的写锁
val cursor = db.rawQuery(
    """
    SELECT name, age, email
    FROM user
    WHERE age >= ? AND age <= ?
    ORDER BY age DESC
    LIMIT 10
    """.trimIndent(),
    arrayOf("18", "30")  // 绑定参数，防止 SQL 注入
)
 
// 必须确保 finally 块中关闭 cursor，释放数据库资源
try {
    while (cursor.moveToNext()) {
        // 按列索引获取数据——性能最优，零反射开销
        val name  = cursor.getString(0)   // 第 0 列：name
        val age   = cursor.getInt(1)      // 第 1 列：age
        val email = cursor.getString(2)   // 第 2 列：email
 
        Log.d("User", "name=$name, age=$age, email=$email")
    }
} finally {
    cursor.close()  // 关闭游标，释放底层资源
}

// kotlin
// 先缓存列索引，避免重复查找
val nameIdx  = cursor.getColumnIndexOrThrow("name")
val ageIdx   = cursor.getColumnIndexOrThrow("age")
val emailIdx = cursor.getColumnIndexOrThrow("email")
 
while (cursor.moveToNext()) {
    val name  = cursor.getString(nameIdx)
    val age   = cursor.getInt(ageIdx)
    val email = cursor.getString(emailIdx)
}

// kotlin
// android.content.ContentValues
val values = ContentValues().apply {
    put("name", "李四")        // String 类型
    put("age", 30)            // Integer/Long 类型，SQLite INTEGER 类型
    put("email", "lisi@example.com")  // NULLABLE: 可以直接 put null
    put("balance", 99.99)     // Double/Float → SQLite REAL
    put("created_at", System.currentTimeMillis() / 1000)  // Unix 时间戳
}
 
// 插入数据，返回新行的 rowid（失败返回 -1）
val rowId = db.insert("user", null, values)
if (rowId == -1L) {
    // 插入失败，可能是违反唯一约束或外键约束
    Log.e("DB", "Insert failed")
}

// kotlin
// insert 的 nullColumnHack 示例
val emptyValues = ContentValues()
// 如果 values 为空，会执行:
// INSERT INTO user (name) VALUES (NULL)
// 即插入一行除 name 为 NULL 外所有列均为 DEFAULT 值的行
db.insert("user", "name", emptyValues)

// kotlin
val updateValues = ContentValues().apply {
    put("age", 31)             // 将 age 更新为 31
    put("email", "lisi_new@example.com")
}
 
// WHERE 子句：更新 name = "李四" 的行
// 返回值：受影响的行数（如果没有匹配行则为 0）
val rowsUpdated = db.update(
    "user",
    updateValues,
    "name = ? AND age = ?",   // WHERE 子句（不含 WHERE 关键字）
    arrayOf("李四", "30")       // WHERE 参数绑定
)
 
Log.d("DB", "Updated $rowsUpdated rows")

// kotlin
// 删除 age < 18 且 email 为 NULL 的用户
val rowsDeleted = db.delete(
    "user",
    "age < ? AND email IS NULL",
    arrayOf("18")
)
 
Log.d("DB", "Deleted $rowsDeleted rows")

// kotlin
// 【选择指南】
 
// 场景一：单行插入，推荐 ContentValues + insert()
val user = ContentValues().apply {
    put("name", "王五")
    put("age", 28)
}
db.insert("user", null, user)
 
// 场景二：批量插入，推荐事务 + execSQL() 或事务 + insert()
// 高性能批量写入场景，execSQL() 可以避免 ContentValues 的 HashMap 开销
db.beginTransaction()
try {
    repeat(10000) { i ->
        db.execSQL(
            "INSERT INTO logs (event, ts) VALUES (?, ?)",
            arrayOf("event_$i", i)
        )
    }
    db.setTransactionSuccessful()
} finally {
    db.endTransaction()
}
 
// 场景三：带条件的复杂查询，推荐 rawQuery()
val results = db.rawQuery(
    """
    SELECT u.*, COUNT(o.id) as order_count
    FROM user u
    LEFT JOIN orders o ON u.id = o.user_id
    WHERE u.age BETWEEN ? AND ?
    GROUP BY u.id
    HAVING order_count > ?
    """.trimIndent(),
    arrayOf("20", "40", "5")
)
 
// 场景四：需要数据库函数（如 RANDOM()、date()）的查询，必须 rawQuery()
val randomUser = db.rawQuery(
    "SELECT * FROM user ORDER BY RANDOM() LIMIT 1",
    null  // 无绑定参数
)

// kotlin
// 预编译语句复用示例：分页加载
fun queryUsers(page: Int, pageSize: Int = 20): List<User> {
    val offset = page * pageSize
    // 注意：LIMIT 和 OFFSET 的值不能通过 ? 绑定，必须字符串拼接
    // 因为 SQLite 不支持将 INTEGER 绑定到 LIMIT/OFFSET
    val sql = "SELECT * FROM user WHERE status = 1 ORDER BY id LIMIT $pageSize OFFSET $offset"
    val cursor = db.rawQuery(sql, null)
    // ... 处理游标
}

// kotlin
// 检查当前数据库的journal模式
val cursor = db.rawQuery("PRAGMA journal_mode", null)
if (cursor.moveToNext()) {
    val mode = cursor.getString(0)
    Log.d("DB", "Journal mode: $mode")  // 输出: WAL 或 DELETE 或 TRUNCATE 等
}
cursor.close()
 
// 设置为 DELETE 模式（传统rollback journal，适用于写入极频繁场景）
db.execSQL("PRAGMA journal_mode = DELETE")
 
// 设置为 TRUNCATE 模式（删除journal文件而非删除内容，性能略优）
db.execSQL("PRAGMA journal_mode = TRUNCATE")

// kotlin
// 使用 use 自动管理 Cursor 生命周期
val users = db.rawQuery(
    "SELECT * FROM user WHERE age >= ?",
    arrayOf("18")
).use { cursor ->
    // use 块结束后，cursor 自动关闭，无需手动 finally
    val list = mutableListOf<User>()
    while (cursor.moveToNext()) {
        list.add(
            User(
                name  = cursor.getString(cursor.getColumnIndexOrThrow("name")),
                age   = cursor.getInt(cursor.getColumnIndexOrThrow("age")),
                email = cursor.getString(cursor.getColumnIndexOrThrow("email"))
            )
        )
    }
    list  // use 块的最后一个表达式作为返回值
}

val db = helper.writableDatabase
db.beginTransaction()
try {
    repeat(10000) { i ->
        val name = "User_$i"
        // 【问题代码】字符串拼接构造 SQL
        db.execSQL("INSERT INTO user (name, age) VALUES ('$name', ${i % 100})")
    }
    db.setTransactionSuccessful()
} finally {
    db.endTransaction()
}

// kotlin - 改进后的版本
val db = helper.writableDatabase
db.beginTransaction()
try {
    repeat(10000) { i ->
        val name = "User_$i"
        // 使用绑定参数：安全且高效
        db.execSQL(
            "INSERT INTO user (name, age) VALUES (?, ?)",
            arrayOf(name, i % 100)
        )
    }
    db.setTransactionSuccessful()
} finally {
    db.endTransaction()
}

// kotlin
// 判断当前游标是否有效（已指向某一行数据）
cursor.isBeforeFirst()   // 游标是否在第一行之前（初始位置）
cursor.isAfterLast()     // 游标是否在最后一行之后
cursor.isFirst()         // 游标是否指向第一行
cursor.isLast()          // 游标是否指向最后一行
cursor.isPosition(position: Int)  // 游标是否指向指定位置
 
// 移动游标的方法——所有移动方法返回 Boolean，表示移动是否成功
cursor.moveToFirst()     // 移动到第一行
cursor.moveToLast()      // 移动到最后一行
cursor.moveToNext()      // 移动到下一行（最常用的遍历方式）
cursor.moveToPrevious()  // 移动到上一行
cursor.moveToPosition(position: Int)  // 移动到指定位置（从0开始）
cursor.move(offset: Int)  // 从当前位置相对移动 offset 行

// kotlin
// 根据列索引读取（索引从 0 开始，效率最高）
cursor.getInt(columnIndex: Int): Int
cursor.getLong(columnIndex: Int): Long
cursor.getString(columnIndex: Int): String
cursor.getFloat(columnIndex: Int): Float
cursor.getDouble(columnIndex: Int): Double
cursor.getShort(columnIndex: Int): Short
cursor.getByte(columnIndex: Int): Byte
 
// 根据列名读取（更易读，但每次都需要内部查找列索引）
cursor.getInt(columnName: String): Int
cursor.getString(columnName: String): String
// ... 其他类型同理
 
// 判断某列是否为 NULL（重要！直接读取可能返回默认值）
cursor.isNull(columnIndex: Int): Boolean
 
// 读取 byte 数组（适用于 BLOB 类型）
cursor.getBlob(columnIndex: Int): ByteArray

// kotlin
// 获取列的总数
cursor.columnCount: Int
 
// 根据列名获取列索引（内部维护了一个 HashMap，
// 因此查找是 O(1) 复杂度，但仍然不如直接用索引高效）
cursor.getColumnIndex(columnName: String): Int
cursor.getColumnIndexOrThrow(columnName: String): Int
// getColumnIndexOrThrow 与前者的区别在于：
// 当列名不存在时，前者返回 -1，后者抛出 IllegalArgumentException
 
// 获取指定索引的列名
cursor.getColumnName(index: Int): String
 
// 获取所有列名（返回一个 String 数组）
cursor.columnNames: Array<String>
 
// 获取游标当前所在行的行号（从 0 开始计数）
cursor.position: Int
 
// 获取结果集的总行数（有些 Cursor 实现可能返回 -1，需要注意）
cursor.count: Int

// kotlin
// 保存当前游标位置
cursor.setSelectionSelection(String: String)
 
// 恢复之前保存的游标位置（如果在数据变化后调用，
// 可能会恢复失败，此时返回 false）
cursor.respondToBoolean(): Boolean

// kotlin
// 标准遍历模式
val cursor = database.rawQuery(
    "SELECT id, name, age FROM users WHERE age > ?",
    arrayOf("18")
)  // 查询返回的 Cursor 默认位置在第一行之前（isBeforeFirst = true）
 
try {
    // moveToNext() 做了两件事：先移动游标，再判断移动后是否有效
    // 因此循环条件本身既是移动操作也是终止条件
    while (cursor.moveToNext()) {
        // 只有 moveToNext() 返回 true 时，才说明当前行有有效数据
        val id = cursor.getLong(cursor.getColumnIndexOrThrow("id"))
        val name = cursor.getString(cursor.getColumnIndexOrThrow("name"))
        val age = cursor.getInt(cursor.getColumnIndexOrThrow("age"))
 
        // 在这里进行数据处理，如添加到列表、构建对象等
        println("用户信息: id=$id, name=$name, age=$age")
    }
} finally {
    // 无论循环是否正常结束，都要关闭 Cursor
    cursor.close()
}

// moveToNext() 的等价实现逻辑（伪代码）
public boolean moveToNext() {
    if (position < count - 1) {
        position++;
        return true;
    }
    position = count; // 移动到 after-last 位置
    return false;
}

// kotlin
// 查询单条记录的高效写法（不需要循环）
val cursor = database.rawQuery(
    "SELECT name, email FROM users WHERE id = ?",
    arrayOf(userId.toString())
)
 
try {
    if (cursor.moveToFirst()) {
        // 已知只有一条结果，直接读取即可
        val name = cursor.getString(0)   // 直接用索引，性能最优
        val email = cursor.getString(1)
        println("用户: $name, 邮箱: $email")
    }
    // 如果结果为空，moveToFirst() 返回 false，不进入 if 分支
    // 不需要调用 cursor.moveToLast() 或其他判断
} finally {
    cursor.close()
}

// kotlin
val cursor = database.rawQuery(
    "SELECT * FROM products WHERE price < ?",
    arrayOf(maxPrice.toString())
)
 
cursor.use { // 使用 use 扩展函数，自动在作用域结束时调用 close()
    for (row in cursor) {
        // Kotlin 为 Cursor 实现了 Iterable 接口，
        // 每次迭代等价于调用 moveToNext()
        val productName = row.getString(row.getColumnIndexOrThrow("name"))
        val price = row.getDouble(row.getColumnIndexOrThrow("price"))
        // 处理数据...
    }
} // cursor.close() 自动调用

// kotlin
// 定义数据模型类
data class User(
    val id: Long,
    val name: String,
    val age: Int,
    val email: String?
)
 
// 将单条 Cursor 记录映射为 User 对象
fun Cursor.toUser(): User {
    // 在调用此方法前，必须确保游标已移动到有效行
    return User(
        id = getLong(getColumnIndexOrThrow("id")),
        name = getString(getColumnIndexOrThrow("name")),
        age = getInt(getColumnIndexOrThrow("age")),
        email = if (isNull(getColumnIndexOrThrow("email"))) null
                else getString(getColumnIndexOrThrow("email"))
    )
}
 
// 将整个 Cursor 结果集映射为 User 列表
fun Cursor.toUserList(): List<User> {
    val users = mutableListOf<User>()
    use { cursor ->  // use 确保 Cursor 自动关闭
        while (cursor.moveToNext()) {
            users.add(cursor.toUser())
        }
    }
    return users
}

// kotlin
import android.database.MatrixCursor
 
// 将 User 列表转换回 Cursor（模拟 ContentProvider 返回的数据格式）
fun List<User>.toCursor(): MatrixCursor {
    // 定义列名数组
    val columns = arrayOf("id", "name", "age", "email")
    val cursor = MatrixCursor(columns)
 
    for (user in this) {
        // addRow 接受一个 Object 数组，每个元素对应一列的值
        cursor.addRow(arrayOf(
            user.id,
            user.name,
            user.age,
            user.email  // nullable 值直接传入，MatrixCursor 会正确处理
        ))
    }
    return cursor
}

// kotlin
import android.content.ContentResolver
import android.net.Uri
 
// 定义 URI 和投影（projection）
val uri = Uri.parse("content://com.example.provider/users")
val projection = arrayOf("_id", "name", "age")  // 指定要查询的列
 
// 通过 ContentResolver 查询
val cursor: Cursor? = contentResolver.query(
    uri,
    projection,           // 列投影，null 表示返回所有列（但 "*" 不被支持）
    "age > ?",            // selection 条件（使用占位符 ? 更安全）
    arrayOf("18"),        // selectionArgs 参数数组
    "name ASC"            // sortOrder 排序
)
 
// 注意：通过 ContentResolver 返回的 Cursor 通常位于主进程，
// 而 ContentProvider 可能在子进程中运行。
// 为了确保线程安全，Cursor 的遍历操作应在同一个线程中完成。

// kotlin
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
 
class UserRepository(private val database: MyDatabase) {
 
    // 使用协程在 IO 线程执行数据库查询
    suspend fun getAllUsers(): List<User> = withContext(Dispatchers.IO) {
        val cursor = database.readableDatabase.rawQuery(
            "SELECT * FROM users ORDER BY name ASC",
            null
        )
 
        cursor.use { c ->   // use 函数确保资源释放
            val users = mutableListOf<User>()
            while (c.moveToNext()) {
                users.add(c.toUser())
            }
            users
        }
    }
 
    // 带条件的分页查询
    suspend fun getUsersByPage(page: Int, pageSize: Int): List<User> =
        withContext(Dispatchers.IO) {
            val offset = (page - 1) * pageSize
            val cursor = database.readableDatabase.rawQuery(
                """
                SELECT * FROM users
                ORDER BY create_time DESC
                LIMIT ? OFFSET ?
                """.trimIndent(),
                arrayOf(pageSize.toString(), offset.toString())
            )
 
            cursor.use { c ->
                val users = mutableListOf<User>()
                while (c.moveToNext()) {
                    users.add(c.toUser())
                }
                users
            }
        }
}

// kotlin
// 游标分页：使用最后一条记录的时间戳作为下一页的起点
suspend fun getUsersByCursor(
    lastTimestamp: Long?,
    pageSize: Int
): List<User> = withContext(Dispatchers.IO) {
    val selection = if (lastTimestamp != null) {
        "create_time < ?"  // 只取时间戳小于（更旧）记录，减少扫描量
    } else {
        null
    }
 
    val selectionArgs = if (lastTimestamp != null) {
        arrayOf(lastTimestamp.toString())
    } else {
        null
    }
 
    val cursor = database.readableDatabase.rawQuery(
        """
        SELECT * FROM users
        WHERE $selection
        ORDER BY create_time DESC
        LIMIT ?
        """.trimIndent(),
        selectionArgs?.plus(pageSize.toString())
            ?: arrayOf(pageSize.toString())
    )
 
    cursor.use { c ->
        val users = mutableListOf<User>()
        while (c.moveToNext()) {
            users.add(c.toUser())
        }
        users
    }
}

// kotlin
val cursor = database.rawQuery("SELECT * FROM users", null)
try {
    while (cursor.moveToNext()) {
        // 处理数据
    }
} finally {
    // finally 块确保即使 try 中抛出异常，cursor 也会被关闭
    cursor.close()
}

// kotlin
database.rawQuery("SELECT * FROM users", null).use { cursor ->
    // 在 use 作用域内，cursor 保持打开状态
    while (cursor.moveToNext()) {
        // 处理数据
    }
} // 作用域结束后，自动调用 cursor.close()

// use 函数的简化实现
public inline fun <T : java.io.Closeable?, R> T.use(
    block: (T) -> R
): R {
    var exception: Throwable? = null
    try {
        return block(this)
    } catch (e: Throwable) {
        exception = e
        throw e
    } finally {
        if (this != null) {
            if (exception != null) {
                try {
                    close()
                } catch (closeException: Throwable) {
                    // 抑制关闭时的异常，不覆盖原始异常
                    exception.addSuppressed(closeException)
                }
            } else {
                close()
            }
        }
    }
}

// kotlin
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.launch
 
class UserListFragment : Fragment() {
 
    private var cursor: Cursor? = null
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // 将数据库查询绑定到 Fragment 的生命周期
        viewLifecycleOwner.lifecycleScope.launch {
            val users = withContext(Dispatchers.IO) {
                // 在 IO 线程执行查询
                database.rawQuery("SELECT * FROM users", null).use { c ->
                    val list = mutableListOf<User>()
                    while (c.moveToNext()) {
                        list.add(c.toUser())
                    }
                    list
                }
            }
 
            // 只有当 Fragment 处于 STARTED 状态时才更新 UI
            // viewLifecycleOwner 确保我们使用 Fragment 的 view 生命周期
            // 而不是 Fragment 本身的生命周期
            viewLifecycleOwner.lifecycleScope.launch(Dispatchers.Main) {
                if (lifecycle.currentState.isAtLeast(Lifecycle.State.STARTED)) {
                    adapter.submitList(users)
                }
            }
        }
    }
 
    // 当 Fragment 销毁视图时，确保不会有悬空的 Cursor 引用
    override fun onDestroyView() {
        super.onDestroyView()
        cursor?.close()
        cursor = null
    }
}

// kotlin
val db = database.writableDatabase
db.beginTransaction()  // 开始事务
try {
    // 使用 SQLiteStatement 进行批量插入，性能远优于逐条 INSERT
    val stmt = db.compileStatement(
        "INSERT INTO users (name, age, email) VALUES (?, ?, ?)"
    )
 
    userList.forEach { user ->
        stmt.bindLong(1, user.id)
        stmt.bindString(2, user.name)
        stmt.bindLong(3, user.age.toLong())
        // 对于可能为 null 的列，使用 bindNull
        if (user.email != null) {
            stmt.bindString(4, user.email)
        } else {
            stmt.bindNull(4)
        }
        stmt.executeInsert()  // 执行插入并返回新行 ID
        stmt.clearBindings()  // 清空绑定值，准备下一次插入
    }
 
    db.setTransactionSuccessful()  // 标记事务成功
} finally {
    db.endTransaction()  // 提交或回滚
}

// kotlin
// 错误示例：跨线程使用 Cursor
val cursor = database.rawQuery("SELECT * FROM large_table", null)
 
// 在后台线程中遍历
thread {
    while (cursor.moveToNext()) {  // 没问题——后台线程读取数据
        // ...
    }
}.start()
 
// 同时在主线程访问 Cursor——危险！
// Cursor 的某些方法（如 getCount()）可能触发跨线程操作
// 导致 CursorWindow 读取位置混乱，甚至抛出
// "android.database.CursorWindowAllocationException"

// kotlin
// 场景一：Activity/Fragment 中使用 Cursor
// 最佳实践：将 Cursor 的生命周期与视图生命周期绑定
class UserListFragment : Fragment() {
 
    private var cursor: Cursor? = null
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // 在协程或线程中执行查询
        lifecycleScope.launch(Dispatchers.IO) {
            cursor = database.query(
                "users",
                arrayOf("id", "name", "email"),
                "age > ?",
                arrayOf("18"),
                null, null, "name ASC"
            )
 
            // 切换到主线程处理 UI
            withContext(Dispatchers.Main) {
                cursor?.let { c ->
                    adapter.swapCursor(c)  // swapCursor 不会关闭旧 Cursor
                }
            }
        }
    }
 
    override fun onDestroyView() {
        super.onDestroyView()
        // Fragment 视图销毁时，务必关闭 Cursor
        // 这是最重要的资源清理操作之一
        cursor?.close()
        cursor = null
    }
}

// kotlin
// 场景二：使用 try-with-resources 风格（Java）/ use 扩展函数（Kotlin）
// 自动关闭 Cursor，即使发生异常也能保证资源释放
fun getAllUsers(): List<User> {
    database.rawQuery(
        "SELECT id, name, email FROM users WHERE active = 1",
        null
    ).use { cursor ->  // use 扩展函数确保 cursor 在作用域结束时自动 close
        val users = mutableListOf<User>()
        while (cursor.moveToNext()) {
            users.add(cursor.toUser())
        }
        return users
    }
}

// kotlin
// 危险的代码：没有处理列不存在的情况
val cursor = database.rawQuery(
    "SELECT id, name, phone FROM users",  // 假设 phone 列在 v2 中被删除
    null
)
 
while (cursor.moveToNext()) {
    // 假设旧版本代码期望读取 phone 列
    // 在 v2 数据库中，phone 列已被删除
    val phoneIndex = cursor.getColumnIndex("phone")
    if (phoneIndex != -1) {  // 这个检查至关重要！
        val phone = cursor.getString(phoneIndex)
        // ... 处理 phone 数据
    }
}

// kotlin
// 分页查询：每页 20 条记录
fun queryUsersPage(pageIndex: Int, pageSize: Int = 20): Cursor {
    val offset = pageIndex * pageSize
    return database.rawQuery(
        """
        SELECT id, name, email, created_at
        FROM users
        WHERE active = 1
        ORDER BY created_at DESC
        LIMIT ? OFFSET ?
        """.trimIndent(),
        arrayOf(pageSize.toString(), offset.toString())
    )
}
 
// 在 UI 层使用 Cursor 的定位方法
fun displayPage(cursor: Cursor) {
    // moveToPosition 可以直接定位到指定位置
    // 这在 RecyclerView 等懒加载场景中非常有用
    if (cursor.moveToPosition(position)) {
        val id = cursor.getLong(cursor.getColumnIndexOrThrow("id"))
        val name = cursor.getString(cursor.getColumnIndexOrThrow("name"))
        // ... 绑定到视图
    }
}

// kotlin
// 手动管理事务的完整模式
val db = database.writableDatabase
 
db.beginTransaction()  // 开始事务，开启一个写入上下文
try {
    // 第一步：创建订单记录
    val orderId = db.insert("orders", null, ContentValues().apply {
        put("user_id", userId)
        put("total_amount", totalAmount)
        put("status", "pending")
        put("created_at", System.currentTimeMillis())
    })
 
    // 第二步：扣减库存——这是关键步骤
    // 如果库存不足，抛出异常，事务将回滚
    val affectedRows = db.update(
        "products",
        ContentValues().apply {
            put("stock", stock - quantity)  // 假设 stock 已在代码中计算
        },
        "id = ? AND stock >= ?",
        arrayOf(productId.toString(), quantity.toString())
    )
 
    if (affectedRows == 0) {
        throw IllegalStateException("库存不足或商品不存在")
    }
 
    // 第三步：记录库存变动日志
    db.insert("stock_logs", null, ContentValues().apply {
        put("product_id", productId)
        put("order_id", orderId)
        put("quantity_change", -quantity)
        put("created_at", System.currentTimeMillis())
    })
 
    // 第四步：扣减用户账户余额
    val walletUpdated = db.update(
        "wallets",
        ContentValues().apply {
            put("balance", "balance - $totalAmount")  // SQLite 支持算术表达式
        },
        "user_id = ? AND balance >= ?",
        arrayOf(userId.toString(), totalAmount.toString())
    )
 
    if (walletUpdated == 0) {
        throw IllegalStateException("余额不足")
    }
 
    // 标记事务成功——只有在所有操作都到达这里时才执行提交
    db.setTransactionSuccessful()
 
} catch (e: Exception) {
    // 任何异常都会被捕获，事务将不会调用 setTransactionSuccessful()
    // 因此 endTransaction() 会自动回滚所有未提交的操作
    Log.e("Transaction", "订单创建失败: ${e.message}", e)
    throw e  // 可选择重新抛出异常，让上层知道操作失败
 
} finally {
    // finally 块确保事务总是被正确结束
    // 如果 setTransactionSuccessful() 被调用了，endTransaction() 提交
    // 如果没有被调用，endTransaction() 回滚
    db.endTransaction()
}

// kotlin
// 使用 execSQL 执行批量 DDL（Data Definition Language）语句
val db = database.writableDatabase
 
db.beginTransaction()
try {
    // 在一个事务中执行多条 DDL 语句
    // 例如：应用首次启动时创建多个相关表
    db.execSQL("""
        CREATE TABLE IF NOT EXISTS categories (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL,
            description TEXT,
            parent_id INTEGER,
            FOREIGN KEY (parent_id) REFERENCES categories(id)
        )
    """.trimIndent())
 
    db.execSQL("""
        CREATE TABLE IF NOT EXISTS products (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL,
            category_id INTEGER NOT NULL,
            price REAL NOT NULL,
            stock INTEGER NOT NULL DEFAULT 0,
            created_at INTEGER NOT NULL,
            FOREIGN KEY (category_id) REFERENCES categories(id)
        )
    """.trimIndent())
 
    db.execSQL("""
        CREATE TABLE IF NOT EXISTS product_tags (
            product_id INTEGER NOT NULL,
            tag TEXT NOT NULL,
            PRIMARY KEY (product_id, tag),
            FOREIGN KEY (product_id) REFERENCES products(id)
        )
    """.trimIndent())
 
    // 插入初始分类数据
    db.execSQL(
        "INSERT INTO categories (name, description) VALUES (?, ?)",
        arrayOf("电子产品", "各类电子设备及配件")
    )
    db.execSQL(
        "INSERT INTO categories (name, description) VALUES (?, ?)",
        arrayOf("图书", "纸质书籍和电子书")
    )
 
    db.setTransactionSuccessful()
} finally {
    db.endTransaction()
}

// kotlin
// 批量导入用户数据：使用事务 + SQLiteStatement 获得最高性能
val db = database.writableDatabase
 
db.beginTransaction()
try {
    // 预编译一条带参数的 INSERT 语句
    // 只需要解析一次 SQL，绑定不同参数执行多次
    val insertStmt = db.compileStatement(
        "INSERT INTO users (name, email, age, department_id, created_at) VALUES (?, ?, ?, ?, ?)"
    )
 
    userDataList.forEachIndexed { index, user ->
        // 逐个绑定参数——bindLong/bindString 的性能远优于 ContentValues
        insertStmt.bindLong(1, user.id)
        insertStmt.bindString(2, user.name)
        insertStmt.bindString(3, user.email)
        insertStmt.bindLong(4, user.age.toLong())
        if (user.departmentId != null) {
            insertStmt.bindLong(5, user.departmentId)
        } else {
            insertStmt.bindNull(5)
        }
        insertStmt.bindLong(6, System.currentTimeMillis())
 
        // executeInsert() 返回新插入行的 rowId（主键）
        val newRowId = insertStmt.executeInsert()
 
        // 如果插入失败（主键冲突等），executeInsert() 返回 -1
        if (newRowId == -1L) {
            throw IllegalStateException("插入第 ${index + 1} 条记录失败: ${user.name}")
        }
 
        // 重要：清空已绑定的值，否则下次绑定会覆盖错误的数据
        insertStmt.clearBindings()
    }
 
    db.setTransactionSuccessful()
 
} finally {
    db.endTransaction()
}

// kotlin
// 健壮的事务处理：包含重试机制和详细日志
fun executeOrderTransaction(order: Order): Result<Order> {
    val maxRetries = 3
    var attempt = 0
 
    while (attempt < maxRetries) {
        attempt++
        val db = database.writableDatabase
 
        db.beginTransaction()
        try {
            val result = performOrderOperations(db, order)
            db.setTransactionSuccessful()
            return Result.success(result)
 
        } catch (e: SQLiteAbortException) {
            // SQLite 内部 abort，通常由程序错误引起
            // 不重试，直接报告错误
            Log.e("Transaction", "数据库中止 (尝试 $attempt/$maxRetries): ${e.message}")
            return Result.failure(e)
 
        } catch (e: SQLiteDatabaseLockedException) {
            // 数据库被另一个事务锁定
            // 这是 SQLite 在并发写入时最常见的异常
            // 适合重试：等待锁释放后重试
            Log.w("Transaction", "数据库被锁定 (尝试 $attempt/$maxRetries), 等待后重试...")
            Thread.sleep(100L * attempt)  // 递增等待时间
 
        } catch (e: SQLiteConstraintException) {
            // 约束违反（如 UNIQUE、NOT NULL、FOREIGN KEY 冲突）
            // 这类错误通常是数据问题，重试无济于事
            Log.e("Transaction", "约束违反: ${e.message}")
            return Result.failure(IllegalArgumentException("数据约束错误: ${e.message}", e))
 
        } catch (e: Exception) {
            // 其他未预期的异常
            Log.e("Transaction", "未知错误 (尝试 $attempt/$maxRetries): ${e.message}", e)
            if (attempt == maxRetries) {
                return Result.failure(e)
            }
 
        } finally {
            if (db.inTransaction()) {
                db.endTransaction()
            }
        }
    }
 
    return Result.failure(IllegalStateException("事务重试次数耗尽"))
}

// kotlin
// 使用保存点实现部分回滚
val db = database.writableDatabase
 
db.beginTransaction()
try {
    // 第一个保存点：用户注册阶段
    db.execSQL("SAVEPOINT user_registration")
 
    val userId = db.insert("users", null, ContentValues().apply {
        put("username", username)
        put("email", email)
        put("created_at", System.currentTimeMillis())
    })
 
    // 第二个保存点：权限初始化阶段
    db.execSQL("SAVEPOINT permission_init")
 
    // 分配默认角色
    db.insert("user_roles", null, ContentValues().apply {
        put("user_id", userId)
        put("role", "member")
    })
 
    // 第三个保存点：档案创建阶段
    db.execSQL("SAVEPOINT profile_creation")
 
    val profileId = db.insert("profiles", null, ContentValues().apply {
        put("user_id", userId)
        put("display_name", username)
    })
 
    // 假设在这里发现用户名已被占用
    if (isUsernameTaken) {
        // 回滚到用户注册保存点，放弃用户记录
        // 权限初始化和档案创建也会自动被撤销
        db.execSQL("ROLLBACK TO SAVEPOINT user_registration")
        throw IllegalArgumentException("用户名已被占用")
    }
 
    // 所有检查通过，释放保存点（从最后一个开始）
    db.execSQL("RELEASE SAVEPOINT profile_creation")
    db.execSQL("RELEASE SAVEPOINT permission_init")
    db.execSQL("RELEASE SAVEPOINT user_registration")
 
    db.setTransactionSuccessful()
 
} finally {
    db.endTransaction()
}