app.database - SQLite 数据库 API

SQLite 数据库操作。

连接管理

app.database.open(path)

打开或创建数据库。

参数:

• path (string) - 数据库文件路径（支持 ~ 展开）

返回值: number, error - 数据库句柄，失败时返回 nil, error

local db, err = app.database.open("~/data/my.db")
if db then
    -- 使用数据库
    app.database.close(db)
end

app.database.close(handle)

关闭数据库连接。

参数:

• handle (number) - 数据库句柄

返回值: boolean, error - 是否成功，失败时返回 false, error

local ok, err = app.database.close(db)

SQL 执行

app.database.execute(handle, sql, params?)

执行 SQL 语句（INSERT/UPDATE/DELETE/CREATE 等）。

参数:

• handle (number) - 数据库句柄
• sql (string) - SQL 语句
• params (array, 可选) - 参数数组

返回值: boolean, error - 是否成功，失败时返回 false, error

-- 创建表
app.database.execute(db, [[
    CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        name TEXT NOT NULL,
        email TEXT UNIQUE,
        created_at INTEGER DEFAULT (strftime('%s', 'now'))
    )
]])

-- 插入数据（位置参数）
app.database.execute(db, "INSERT INTO users (name, email) VALUES (?, ?)",
    {"张三", "zhangsan@example.com"})

app.database.query(handle, sql, params?)

查询数据。

参数:

• handle (number) - 数据库句柄
• sql (string) - SQL 查询语句
• params (array, 可选) - 参数数组

返回值: array, error - 结果行数组（每行是键值对表），失败时返回 nil, error

-- 查询所有
local users = app.database.query(db, "SELECT * FROM users")
if users then
    for _, user in ipairs(users) do
        app.log.info(user.name .. " - " .. user.email)
    end
end

-- 带条件查询
local results = app.database.query(db, "SELECT * FROM users WHERE id = ?", {1})

事务

app.database.begin(handle)

开始事务。

返回值: boolean, error - 是否成功，失败时返回 false, error

app.database.begin(db)

app.database.commit(handle)

提交事务。

返回值: boolean, error - 是否成功，失败时返回 false, error

app.database.commit(db)

app.database.rollback(handle)

回滚事务。

返回值: boolean, error - 是否成功，失败时返回 false, error

app.database.rollback(db)

事务示例:

app.database.begin(db)
local ok1 = app.database.execute(db, "INSERT INTO users (name) VALUES (?)", {"用户1"})
local ok2 = app.database.execute(db, "INSERT INTO users (name) VALUES (?)", {"用户2"})

if ok1 and ok2 then
    app.database.commit(db)
else
    app.database.rollback(db)
end

辅助方法

app.database.changes(handle)

获取上次操作影响的行数。

返回值: number

app.database.execute(db, "UPDATE users SET name = ? WHERE id > ?", {"更新", 10})
local affected = app.database.changes(db)

app.database.lastInsertId(handle)

获取最后插入的行 ID。

返回值: number

app.database.execute(db, "INSERT INTO users (name) VALUES (?)", {"测试"})
local id = app.database.lastInsertId(db)

app.database.tableExists(handle, tableName)

检查表是否存在。

参数:

• handle (number) - 数据库句柄
• tableName (string) - 表名

返回值: boolean, error - 失败时返回 false, error

if not app.database.tableExists(db, "users") then
    -- 创建表
end

app.database.tables(handle)

列出所有表名。

返回值: array, error - 表名数组，失败时返回 nil, error

local tables = app.database.tables(db)
if tables then
    for _, name in ipairs(tables) do
        app.log.info("表: " .. name)
    end
end

app.database.columns(handle, tableName)

获取表的列信息。

参数:

• handle (number) - 数据库句柄
• tableName (string) - 表名

返回值: array, error - 列信息数组，失败时返回 nil, error

local columns = app.database.columns(db, "users")
if columns then
    for _, col in ipairs(columns) do
        app.log.info(col.name .. " - " .. col.type)
        -- col.notnull: boolean
        -- col.defaultValue: any
        -- col.primaryKey: boolean
    end
end

示例

文件索引数据库

function MyPlugin:init()
    local pluginDir = app.context.pluginDirectory()
    local dbPath = app.path.join(pluginDir, "index.db")
    self.db = app.database.open(dbPath)

    app.database.execute(self.db, [[
        CREATE TABLE IF NOT EXISTS files (
            id INTEGER PRIMARY KEY,
            path TEXT UNIQUE,
            name TEXT,
            size INTEGER,
            modified INTEGER,
            hash TEXT,
            indexed_at INTEGER
        )
    ]])

    app.database.execute(self.db, "CREATE INDEX IF NOT EXISTS idx_files_name ON files(name)")
end

function MyPlugin:indexFile(path)
    local size = app.file.size(path)
    local modified = app.file.modificationDate(path)
    local hash = app.crypto.md5File(path)

    app.database.execute(self.db, [[
        INSERT OR REPLACE INTO files (path, name, size, modified, hash, indexed_at)
        VALUES (?, ?, ?, ?, ?, ?)
    ]], {
        path,
        app.path.basename(path),
        size,
        modified,
        hash,
        app.date.now()
    })
end

function MyPlugin:searchFiles(query)
    return app.database.query(self.db,
        "SELECT * FROM files WHERE name LIKE ? ORDER BY modified DESC",
        {"%" .. query .. "%"}
    )
end

function MyPlugin:cleanup()
    app.database.close(self.db)
end