База данных SQL

Выполнение SQL-запросов к базам данных PostgreSQL, MySQL, SQLite, MSSQL и Oracle. Поддержка параметризованных запросов, транзакций, подготовленных выражений и fluent-конструктора запросов.

Настройку базы данных см. в Database.

Загрузка

local sql = require("sql")

Получение соединения

Получить соединение с базой данных из реестра ресурсов:

local db, err = sql.get("app.db:main")
if err then
    return nil, err
end

local rows = db:query("SELECT * FROM users WHERE active = ?", {1})

db:release()

Возвращает: DB, error

Константы

Типы баз данных

sql.type.POSTGRES    -- "postgres"
sql.type.MYSQL       -- "mysql"
sql.type.SQLITE      -- "sqlite"
sql.type.MSSQL       -- "mssql"
sql.type.ORACLE      -- "oracle"
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

local insert = sql.builder.insert("users")
    :columns("name", "email")
    :values("alice", sql.NULL)

Приведение типов

as.int

local value = sql.as.int(42)

Возвращает: userdata

as.float

Приведение значения к SQL-типу float.

local value = sql.as.float(19.99)

Возвращает: userdata

as.text

Приведение значения к SQL-типу text.

local value = sql.as.text("hello")

Возвращает: userdata

as.binary

Приведение значения к SQL-типу binary.

local value = sql.as.binary("binary data")

Возвращает: userdata

as.null

Возвращает маркер SQL NULL.

local value = sql.as.null()

Возвращает: userdata

Конструктор запросов

Создание запросов

local query = sql.builder.select("id", "name")
    :from("users")
    :where({active = 1})

Возвращает: SelectBuilder

builder.insert

Создаёт конструктор INSERT-запроса.

local query = sql.builder.insert("users")
    :columns("name", "email")
    :values("alice", "alice@example.com")

Возвращает: InsertBuilder

builder.update

Создаёт конструктор UPDATE-запроса.

local query = sql.builder.update("users")
    :set("status", "active")
    :where({id = 123})

Возвращает: UpdateBuilder

builder.delete

Создаёт конструктор DELETE-запроса.

local query = sql.builder.delete("users")
    :where({active = 0})
    :limit(100)

Возвращает: DeleteBuilder

builder.expr

Создаёт сырое SQL-выражение для использования в where/having.

local expr = sql.builder.expr("score BETWEEN ? AND ?", 80, 90)

Возвращает: Sqlizer

builder.eq

Создаёт условие равенства из таблицы.

local cond = sql.builder.eq({active = 1, status = "open"})

Возвращает: Sqlizer

builder.not_eq

Создаёт условие неравенства из таблицы.

local cond = sql.builder.not_eq({status = "closed"})

Возвращает: Sqlizer

builder.lt

Создаёт условие «меньше» из таблицы.

local cond = sql.builder.lt({age = 18})

Возвращает: Sqlizer

builder.lte

Создаёт условие «меньше или равно» из таблицы.

local cond = sql.builder.lte({price = 100})

Возвращает: Sqlizer

builder.gt

Создаёт условие «больше» из таблицы.

local cond = sql.builder.gt({score = 80})

Возвращает: Sqlizer

builder.gte

Создаёт условие «больше или равно» из таблицы.

local cond = sql.builder.gte({age = 21})

Возвращает: Sqlizer

builder.like

Создаёт условие LIKE из таблицы.

local cond = sql.builder.like({name = "john%"})

Возвращает: Sqlizer

builder.not_like

Создаёт условие NOT LIKE из таблицы.

local cond = sql.builder.not_like({email = "%@spam.com"})

Возвращает: Sqlizer

builder.and_

Объединяет несколько условий через AND.

local cond = sql.builder.and_({
    sql.builder.eq({active = 1}),
    sql.builder.gt({score = 80})
})

Возвращает: Sqlizer

builder.or_

Объединяет несколько условий через OR.

local cond = sql.builder.or_({
    sql.builder.eq({status = "pending"}),
    sql.builder.eq({status = "active"})
})

Возвращает: Sqlizer

builder.question

Формат плейсхолдеров ? (по умолчанию).

local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.question)

builder.dollar

Формат плейсхолдеров $1, $2, ...

local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.dollar)

builder.at

Формат плейсхолдеров @p1, @p2, ...

local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.at)

builder.colon

Формат плейсхолдеров :1, :2, ...

local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.colon)

Методы соединения

Дескриптор соединения, возвращаемый sql.get().

db:type

Возвращает константу типа базы данных.

local dbtype, err = db:type()

Возвращает: string, error

db:query

Выполняет SELECT-запрос и возвращает строки.

local rows, err = db:query("SELECT id, name FROM users WHERE active = ?", {1})

Возвращает: table[], error

db:execute

Выполняет INSERT/UPDATE/DELETE-запрос.

local result, err = db:execute("INSERT INTO users (name) VALUES (?)", {"alice"})

Возвращает: table, error

Возвращаемая таблица содержит поля:

• last_insert_id — ID последней вставленной записи
• rows_affected — количество затронутых строк

db:prepare

Создаёт подготовленное выражение для многократного выполнения.

local stmt, err = db:prepare("SELECT * FROM users WHERE id = ?")

Возвращает: Statement, error

db:begin

Начинает транзакцию базы данных.

local tx, err = db:begin({
    isolation = sql.isolation.SERIALIZABLE,
    read_only = false
})

Поля таблицы опций:

• isolation — уровень изоляции из sql.isolation.* (по умолчанию: DEFAULT)
• read_only — флаг транзакции только для чтения (по умолчанию: false)

Возвращает: Transaction, error

db:release

Возвращает ресурс базы данных в пул.

local ok, err = db:release()

Возвращает: boolean, error

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
• max_idle_time_closed — соединений закрыто по таймауту простоя
• max_lifetime_closed — соединений закрыто по max lifetime

Подготовленные выражения

Подготовленное выражение, возвращаемое db:prepare().

stmt:query

Выполняет подготовленное выражение как SELECT.

local rows, err = stmt:query({123})

Возвращает: table[], error

stmt:execute

Выполняет подготовленное выражение как INSERT/UPDATE/DELETE.

local result, err = stmt:execute({"alice"})

Возвращает: table, error

Возвращаемая таблица содержит поля:

• last_insert_id — ID последней вставленной записи
• rows_affected — количество затронутых строк

stmt:close

Закрывает подготовленное выражение.

local ok, err = stmt:close()

Возвращает: boolean, error

Транзакции

Транзакция базы данных, возвращаемая db:begin().

tx:db_type

Возвращает константу типа базы данных.

local dbtype, err = tx:db_type()

Возвращает: string, error

tx:query

Выполняет SELECT-запрос внутри транзакции.

local rows, err = tx:query("SELECT id, name FROM users WHERE active = ?", {1})

Возвращает: table[], error

tx:execute

Выполняет INSERT/UPDATE/DELETE внутри транзакции.

local result, err = tx:execute("INSERT INTO users (name) VALUES (?)", {"alice"})

Возвращает: table, error

Возвращаемая таблица содержит поля:

• last_insert_id — ID последней вставленной записи
• rows_affected — количество затронутых строк

tx:prepare

Создаёт подготовленное выражение внутри транзакции.

local stmt, err = tx:prepare("SELECT * FROM users WHERE id = ?")

Возвращает: Statement, error

tx:commit

Фиксирует транзакцию.

local ok, err = tx:commit()

Возвращает: boolean, error

tx:rollback

Откатывает транзакцию.

local ok, err = tx:rollback()

Возвращает: boolean, error

tx:savepoint

Создаёт именованную точку сохранения внутри транзакции.

local ok, err = tx:savepoint("sp1")

Возвращает: boolean, error

tx:rollback_to

Откатывает к именованной точке сохранения.

local ok, err = tx:rollback_to("sp1")

Возвращает: boolean, error

tx:release

Освобождает точку сохранения.

local ok, err = tx:release("sp1")

Возвращает: boolean, error

SELECT Builder

Fluent-интерфейс для построения SELECT-запросов.

select:from

Устанавливает FROM-часть.

local query = sql.builder.select("id", "name"):from("users")

Возвращает: SelectBuilder

select:join

Добавляет JOIN-часть.

local query = sql.builder.select("*")
    :from("users")
    :join("orders ON orders.user_id = users.id")

Возвращает: SelectBuilder

select:left_join

Добавляет LEFT JOIN-часть.

local query = sql.builder.select("*")
    :from("users")
    :left_join("orders ON orders.user_id = users.id")

Возвращает: SelectBuilder

select:right_join

Добавляет RIGHT JOIN-часть.

local query = sql.builder.select("*")
    :from("users")
    :right_join("orders ON orders.user_id = users.id")

Возвращает: SelectBuilder

select:inner_join

Добавляет INNER JOIN-часть.

local query = sql.builder.select("*")
    :from("users")
    :inner_join("orders ON orders.user_id = users.id")

Возвращает: SelectBuilder

select:where

Добавляет WHERE-условие.

local query = sql.builder.select("*")
    :from("users")
    :where({active = 1})

Поддерживает три формата:

• Строка: where("status = ?", "active")
• Таблица: where({status = "active"})
• Sqlizer: where(sql.builder.gt({score = 80}))

Возвращает: SelectBuilder

select:order_by

Добавляет ORDER BY-часть.

local query = sql.builder.select("*")
    :from("users")
    :order_by("name ASC", "created_at DESC")

Возвращает: SelectBuilder

select:group_by

Добавляет GROUP BY-часть.

local query = sql.builder.select("status", "COUNT(*)")
    :from("users")
    :group_by("status")

Возвращает: SelectBuilder

select:having

Добавляет HAVING-условие.

local query = sql.builder.select("status", "COUNT(*) as cnt")
    :from("users")
    :group_by("status")
    :having(sql.builder.gt({cnt = 10}))

Возвращает: SelectBuilder

select:limit

Устанавливает LIMIT.

local query = sql.builder.select("*")
    :from("users")
    :limit(10)

Возвращает: SelectBuilder

select:offset

Устанавливает OFFSET.

local query = sql.builder.select("*")
    :from("users")
    :offset(20)

Возвращает: SelectBuilder

select:columns

Добавляет колонки в SELECT.

local query = sql.builder.select():columns("id", "name", "email")

Возвращает: SelectBuilder

select:distinct

Добавляет модификатор DISTINCT.

local query = sql.builder.select("status")
    :from("users")
    :distinct()

Возвращает: SelectBuilder

select:suffix

Добавляет SQL-суффикс.

local query = sql.builder.select("*")
    :from("users")
    :suffix("FOR UPDATE")

Возвращает: SelectBuilder

select:placeholder_format

Устанавливает формат плейсхолдеров.

local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.dollar)

Возвращает: SelectBuilder

select:to_sql

Генерирует SQL-строку и аргументы привязки.

local sql_str, args = query:to_sql()

Возвращает: string, table

select:run_with

Создаёт исполнитель для запроса.

local executor = query:run_with(db)
local rows, err = executor:query()

Возвращает: QueryExecutor

INSERT Builder

Fluent-интерфейс для построения INSERT-запросов.

insert:into

Устанавливает имя таблицы.

local query = sql.builder.insert():into("users")

Возвращает: InsertBuilder

insert:columns

Устанавливает имена колонок.

local query = sql.builder.insert("users"):columns("name", "email")

Возвращает: InsertBuilder

insert:values

Добавляет значения строки.

local query = sql.builder.insert("users")
    :columns("name", "email")
    :values("alice", "alice@example.com")

Возвращает: InsertBuilder

insert:set_map

Устанавливает колонки и значения из таблицы.

local query = sql.builder.insert("users")
    :set_map({name = "alice", email = "alice@example.com"})

Возвращает: InsertBuilder

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)

Возвращает: InsertBuilder

insert:prefix

Добавляет SQL-префикс.

local query = sql.builder.insert("users")
    :prefix("INSERT IGNORE INTO")

Возвращает: InsertBuilder

insert:suffix

Добавляет SQL-суффикс.

local query = sql.builder.insert("users")
    :columns("name")
    :values("alice")
    :suffix("RETURNING id")

Возвращает: InsertBuilder

insert:options

Добавляет опции INSERT.

local query = sql.builder.insert("users")
    :options("DELAYED", "IGNORE")

Возвращает: InsertBuilder

insert:placeholder_format

Устанавливает формат плейсхолдеров.

local query = sql.builder.insert("users")
    :placeholder_format(sql.builder.dollar)

Возвращает: InsertBuilder

insert:to_sql

Генерирует SQL-строку и аргументы привязки.

local sql_str, args = query:to_sql()

Возвращает: string, table

insert:run_with

Создаёт исполнитель для запроса.

local executor = query:run_with(db)
local result, err = executor:exec()

Возвращает: QueryExecutor

UPDATE Builder

Fluent-интерфейс для построения UPDATE-запросов.

update:table

Устанавливает имя таблицы.

local query = sql.builder.update():table("users")

Возвращает: UpdateBuilder

update:set

Устанавливает значение колонки.

local query = sql.builder.update("users")
    :set("status", "active")
    :set("updated_at", sql.builder.expr("NOW()"))

Возвращает: UpdateBuilder

update:set_map

Устанавливает несколько колонок из таблицы.

local query = sql.builder.update("users")
    :set_map({status = "active", updated_at = sql.builder.expr("NOW()")})

Возвращает: UpdateBuilder

update:where

Добавляет WHERE-условие.

local query = sql.builder.update("users")
    :set("status", "active")
    :where({id = 123})

Возвращает: UpdateBuilder

update:order_by

Добавляет ORDER BY-часть.

local query = sql.builder.update("users")
    :set("rank", 1)
    :order_by("score DESC")

Возвращает: UpdateBuilder

update:limit

Устанавливает LIMIT.

local query = sql.builder.update("users")
    :set("status", "active")
    :limit(10)

Возвращает: UpdateBuilder

update:offset

Устанавливает OFFSET.

local query = sql.builder.update("users")
    :set("status", "active")
    :offset(5)

Возвращает: UpdateBuilder

update:suffix

Добавляет SQL-суффикс.

local query = sql.builder.update("users")
    :set("status", "active")
    :suffix("RETURNING id")

Возвращает: UpdateBuilder

update:from

Добавляет FROM-часть.

local query = sql.builder.update("users")
    :set("status", "active")
    :from("other_table")

Возвращает: UpdateBuilder

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")

Возвращает: UpdateBuilder

update:placeholder_format

Устанавливает формат плейсхолдеров.

local query = sql.builder.update("users")
    :placeholder_format(sql.builder.dollar)

Возвращает: UpdateBuilder

update:to_sql

Генерирует SQL-строку и аргументы привязки.

local sql_str, args = query:to_sql()

Возвращает: string, table

update:run_with

Создаёт исполнитель для запроса.

local executor = query:run_with(db)
local result, err = executor:exec()

Возвращает: QueryExecutor

DELETE Builder

Fluent-интерфейс для построения DELETE-запросов.

delete:from

Устанавливает имя таблицы.

local query = sql.builder.delete():from("users")

Возвращает: DeleteBuilder

delete:where

Добавляет WHERE-условие.

local query = sql.builder.delete("users")
    :where({active = 0})

Возвращает: DeleteBuilder

delete:order_by

Добавляет ORDER BY-часть.

local query = sql.builder.delete("users")
    :where({active = 0})
    :order_by("created_at ASC")

Возвращает: DeleteBuilder

delete:limit

Устанавливает LIMIT.

local query = sql.builder.delete("users")
    :where({active = 0})
    :limit(100)

Возвращает: DeleteBuilder

delete:offset

Устанавливает OFFSET.

local query = sql.builder.delete("users")
    :where({active = 0})
    :offset(10)

Возвращает: DeleteBuilder

delete:suffix

Добавляет SQL-суффикс.

local query = sql.builder.delete("users")
    :where({active = 0})
    :suffix("RETURNING id")

Возвращает: DeleteBuilder

delete:placeholder_format

Устанавливает формат плейсхолдеров.

local query = sql.builder.delete("users")
    :placeholder_format(sql.builder.dollar)

Возвращает: DeleteBuilder

delete:to_sql

Генерирует SQL-строку и аргументы привязки.

local sql_str, args = query:to_sql()

Возвращает: string, table

delete:run_with

Создаёт исполнитель для запроса.

local executor = query:run_with(db)
local result, err = executor:exec()

Возвращает: QueryExecutor

Выполнение запросов

Исполнитель запросов для запросов, построенных конструктором.

executor:query

Выполняет запрос и возвращает строки (для SELECT).

local rows, err = executor:query()

Возвращает: table[], error

executor:exec

Выполняет запрос и возвращает результат (для INSERT/UPDATE/DELETE).

local result, err = executor:exec()

Возвращает: table, error

Возвращаемая таблица содержит поля:

• last_insert_id — ID последней вставленной записи
• rows_affected — количество затронутых строк

executor:to_sql

Возвращает сгенерированный SQL и аргументы без выполнения.

local sql_str, args = executor:to_sql()

Возвращает: string, table

Разрешения

Доступ к базе данных подчиняется вычислению политики безопасности.

Ошибки

См. Обработка ошибок для работы с ошибками.

Пример

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)
    end
end

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()