---@meta lsqlite3

--------------------------------------------------------------------------------
-- lsqlite3 C 模块
--------------------------------------------------------------------------------

---@alias lsqlite3_value nil|boolean|number|string
---@alias lsqlite3_row table<integer,lsqlite3_value>
---@alias lsqlite3_named_row table<string,lsqlite3_value>
---@alias lsqlite3_exec_callback fun(userdata:any, columns:integer, values:table, names:table):integer|boolean|nil
---@alias lsqlite3_busy_callback fun(userdata:any, tries:integer):boolean|integer|nil
---@alias lsqlite3_hook_callback fun(userdata:any, ...:any)
---@alias lsqlite3_scalar_callback fun(ctx:lsqlite3_context*, ...:lsqlite3_value)
---@alias lsqlite3_collation_callback fun(a:string, b:string):integer

---@class lsqlite3_context*
local lsqlite3_context = {}

--- 获取注册函数时保存的用户数据。
---@return any userdata 用户数据
function lsqlite3_context:user_data() end

--- 获取聚合上下文数据。
---@return any value 聚合数据
function lsqlite3_context:get_aggregate_data() end

--- 设置聚合上下文数据。
---@param value any 聚合数据
function lsqlite3_context:set_aggregate_data(value) end

--- 获取聚合调用次数。
---@return integer count 调用次数
function lsqlite3_context:aggregate_count() end

--- 设置 SQL 函数返回值。
---@param value lsqlite3_value 返回值
function lsqlite3_context:result(value) end

--- 设置 SQL 函数返回 NULL。
function lsqlite3_context:result_null() end

--- 设置 SQL 函数返回 number。
---@param value number 返回值
function lsqlite3_context:result_number(value) end

--- 设置 SQL 函数返回 double。
---@param value number 返回值
function lsqlite3_context:result_double(value) end

--- 设置 SQL 函数返回 integer。
---@param value integer 返回值
function lsqlite3_context:result_int(value) end

--- 设置 SQL 函数返回 text。
---@param value string 返回值
function lsqlite3_context:result_text(value) end

--- 设置 SQL 函数返回 blob。
---@param value string 返回值
function lsqlite3_context:result_blob(value) end

--- 设置 SQL 函数错误。
---@param message string 错误信息
function lsqlite3_context:result_error(message) end

---@class lsqlite3_backup*
local lsqlite3_backup = {}

--- 执行备份步进。
---@param pages integer 页数；-1 表示全部
---@return integer code SQLite 返回码
function lsqlite3_backup:step(pages) end

--- 返回剩余页数。
---@return integer count 剩余页数
function lsqlite3_backup:remaining() end

--- 返回总页数。
---@return integer count 总页数
function lsqlite3_backup:pagecount() end

--- 完成备份。
---@return integer code SQLite 返回码
function lsqlite3_backup:finish() end

---@class lsqlite3_stmt*
local lsqlite3_stmt = {}

--- 语句是否仍打开。
---@return boolean ok 是否打开
function lsqlite3_stmt:isopen() end

--- 执行一步。
---@return integer code SQLite 返回码
function lsqlite3_stmt:step() end

--- 重置语句。
---@return integer code SQLite 返回码
function lsqlite3_stmt:reset() end

--- 释放语句。
---@return integer code SQLite 返回码
function lsqlite3_stmt:finalize() end

--- 返回列数。
---@return integer count 列数
function lsqlite3_stmt:columns() end

--- 绑定一个参数。
---@param index integer 参数序号，从 1 开始
---@param value lsqlite3_value 参数值
---@return integer code SQLite 返回码
function lsqlite3_stmt:bind(index, value) end

--- 按顺序绑定所有参数。
---@param ... lsqlite3_value 参数值
---@return integer code SQLite 返回码
function lsqlite3_stmt:bind_values(...) end

--- 按名称或序号从 table 绑定参数。
---@param values table<string|integer,lsqlite3_value> 参数表
---@return integer code SQLite 返回码
function lsqlite3_stmt:bind_names(values) end

--- 绑定 blob 参数。
---@param index integer 参数序号，从 1 开始
---@param value string blob 数据
---@return integer code SQLite 返回码
function lsqlite3_stmt:bind_blob(index, value) end

--- 返回绑定参数数量。
---@return integer count 参数数量
function lsqlite3_stmt:bind_parameter_count() end

--- 返回绑定参数名。
---@param index integer 参数序号，从 1 开始
---@return string? name 参数名
function lsqlite3_stmt:bind_parameter_name(index) end

--- 获取当前行的列值。
---@param index integer 列序号，从 0 开始
---@return lsqlite3_value value 列值
function lsqlite3_stmt:get_value(index) end

--- 获取当前行全部列值。
---@return lsqlite3_row values 值列表
function lsqlite3_stmt:get_values() end

--- 获取列名。
---@param index integer 列序号，从 0 开始
---@return string name 列名
function lsqlite3_stmt:get_name(index) end

--- 获取全部列名。
---@return string[] names 列名列表
function lsqlite3_stmt:get_names() end

--- 获取列声明类型。
---@param index integer 列序号，从 0 开始
---@return string? typeName 类型名
function lsqlite3_stmt:get_type(index) end

--- 获取全部列声明类型。
---@return table<integer,string?> types 类型列表
function lsqlite3_stmt:get_types() end

--- 以多返回值返回当前行列值。
---@return lsqlite3_value ...
function lsqlite3_stmt:get_uvalues() end

--- 以多返回值返回列名。
---@return string ...
function lsqlite3_stmt:get_unames() end

--- 以多返回值返回列声明类型。
---@return string? ...
function lsqlite3_stmt:get_utypes() end

--- 以列名为键获取当前行值。
---@return lsqlite3_named_row values 值表
function lsqlite3_stmt:get_named_values() end

--- 以列名为键获取列声明类型。
---@return table<string,string?> types 类型表
function lsqlite3_stmt:get_named_types() end

--- 返回逐行迭代器，每行是数组表。
---@return fun():lsqlite3_row? iter 迭代器
---@return lsqlite3_stmt* stmt 语句对象
function lsqlite3_stmt:rows() end

--- 返回逐行迭代器，每行是列名键表。
---@return fun():lsqlite3_named_row? iter 迭代器
---@return lsqlite3_stmt* stmt 语句对象
function lsqlite3_stmt:nrows() end

--- 返回逐行迭代器，每行以多返回值返回。
---@return fun():lsqlite3_value ... iter 迭代器
---@return lsqlite3_stmt* stmt 语句对象
function lsqlite3_stmt:urows() end

--- 返回最近插入 rowid。
---@return integer|string rowid rowid
function lsqlite3_stmt:last_insert_rowid() end

--- `get_values` 兼容别名。
---@return lsqlite3_row values 值列表
function lsqlite3_stmt:idata() end

--- `get_names` 兼容别名。
---@return string[] names 列名列表
function lsqlite3_stmt:inames() end

--- `get_types` 兼容别名。
---@return table<integer,string?> types 类型列表
function lsqlite3_stmt:itypes() end

--- `get_named_values` 兼容别名。
---@return lsqlite3_named_row values 值表
function lsqlite3_stmt:data() end

--- `get_named_types` 兼容别名。
---@return table<string,string?> types 类型表
function lsqlite3_stmt:type() end

---@class lsqlite3_db*
local lsqlite3_db = {}

--- 数据库是否仍打开。
---@return boolean ok 是否打开
function lsqlite3_db:isopen() end

--- 返回最近插入 rowid。
---@return integer|string rowid rowid
function lsqlite3_db:last_insert_rowid() end

--- 返回最近语句影响行数。
---@return integer count 行数
function lsqlite3_db:changes() end

--- 返回连接累计影响行数。
---@return integer count 行数
function lsqlite3_db:total_changes() end

--- 返回最近 SQLite 错误码。
---@return integer code 错误码
function lsqlite3_db:errcode() end

--- 返回最近 SQLite 错误码。
---@return integer code 错误码
function lsqlite3_db:error_code() end

--- 返回最近 SQLite 错误信息。
---@return string message 错误信息
function lsqlite3_db:errmsg() end

--- 返回最近 SQLite 错误信息。
---@return string message 错误信息
function lsqlite3_db:error_message() end

--- 中断当前连接上的长时间操作。
function lsqlite3_db:interrupt() end

--- 返回指定数据库名对应的文件路径。
---@param name string 数据库名，通常为 `main`、`temp` 或 attached 名称
---@return string? filename 文件路径
function lsqlite3_db:db_filename(name) end

--- 注册标量 SQL 函数。
---@param name string SQL 函数名
---@param nargs integer 参数个数
---@param callback lsqlite3_scalar_callback 回调
---@param userdata? any 用户数据
---@return boolean ok 是否成功
function lsqlite3_db:create_function(name, nargs, callback, userdata) end

--- 注册聚合 SQL 函数。
---@param name string SQL 函数名
---@param nargs integer 参数个数
---@param step lsqlite3_scalar_callback step 回调
---@param final fun(ctx:lsqlite3_context*) finalize 回调
---@param userdata? any 用户数据
---@return boolean ok 是否成功
function lsqlite3_db:create_aggregate(name, nargs, step, final, userdata) end

--- 注册排序规则。
---@param name string 排序规则名
---@param callback? lsqlite3_collation_callback 回调；nil 表示移除
function lsqlite3_db:create_collation(name, callback) end

--- 加载 SQLite 扩展；不传扩展名时关闭扩展加载。
---@param extname? string 扩展路径
---@param entrypoint? string 入口函数名
---@return boolean ok 是否成功
---@return string? errMsg 错误信息
function lsqlite3_db:load_extension(extname, entrypoint) end

--- 设置 trace 回调。
---@param callback? fun(userdata:any, sql:string) 回调；nil 表示移除
---@param userdata? any 用户数据
function lsqlite3_db:trace(callback, userdata) end

--- 设置 progress 回调。
---@param opcodes? integer opcode 间隔；nil 表示移除
---@param callback? fun(userdata:any):boolean|integer|nil 回调
---@param userdata? any 用户数据
function lsqlite3_db:progress_handler(opcodes, callback, userdata) end

--- 设置 busy 超时毫秒数。
---@param ms integer 毫秒
function lsqlite3_db:busy_timeout(ms) end

--- 设置 busy 回调。
---@param callback? lsqlite3_busy_callback 回调；nil 表示移除
---@param userdata? any 用户数据
function lsqlite3_db:busy_handler(callback, userdata) end

--- 设置 update hook。
---@param callback? fun(userdata:any, operation:integer, database:string, tableName:string, rowid:integer|string) 回调；nil 表示移除
---@param userdata? any 用户数据
function lsqlite3_db:update_hook(callback, userdata) end

--- 设置 commit hook。
---@param callback? fun(userdata:any):boolean|integer|nil 回调；nil 表示移除
---@param userdata? any 用户数据
function lsqlite3_db:commit_hook(callback, userdata) end

--- 设置 rollback hook。
---@param callback? lsqlite3_hook_callback 回调；nil 表示移除
---@param userdata? any 用户数据
function lsqlite3_db:rollback_hook(callback, userdata) end

--- 编译 SQL 语句。
---@param sql string SQL 文本
---@return lsqlite3_stmt*? stmt 语句对象
---@return string|integer? tailOrCode 成功时为未编译尾部，失败时为错误码
function lsqlite3_db:prepare(sql) end

--- 执行 SQL 并返回数组行迭代器。
---@param sql string SQL 文本
---@param ... any 绑定参数或单个参数表
---@return fun():lsqlite3_row? iter 迭代器
---@return lsqlite3_stmt* stmt 临时语句对象
function lsqlite3_db:rows(sql, ...) end

--- 执行 SQL 并返回列名键行迭代器。
---@param sql string SQL 文本
---@param ... any 绑定参数或单个参数表
---@return fun():lsqlite3_named_row? iter 迭代器
---@return lsqlite3_stmt* stmt 临时语句对象
function lsqlite3_db:nrows(sql, ...) end

--- 执行 SQL 并以多返回值逐行迭代。
---@param sql string SQL 文本
---@param ... any 绑定参数或单个参数表
---@return fun():lsqlite3_value ... iter 迭代器
---@return lsqlite3_stmt* stmt 临时语句对象
function lsqlite3_db:urows(sql, ...) end

--- 执行 SQL。
---@param sql string SQL 文本
---@param callback? lsqlite3_exec_callback 行回调
---@param userdata? any 用户数据
---@return integer code SQLite 返回码
function lsqlite3_db:exec(sql, callback, userdata) end

--- 执行 SQL。
---@param sql string SQL 文本
---@param callback? lsqlite3_exec_callback 行回调
---@param userdata? any 用户数据
---@return integer code SQLite 返回码
function lsqlite3_db:execute(sql, callback, userdata) end

--- 关闭数据库。
---@return integer? code SQLite 返回码
function lsqlite3_db:close() end

--- 关闭指定语句或当前连接关联语句。
---@param stmt? lsqlite3_stmt* 语句对象
---@return integer? code SQLite 返回码
function lsqlite3_db:close_vm(stmt) end

--- 获取底层 sqlite3 指针。
---@return lightuserdata ptr sqlite3 指针
function lsqlite3_db:get_ptr() end

---@class lsqlite3*
---@field OK integer
---@field ERROR integer
---@field INTERNAL integer
---@field PERM integer
---@field ABORT integer
---@field BUSY integer
---@field LOCKED integer
---@field NOMEM integer
---@field READONLY integer
---@field INTERRUPT integer
---@field IOERR integer
---@field CORRUPT integer
---@field NOTFOUND integer
---@field FULL integer
---@field CANTOPEN integer
---@field PROTOCOL integer
---@field EMPTY integer
---@field SCHEMA integer
---@field TOOBIG integer
---@field CONSTRAINT integer
---@field MISMATCH integer
---@field MISUSE integer
---@field NOLFS integer
---@field FORMAT integer
---@field NOTADB integer
---@field RANGE integer
---@field ROW integer
---@field DONE integer
---@field INTEGER integer
---@field FLOAT integer
---@field TEXT integer
---@field BLOB integer
---@field NULL integer
---@field CREATE_INDEX integer
---@field CREATE_TABLE integer
---@field CREATE_TEMP_INDEX integer
---@field CREATE_TEMP_TABLE integer
---@field CREATE_TEMP_TRIGGER integer
---@field CREATE_TEMP_VIEW integer
---@field CREATE_TRIGGER integer
---@field CREATE_VIEW integer
---@field DELETE integer
---@field DROP_INDEX integer
---@field DROP_TABLE integer
---@field DROP_TEMP_INDEX integer
---@field DROP_TEMP_TABLE integer
---@field DROP_TEMP_TRIGGER integer
---@field DROP_TEMP_VIEW integer
---@field DROP_TRIGGER integer
---@field DROP_VIEW integer
---@field INSERT integer
---@field PRAGMA integer
---@field READ integer
---@field SELECT integer
---@field TRANSACTION integer
---@field UPDATE integer
---@field ATTACH integer
---@field DETACH integer
---@field ALTER_TABLE integer
---@field REINDEX integer
---@field ANALYZE integer
---@field CREATE_VTABLE integer
---@field DROP_VTABLE integer
---@field FUNCTION integer
---@field SAVEPOINT integer
---@field OPEN_READONLY integer
---@field OPEN_READWRITE integer
---@field OPEN_CREATE integer
---@field OPEN_URI integer
---@field OPEN_MEMORY integer
---@field OPEN_NOMUTEX integer
---@field OPEN_FULLMUTEX integer
---@field OPEN_SHAREDCACHE integer
---@field OPEN_PRIVATECACHE integer
---@type lsqlite3*
local M = {}

--- 返回 lsqlite3 绑定版本。
---@return string version 绑定版本
function M.lversion() end

--- 返回底层 SQLite 版本。
---@return string version SQLite 版本
function M.version() end

--- 判断 SQL 是否为完整语句。
---@param sql string SQL 文本
---@return boolean ok 是否完整
function M.complete(sql) end

--- 获取或设置 SQLite 临时目录。
---@param path? string|nil 新临时目录；nil 表示清空
---@return string? oldPath 旧临时目录
function M.temp_directory(path) end

--- 打开数据库。
---@param filename string 文件路径
---@param flags? integer open flags，默认 `OPEN_READWRITE | OPEN_CREATE`
---@return lsqlite3_db*? db 数据库对象
---@return integer? errCode 错误码
---@return string? errMsg 错误信息
function M.open(filename, flags) end

--- 打开内存数据库。
---@return lsqlite3_db*? db 数据库对象
---@return integer? errCode 错误码
---@return string? errMsg 错误信息
function M.open_memory() end

--- 从底层 sqlite3 指针打开数据库对象。
---@param ptr lightuserdata sqlite3 指针
---@return lsqlite3_db* db 数据库对象
function M.open_ptr(ptr) end

--- 初始化在线备份。
---@param target lsqlite3_db* 目标数据库
---@param targetName string 目标数据库名
---@param source lsqlite3_db* 源数据库
---@param sourceName string 源数据库名
---@return lsqlite3_backup*? backup 备份对象
function M.backup_init(target, targetName, source, sourceName) end

return M
