SQL 数据库
SQL 数据库
Section titled “SQL 数据库”对 PostgreSQL、MySQL 和 SQLite 数据库执行 SQL 查询。支持参数化查询、事务、预处理语句和流式查询构建器。
数据库配置请参阅 数据库。
local sql = require("sql")从资源注册表获取数据库连接:
local db, err = sql.get("app.db:main")if err then return nil, errend
local rows = db:query("SELECT * FROM users WHERE active = ?", {1})
db:release()| 参数 | 类型 | 描述 |
|---|---|---|
id | string | 资源 ID(例如 “app.db:main”) |
返回: DB, error
sql.type.POSTGRES -- "postgres"sql.type.MYSQL -- "mysql"sql.type.SQLITE -- "sqlite"sql.type.UNKNOWN -- "unknown"sql.isolation.DEFAULT -- "default"sql.isolation.READ_UNCOMMITTED -- "read_uncommitted"sql.isolation.READ_COMMITTED -- "read_committed"sql.isolation.WRITE_COMMITTED -- "write_committed"sql.isolation.REPEATABLE_READ -- "repeatable_read"sql.isolation.SERIALIZABLE -- "serializable"NULL 值
Section titled “NULL 值”local insert = sql.builder.insert("users") :columns("name", "email") :values("alice", sql.NULL)as.int
Section titled “as.int”local value = sql.as.int(42)返回: userdata
as.float
Section titled “as.float”将值转换为 SQL float 类型。
local value = sql.as.float(19.99)返回: userdata
as.text
Section titled “as.text”将值转换为 SQL text 类型。
local value = sql.as.text("hello")返回: userdata
as.binary
Section titled “as.binary”将值转换为 SQL binary 类型。
local value = sql.as.binary("binary data")返回: userdata
as.null
Section titled “as.null”返回 SQL NULL 标记。
local value = sql.as.null()返回: userdata
local query = sql.builder.select("id", "name") :from("users") :where({active = 1})| 参数 | 类型 | 描述 |
|---|---|---|
columns | …string | 列名(可选) |
返回: SelectBuilder
builder.insert
Section titled “builder.insert”创建 INSERT 查询构建器。
local query = sql.builder.insert("users") :columns("name", "email") :values("alice", "alice@example.com")| 参数 | 类型 | 描述 |
|---|---|---|
table | string | 表名(可选) |
返回: InsertBuilder
builder.update
Section titled “builder.update”创建 UPDATE 查询构建器。
local query = sql.builder.update("users") :set("status", "active") :where({id = 123})| 参数 | 类型 | 描述 |
|---|---|---|
table | string | 表名(可选) |
返回: UpdateBuilder
builder.delete
Section titled “builder.delete”创建 DELETE 查询构建器。
local query = sql.builder.delete("users") :where({active = 0}) :limit(100)| 参数 | 类型 | 描述 |
|---|---|---|
table | string | 表名(可选) |
返回: DeleteBuilder
builder.expr
Section titled “builder.expr”创建用于 where/having 子句的原始 SQL 表达式。
local expr = sql.builder.expr("score BETWEEN ? AND ?", 80, 90)| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL 表达式 |
args | …any | 绑定参数(可选) |
返回: Sqlizer
builder.eq
Section titled “builder.eq”从表创建等值条件。
local cond = sql.builder.eq({active = 1, status = "open"})| 参数 | 类型 | 描述 |
|---|---|---|
map | table | {列名 = 值} 键值对 |
返回: Sqlizer
builder.not_eq
Section titled “builder.not_eq”从表创建不等条件。
local cond = sql.builder.not_eq({status = "closed"})| 参数 | 类型 | 描述 |
|---|---|---|
map | table | {列名 = 值} 键值对 |
返回: Sqlizer
builder.lt
Section titled “builder.lt”从表创建小于条件。
local cond = sql.builder.lt({age = 18})| 参数 | 类型 | 描述 |
|---|---|---|
map | table | {列名 = 值} 键值对 |
返回: Sqlizer
builder.lte
Section titled “builder.lte”从表创建小于等于条件。
local cond = sql.builder.lte({price = 100})| 参数 | 类型 | 描述 |
|---|---|---|
map | table | {列名 = 值} 键值对 |
返回: Sqlizer
builder.gt
Section titled “builder.gt”从表创建大于条件。
local cond = sql.builder.gt({score = 80})| 参数 | 类型 | 描述 |
|---|---|---|
map | table | {列名 = 值} 键值对 |
返回: Sqlizer
builder.gte
Section titled “builder.gte”从表创建大于等于条件。
local cond = sql.builder.gte({age = 21})| 参数 | 类型 | 描述 |
|---|---|---|
map | table | {列名 = 值} 键值对 |
返回: Sqlizer
builder.like
Section titled “builder.like”从表创建 LIKE 条件。
local cond = sql.builder.like({name = "john%"})| 参数 | 类型 | 描述 |
|---|---|---|
map | table | {列名 = 值} 键值对 |
返回: Sqlizer
builder.not_like
Section titled “builder.not_like”从表创建 NOT LIKE 条件。
local cond = sql.builder.not_like({email = "%@spam.com"})| 参数 | 类型 | 描述 |
|---|---|---|
map | table | {列名 = 值} 键值对 |
返回: Sqlizer
builder.and_
Section titled “builder.and_”用 AND 组合多个条件。
local cond = sql.builder.and_({ sql.builder.eq({active = 1}), sql.builder.gt({score = 80})})| 参数 | 类型 | 描述 |
|---|---|---|
conditions | table | Sqlizer 或表条件数组 |
返回: Sqlizer
builder.or_
Section titled “builder.or_”用 OR 组合多个条件。
local cond = sql.builder.or_({ sql.builder.eq({status = "pending"}), sql.builder.eq({status = "active"})})| 参数 | 类型 | 描述 |
|---|---|---|
conditions | table | Sqlizer 或表条件数组 |
返回: Sqlizer
builder.question
Section titled “builder.question”? 占位符格式(默认)。可作为 sql.builder.default_placeholder 别名使用。
local query = sql.builder.select("*") :from("users") :placeholder_format(sql.builder.question)builder.dollar
Section titled “builder.dollar”$1, $2, … 占位符格式。
local query = sql.builder.select("*") :from("users") :placeholder_format(sql.builder.dollar)builder.at
Section titled “builder.at”@p1, @p2, ... 占位符格式(SQL Server 风格)。像上面的格式一样传给 placeholder_format。
builder.colon
Section titled “builder.colon”:1, :2, ... 占位符格式。像上面的格式一样传给 placeholder_format。
sql.get() 返回的数据库连接句柄。
db:type
Section titled “db:type”返回数据库类型常量。
local dbtype, err = db:type()返回: string, error
db:query
Section titled “db:query”执行 SELECT 查询并返回行。
local rows, err = db:query("SELECT id, name FROM users WHERE active = ?", {1})| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL 查询 |
params | table | 绑定参数数组(可选) |
返回: table[], error
db:execute
Section titled “db:execute”执行 INSERT/UPDATE/DELETE 查询。
local result, err = db:execute("INSERT INTO users (name) VALUES (?)", {"alice"})| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL 语句 |
params | table | 绑定参数数组(可选) |
返回: table, error
返回包含以下字段的表:
last_insert_id- 最后插入的 IDrows_affected- 受影响的行数
db:prepare
Section titled “db:prepare”创建可重复执行的预处理语句。
local stmt, err = db:prepare("SELECT * FROM users WHERE id = ?")| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL |
返回: Statement, error
db:begin
Section titled “db:begin”开始数据库事务。
local tx, err = db:begin({ isolation = sql.isolation.SERIALIZABLE, read_only = false})| 参数 | 类型 | 描述 |
|---|---|---|
options | table | 事务选项(可选) |
选项表字段:
isolation- 来自 sql.isolation.* 的隔离级别(默认:DEFAULT)read_only- 只读事务标志(默认:false)
返回: Transaction, error
db:release
Section titled “db:release”将数据库资源释放回连接池。
local ok, err = db:release()返回: boolean, error
db:stats
Section titled “db:stats”返回连接池统计信息。
local stats, err = db:stats()返回: table, error
返回包含以下字段的表:
max_open_connections- 最大允许的打开连接数open_connections- 当前打开的连接数in_use- 当前正在使用的连接数idle- 池中的空闲连接数wait_count- 总连接等待计数wait_duration- 总等待时间max_idle_closed- 因达到最大空闲数而关闭的连接数max_idle_time_closed- 因空闲超时而关闭的连接数max_lifetime_closed- 因达到最大生命周期而关闭的连接数
db:prepare() 返回的预处理语句。
stmt:query
Section titled “stmt:query”将预处理语句作为 SELECT 执行。
local rows, err = stmt:query({123})| 参数 | 类型 | 描述 |
|---|---|---|
params | table | 绑定参数数组(可选) |
返回: table[], error
stmt:execute
Section titled “stmt:execute”将预处理语句作为 INSERT/UPDATE/DELETE 执行。
local result, err = stmt:execute({"alice"})| 参数 | 类型 | 描述 |
|---|---|---|
params | table | 绑定参数数组(可选) |
返回: table, error
返回包含以下字段的表:
last_insert_id- 最后插入的 IDrows_affected- 受影响的行数
stmt:close
Section titled “stmt:close”关闭预处理语句。
local ok, err = stmt:close()返回: boolean, error
db:begin() 返回的数据库事务。
tx:db_type
Section titled “tx:db_type”返回数据库类型常量。
local dbtype, err = tx:db_type()返回: string, error
tx:query
Section titled “tx:query”在事务中执行 SELECT 查询。
local rows, err = tx:query("SELECT id, name FROM users WHERE active = ?", {1})| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL 查询 |
params | table | 绑定参数数组(可选) |
返回: table[], error
tx:execute
Section titled “tx:execute”在事务中执行 INSERT/UPDATE/DELETE。
local result, err = tx:execute("INSERT INTO users (name) VALUES (?)", {"alice"})| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL 语句 |
params | table | 绑定参数数组(可选) |
返回: table, error
返回包含以下字段的表:
last_insert_id- 最后插入的 IDrows_affected- 受影响的行数
tx:prepare
Section titled “tx:prepare”在事务中创建预处理语句。
local stmt, err = tx:prepare("SELECT * FROM users WHERE id = ?")| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL |
返回: Statement, error
tx:commit
Section titled “tx:commit”提交事务。
local ok, err = tx:commit()返回: boolean, error
tx:rollback
Section titled “tx:rollback”回滚事务。
local ok, err = tx:rollback()返回: boolean, error
tx:savepoint
Section titled “tx:savepoint”在事务中创建命名保存点。
local ok, err = tx:savepoint("sp1")| 参数 | 类型 | 描述 |
|---|---|---|
name | string | 保存点名称(仅限字母数字和下划线) |
返回: boolean, error
tx:rollback_to
Section titled “tx:rollback_to”回滚到命名保存点。
local ok, err = tx:rollback_to("sp1")| 参数 | 类型 | 描述 |
|---|---|---|
name | string | 保存点名称 |
返回: boolean, error
tx:release
Section titled “tx:release”释放保存点。
local ok, err = tx:release("sp1")| 参数 | 类型 | 描述 |
|---|---|---|
name | string | 保存点名称 |
返回: boolean, error
SELECT 构建器
Section titled “SELECT 构建器”用于构建 SELECT 查询的流式接口。
select:from
Section titled “select:from”设置 FROM 子句。
local query = sql.builder.select("id", "name"):from("users")| 参数 | 类型 | 描述 |
|---|---|---|
table | string | 表名 |
返回: SelectBuilder
select:join
Section titled “select:join”添加 JOIN 子句。
local query = sql.builder.select("*") :from("users") :join("orders ON orders.user_id = users.id")| 参数 | 类型 | 描述 |
|---|---|---|
join | string | 带 ? 占位符的 JOIN 子句 |
args | …any | 绑定参数(可选) |
返回: SelectBuilder
select:left_join
Section titled “select:left_join”添加 LEFT JOIN 子句。
local query = sql.builder.select("*") :from("users") :left_join("orders ON orders.user_id = users.id")| 参数 | 类型 | 描述 |
|---|---|---|
join | string | 带 ? 占位符的 JOIN 子句 |
args | …any | 绑定参数(可选) |
返回: SelectBuilder
select:right_join
Section titled “select:right_join”添加 RIGHT JOIN 子句。
local query = sql.builder.select("*") :from("users") :right_join("orders ON orders.user_id = users.id")| 参数 | 类型 | 描述 |
|---|---|---|
join | string | 带 ? 占位符的 JOIN 子句 |
args | …any | 绑定参数(可选) |
返回: SelectBuilder
select:inner_join
Section titled “select:inner_join”添加 INNER JOIN 子句。
local query = sql.builder.select("*") :from("users") :inner_join("orders ON orders.user_id = users.id")| 参数 | 类型 | 描述 |
|---|---|---|
join | string | 带 ? 占位符的 JOIN 子句 |
args | …any | 绑定参数(可选) |
返回: SelectBuilder
select:where
Section titled “select:where”添加 WHERE 条件。
local query = sql.builder.select("*") :from("users") :where({active = 1})| 参数 | 类型 | 描述 |
|---|---|---|
condition | string|table|Sqlizer | WHERE 条件 |
args | …any | 绑定参数(可选,使用字符串时) |
支持三种格式:
- 字符串:
where("status = ?", "active") - 表:
where({status = "active"}) - Sqlizer:
where(sql.builder.gt({score = 80}))
返回: SelectBuilder
select:order_by
Section titled “select:order_by”添加 ORDER BY 子句。
local query = sql.builder.select("*") :from("users") :order_by("name ASC", "created_at DESC")| 参数 | 类型 | 描述 |
|---|---|---|
columns | …string | 列名(可选带 ASC/DESC) |
返回: SelectBuilder
select:group_by
Section titled “select:group_by”添加 GROUP BY 子句。
local query = sql.builder.select("status", "COUNT(*)") :from("users") :group_by("status")| 参数 | 类型 | 描述 |
|---|---|---|
columns | …string | 列名 |
返回: SelectBuilder
select:having
Section titled “select:having”添加 HAVING 条件。
local query = sql.builder.select("status", "COUNT(*) as cnt") :from("users") :group_by("status") :having(sql.builder.gt({cnt = 10}))| 参数 | 类型 | 描述 |
|---|---|---|
condition | string|table|Sqlizer | HAVING 条件 |
args | …any | 绑定参数(可选,使用字符串时) |
返回: SelectBuilder
select:limit
Section titled “select:limit”设置 LIMIT。
local query = sql.builder.select("*") :from("users") :limit(10)| 参数 | 类型 | 描述 |
|---|---|---|
n | integer | 限制值 |
返回: SelectBuilder
select:offset
Section titled “select:offset”设置 OFFSET。
local query = sql.builder.select("*") :from("users") :offset(20)| 参数 | 类型 | 描述 |
|---|---|---|
n | integer | 偏移值 |
返回: SelectBuilder
select:columns
Section titled “select:columns”向 SELECT 添加列。
local query = sql.builder.select():columns("id", "name", "email")| 参数 | 类型 | 描述 |
|---|---|---|
columns | …string | 列名 |
返回: SelectBuilder
select:distinct
Section titled “select:distinct”添加 DISTINCT 修饰符。
local query = sql.builder.select("status") :from("users") :distinct()返回: SelectBuilder
select:suffix
Section titled “select:suffix”添加 SQL 后缀。
local query = sql.builder.select("*") :from("users") :suffix("FOR UPDATE")| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL 后缀 |
args | …any | 绑定参数(可选) |
返回: SelectBuilder
select:placeholder_format
Section titled “select:placeholder_format”设置占位符格式。
local query = sql.builder.select("*") :from("users") :placeholder_format(sql.builder.dollar)| 参数 | 类型 | 描述 |
|---|---|---|
format | userdata | 占位符格式(sql.builder.*) |
返回: SelectBuilder
select:to_sql
Section titled “select:to_sql”生成 SQL 字符串和绑定参数。
local sql_str, args = query:to_sql()返回: string, table
select:run_with
Section titled “select:run_with”创建查询执行器。
local executor = query:run_with(db)local rows, err = executor:query()| 参数 | 类型 | 描述 |
|---|---|---|
db | DB|Transaction | 数据库或事务句柄 |
返回: QueryExecutor
INSERT 构建器
Section titled “INSERT 构建器”用于构建 INSERT 查询的流式接口。
insert:into
Section titled “insert:into”设置表名。
local query = sql.builder.insert():into("users")| 参数 | 类型 | 描述 |
|---|---|---|
table | string | 表名 |
返回: InsertBuilder
insert:columns
Section titled “insert:columns”设置列名。
local query = sql.builder.insert("users"):columns("name", "email")| 参数 | 类型 | 描述 |
|---|---|---|
columns | …string | 列名 |
返回: InsertBuilder
insert:values
Section titled “insert:values”添加行值。
local query = sql.builder.insert("users") :columns("name", "email") :values("alice", "alice@example.com")| 参数 | 类型 | 描述 |
|---|---|---|
values | …any | 行值 |
返回: InsertBuilder
insert:set_map
Section titled “insert:set_map”从表设置列和值。
local query = sql.builder.insert("users") :set_map({name = "alice", email = "alice@example.com"})| 参数 | 类型 | 描述 |
|---|---|---|
map | table | {列名 = 值} 键值对 |
返回: InsertBuilder
insert:select
Section titled “insert:select”从 SELECT 查询插入。
local select_query = sql.builder.select("name", "email"):from("temp_users")local query = sql.builder.insert("users") :columns("name", "email") :select(select_query)| 参数 | 类型 | 描述 |
|---|---|---|
query | SelectBuilder | SELECT 查询 |
返回: InsertBuilder
insert:prefix
Section titled “insert:prefix”添加 SQL 前缀。
local query = sql.builder.insert("users") :prefix("INSERT IGNORE INTO")| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL 前缀 |
args | …any | 绑定参数(可选) |
返回: InsertBuilder
insert:suffix
Section titled “insert:suffix”添加 SQL 后缀。
local query = sql.builder.insert("users") :columns("name") :values("alice") :suffix("RETURNING id")| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL 后缀 |
args | …any | 绑定参数(可选) |
返回: InsertBuilder
insert:options
Section titled “insert:options”添加 INSERT 选项。
local query = sql.builder.insert("users") :options("DELAYED", "IGNORE")| 参数 | 类型 | 描述 |
|---|---|---|
options | …string | INSERT 选项 |
返回: InsertBuilder
insert:placeholder_format
Section titled “insert:placeholder_format”设置占位符格式。
local query = sql.builder.insert("users") :placeholder_format(sql.builder.dollar)| 参数 | 类型 | 描述 |
|---|---|---|
format | userdata | 占位符格式(sql.builder.*) |
返回: InsertBuilder
insert:to_sql
Section titled “insert:to_sql”生成 SQL 字符串和绑定参数。
local sql_str, args = query:to_sql()返回: string, table
insert:run_with
Section titled “insert:run_with”创建查询执行器。
local executor = query:run_with(db)local result, err = executor:exec()| 参数 | 类型 | 描述 |
|---|---|---|
db | DB|Transaction | 数据库或事务句柄 |
返回: QueryExecutor
UPDATE 构建器
Section titled “UPDATE 构建器”用于构建 UPDATE 查询的流式接口。
update:table
Section titled “update:table”设置表名。
local query = sql.builder.update():table("users")| 参数 | 类型 | 描述 |
|---|---|---|
table | string | 表名 |
返回: UpdateBuilder
update:set
Section titled “update:set”设置列值。
local query = sql.builder.update("users") :set("status", "active") :set("updated_at", sql.builder.expr("NOW()"))| 参数 | 类型 | 描述 |
|---|---|---|
column | string | 列名 |
value | any | 列值 |
返回: UpdateBuilder
update:set_map
Section titled “update:set_map”从表设置多个列。
local query = sql.builder.update("users") :set_map({status = "active", updated_at = sql.builder.expr("NOW()")})| 参数 | 类型 | 描述 |
|---|---|---|
map | table | {列名 = 值} 键值对 |
返回: UpdateBuilder
update:where
Section titled “update:where”添加 WHERE 条件。
local query = sql.builder.update("users") :set("status", "active") :where({id = 123})| 参数 | 类型 | 描述 |
|---|---|---|
condition | string|table|Sqlizer | WHERE 条件 |
args | …any | 绑定参数(可选,使用字符串时) |
返回: UpdateBuilder
update:order_by
Section titled “update:order_by”添加 ORDER BY 子句。
local query = sql.builder.update("users") :set("rank", 1) :order_by("score DESC")| 参数 | 类型 | 描述 |
|---|---|---|
columns | …string | 列名(可选带 ASC/DESC) |
返回: UpdateBuilder
update:limit
Section titled “update:limit”设置 LIMIT。
local query = sql.builder.update("users") :set("status", "active") :limit(10)| 参数 | 类型 | 描述 |
|---|---|---|
n | integer | 限制值 |
返回: UpdateBuilder
update:offset
Section titled “update:offset”设置 OFFSET。
local query = sql.builder.update("users") :set("status", "active") :offset(5)| 参数 | 类型 | 描述 |
|---|---|---|
n | integer | 偏移值 |
返回: UpdateBuilder
update:suffix
Section titled “update:suffix”添加 SQL 后缀。
local query = sql.builder.update("users") :set("status", "active") :suffix("RETURNING id")| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL 后缀 |
args | …any | 绑定参数(可选) |
返回: UpdateBuilder
update:from
Section titled “update:from”添加 FROM 子句。
local query = sql.builder.update("users") :set("status", "active") :from("other_table")| 参数 | 类型 | 描述 |
|---|---|---|
table | string | 表名 |
返回: UpdateBuilder
update:from_select
Section titled “update:from_select”从 SELECT 查询更新。
local select_query = sql.builder.select("*"):from("temp_users")local query = sql.builder.update("users") :set("status", "active") :from_select(select_query, "t")| 参数 | 类型 | 描述 |
|---|---|---|
query | SelectBuilder | SELECT 查询 |
alias | string | 表别名 |
返回: UpdateBuilder
update:placeholder_format
Section titled “update:placeholder_format”设置占位符格式。
local query = sql.builder.update("users") :placeholder_format(sql.builder.dollar)| 参数 | 类型 | 描述 |
|---|---|---|
format | userdata | 占位符格式(sql.builder.*) |
返回: UpdateBuilder
update:to_sql
Section titled “update:to_sql”生成 SQL 字符串和绑定参数。
local sql_str, args = query:to_sql()返回: string, table
update:run_with
Section titled “update:run_with”创建查询执行器。
local executor = query:run_with(db)local result, err = executor:exec()| 参数 | 类型 | 描述 |
|---|---|---|
db | DB|Transaction | 数据库或事务句柄 |
返回: QueryExecutor
DELETE 构建器
Section titled “DELETE 构建器”用于构建 DELETE 查询的流式接口。
delete:from
Section titled “delete:from”设置表名。
local query = sql.builder.delete():from("users")| 参数 | 类型 | 描述 |
|---|---|---|
table | string | 表名 |
返回: DeleteBuilder
delete:where
Section titled “delete:where”添加 WHERE 条件。
local query = sql.builder.delete("users") :where({active = 0})| 参数 | 类型 | 描述 |
|---|---|---|
condition | string|table|Sqlizer | WHERE 条件 |
args | …any | 绑定参数(可选,使用字符串时) |
返回: DeleteBuilder
delete:order_by
Section titled “delete:order_by”添加 ORDER BY 子句。
local query = sql.builder.delete("users") :where({active = 0}) :order_by("created_at ASC")| 参数 | 类型 | 描述 |
|---|---|---|
columns | …string | 列名(可选带 ASC/DESC) |
返回: DeleteBuilder
delete:limit
Section titled “delete:limit”设置 LIMIT。
local query = sql.builder.delete("users") :where({active = 0}) :limit(100)| 参数 | 类型 | 描述 |
|---|---|---|
n | integer | 限制值 |
返回: DeleteBuilder
delete:offset
Section titled “delete:offset”设置 OFFSET。
local query = sql.builder.delete("users") :where({active = 0}) :offset(10)| 参数 | 类型 | 描述 |
|---|---|---|
n | integer | 偏移值 |
返回: DeleteBuilder
delete:suffix
Section titled “delete:suffix”添加 SQL 后缀。
local query = sql.builder.delete("users") :where({active = 0}) :suffix("RETURNING id")| 参数 | 类型 | 描述 |
|---|---|---|
sql | string | 带 ? 占位符的 SQL 后缀 |
args | …any | 绑定参数(可选) |
返回: DeleteBuilder
delete:placeholder_format
Section titled “delete:placeholder_format”设置占位符格式。
local query = sql.builder.delete("users") :placeholder_format(sql.builder.dollar)| 参数 | 类型 | 描述 |
|---|---|---|
format | userdata | 占位符格式(sql.builder.*) |
返回: DeleteBuilder
delete:to_sql
Section titled “delete:to_sql”生成 SQL 字符串和绑定参数。
local sql_str, args = query:to_sql()返回: string, table
delete:run_with
Section titled “delete:run_with”创建查询执行器。
local executor = query:run_with(db)local result, err = executor:exec()| 参数 | 类型 | 描述 |
|---|---|---|
db | DB|Transaction | 数据库或事务句柄 |
返回: QueryExecutor
查询执行器运行构建器生成的查询。
executor:query
Section titled “executor:query”执行查询并返回行(用于 SELECT)。
local rows, err = executor:query()返回: table[], error
executor:exec
Section titled “executor:exec”执行查询并返回结果(用于 INSERT/UPDATE/DELETE)。
local result, err = executor:exec()返回: table, error
返回包含以下字段的表:
last_insert_id- 最后插入的 IDrows_affected- 受影响的行数
executor:to_sql
Section titled “executor:to_sql”返回生成的 SQL 和参数但不执行。
local sql_str, args = executor:to_sql()返回: string, table
数据库访问受安全策略评估约束。
| 操作 | 资源 | 描述 |
|---|---|---|
db.get | 数据库 ID | 获取数据库连接 |
| 条件 | 类型 | 可重试 |
|---|---|---|
| 资源 ID 为空 | errors.INVALID | 否 |
| 权限被拒绝 | errors.PERMISSION_DENIED | 否 |
| 资源未找到 | errors.NOT_FOUND | 否 |
| 资源不是数据库 | errors.INVALID | 否 |
| 参数无效 | errors.INVALID | 否 |
| SQL 语法错误 | errors.INVALID | 否 |
| 语句已关闭 | errors.INVALID | 否 |
| 事务未激活 | errors.INVALID | 否 |
| 保存点名称无效 | errors.INVALID | 否 |
| 查询执行错误 | 各种 | 各种 |
错误处理请参阅 错误处理。
local sql = require("sql")
-- 获取数据库连接local db, err = sql.get("app.db:main")if err then error(err) end
-- 检查数据库类型local dbtype, _ = db:type()print("Database type:", dbtype)
-- 直接查询local users, err = db:query("SELECT id, name FROM users WHERE active = ?", {1})if err then error(err) end
for _, user in ipairs(users) do print(user.id, user.name)end
-- 构建器模式local query = sql.builder.select("u.id", "u.name", "COUNT(o.id) as order_count") :from("users u") :left_join("orders o ON o.user_id = u.id") :where(sql.builder.and_({ sql.builder.eq({["u.active"] = 1}), sql.builder.gte({["u.score"] = 80}) })) :group_by("u.id", "u.name") :having(sql.builder.gt({["COUNT(o.id)"] = 0})) :order_by("order_count DESC") :limit(10)
local executor = query:run_with(db)local results, err = executor:query()if err then error(err) end
-- 带保存点的事务local tx, err = db:begin({isolation = sql.isolation.SERIALIZABLE})if err then error(err) end
local _, err = tx:execute("INSERT INTO users (name) VALUES (?)", {"alice"})if err then tx:rollback() error(err)end
tx:savepoint("sp1")
local _, err = tx:execute("UPDATE users SET status = ? WHERE id = ?", {"active", 1})if err then tx:rollback_to("sp1")else tx:release("sp1")end
local ok, err = tx:commit()if err then error(err) end
-- 预处理语句local stmt, err = db:prepare("INSERT INTO logs (message, level) VALUES (?, ?)")if err then error(err) end
for i = 1, 100 do local _, err = stmt:execute({"log message " .. i, "info"}) if err then stmt:close() error(err) endend
stmt:close()
-- NULL 和类型化值local insert = sql.builder.insert("products") :columns("name", "price", "description") :values("Widget", sql.as.float(19.99), sql.NULL)
local executor = insert:run_with(db)local result, err = executor:exec()if err then error(err) end
print("Inserted ID:", result.last_insert_id)
db:release()