Объект соединения

conn:query

Выполняет запрос и отдаёт строки в коллбэк.

conn:query(sql[, ...], fn)
conn:query(sql, params, fn)

Аргументы

#	имя	тип
1	`sql`	string	SQL с `?` на месте значений
2	`...`	any	значения для `?`, ровно по числу знаков
3	`params`	table	массив значений для `?`
4	`fn`	function	получает объект ответа

Есть два способа передать значения для ?.Старый вариант передаёт их отдельными аргументами:

conn:query(
    "SELECT * FROM users WHERE server_id = ? AND steamid = ?",
    server_id,
    steamid,
    function(res)
        ...
    end
)

Для динамического количества параметров можно передать их одной таблицей:

conn:query(
    "SELECT * FROM users WHERE server_id = ? AND steamid = ?",
    { server_id, steamid },
    function(res)
        ...
    end
)

Оба варианта поддерживаются.

Возвращает

тип
`number`	id запроса

Пример

Отдельные параметры

site:query(
    "SELECT id, shilings FROM users WHERE steam_id = ?",
    p:steamid(),
    function(res)
        if not res.ok then
            return print(res.error)
        end

        for _, row in ipairs(res.rows) do
            print(row.id, row.shilings)
        end
    end
)

Таблица параметров

local params = {
    server_id,
    steamid,
}

site:query(
    "SELECT id FROM users WHERE server_id = ? AND steam_id = ?",
    params,
    function(res)
        if not res.ok then
            return print(res.error)
        end

        local row = res.rows[1]
        if row then
            print(row.id)
        end
    end
)

Форма с таблицей особенно удобна для запросов, которые собираются динамически:

local sets = {}
local params = {}

table.insert(sets, "name = ?")
table.insert(params, player:name())

table.insert(sets, "updated_at = ?")
table.insert(params, os.time())

table.insert(params, player:id())

conn:exec(
    "UPDATE users SET " .. table.concat(sets, ", ") .. " WHERE id = ?",
    params,
    function(res)
        if not res.ok then
            print(res.error)
        end
    end
)

Соединения переживают lua_reload и выгрузку плагина: сокет закрывается только при остановке сервера, а не при перезагрузке — обрывать чужой запрос на середине нельзя, см. ниже.

conn:exec

conn:exec полностью эквивалентен conn:query. Отличается только названием: query обычно используется для SELECT, а exec — для INSERT, UPDATE и DELETE.

conn:exec(sql[, ...], fn)
conn:exec(sql, params, fn)

Аргументы

#	имя	тип
1	`sql`	string	SQL с `?` на месте значений
2	`...`	any	значения для `?`
3	`params`	table	массив значений для `?`
4	`fn`	function	получает объект ответа

Возвращает

тип
`number`	id запроса

Пример

site:exec("UPDATE users SET shilings = shilings + ? WHERE id = ?", delta, id,
    function(res)
        if res.ok then print(res.affected_rows) end
    end)

conn:find

SELECT по одной таблице. Собирает запрос сам; значения в where идут через ?.

conn:find(table, opts, fn)

Аргументы

#	имя	тип
1	`table`	string	имя таблицы (`[A-Za-z0-9_]+`)
2	`opts`	table	см. ниже
3	`fn`	function	тот же объект ответа, что у `query`

opts

поле	тип
`where`	table \| nil	`{ col = value, ... }` — только равенства, соединяются через `AND`
`select`	table \| nil	список имён колонок; нет или пусто — `*`
`order`	table \| nil	строки `"col"` или `"col ASC"` / `"col DESC"`
`limit`	number \| nil	`LIMIT n`
`offset`	number \| nil	`OFFSET n`

Возвращает

тип
`number`	id запроса

Пример

site:find("users", {
    where  = { steam_id = p:steamid() },
    select = { "id", "shilings" },
    limit  = 1,
}, function(res)
    if not res.ok then return print(res.error) end
    local row = res.rows[1]
    if row then print(row.shilings) end
end)

conn:create

INSERT одной строки. Ключи таблицы — имена колонок, значения — через ?.

conn:create(table, data, fn)

Аргументы

#	имя	тип
1	`table`	string	имя таблицы
2	`data`	table	`{ col = value, ... }`, не пустая
3	`fn`	function	объект ответа (`insert_id`, `affected_rows`)

Возвращает

тип
`number`	id запроса

Пример

site:create("users", {
    steam_id = steamid,
    name     = name,
    shilings = 0,
}, function(res)
    if res.ok then print("id", res.insert_id) end
end)

conn:update

UPDATE: обязательны и set, и where (оба непустые).

conn:update(table, opts, fn)

Аргументы

#	имя	тип
1	`table`	string	имя таблицы
2	`opts`	table	`set` + `where`
3	`fn`	function	объект ответа

opts

поле	тип
`set`	table	`{ col = value, ... }`
`where`	table	`{ col = value, ... }` — только `AND` равенств

Возвращает

тип
`number`	id запроса

Пример

site:update("users", {
    set   = { shilings = 100 },
    where = { id = 42 },
}, function(res)
    if res.ok then print(res.affected_rows) end
end)

conn:delete

DELETE. where обязателен и непустой (защита от «удалить всё»).

conn:delete(table, opts, fn)

Аргументы

#	имя	тип
1	`table`	string	имя таблицы
2	`opts`	table	`where`
3	`fn`	function	объект ответа

opts

поле	тип
`where`	table	`{ col = value, ... }`

Возвращает

тип
`number`	id запроса

Пример

site:delete("users", { where = { id = 42 } }, function(res)
    if res.ok then print(res.affected_rows) end
end)

conn:migrate

Прогоняет миграции последовательно на этом соединении (под одним use_lock). Уже применённые id пропускаются. Книга учёта —

_cslua_migrations (id VARCHAR(128) PRIMARY KEY, applied_at TIMESTAMP)

создаётся сама при первом вызове.

conn:migrate(opts, fn)

Аргументы

#	имя	тип
1	`opts`	table	`migrations` и/или `files`
2	`fn`	function	объект ответа + `res.applied`

opts

migrations — массив шагов:

поле шага	тип
`id`	string	уникальный id (`[A-Za-z0-9_.-]+`, до 128)
`sql`	string \| nil	текст SQL
`file`	string \| nil	имя файла в `plugin.data_dir()` (те же правила, что у `file.read`)

Нужен sql или file. files — массив имён файлов; id миграции = имя файла целиком (001_init.sql). Можно передать оба списка: сначала migrations, потом files.

Возвращает

тип
`number`	id запроса

Ответ

Как у query, плюс:

поле	тип
`res.applied`	table	id, которые реально выполнились в этом вызове (пустой, если всё уже было)

Пример

site:migrate({
    migrations = {
        {
            id = "001_users",
            sql = [[
                CREATE TABLE IF NOT EXISTS users (
                    id INT AUTO_INCREMENT PRIMARY KEY,
                    steam_id VARCHAR(32) NOT NULL UNIQUE,
                    shilings INT NOT NULL DEFAULT 0
                )
            ]],
        },
        { id = "002_name", file = "002_name.sql" },
    },
}, function(res)
    if not res.ok then return print(res.error) end
    for _, id in ipairs(res.applied or {}) do
        print("applied", id)
    end
end)

-- только файлы из data_dir плагина
site:migrate({
    files = { "001_init.sql", "002_vip.sql" },
}, function(res)
    if not res.ok then return print(res.error) end
end)

Файлы читаются только из каталога плагина (песочница file.*): без ../, без подпапок. SQL из файла выполняется как есть — это код плагина.

Повторный вызов с тем же id ничего не делает. Новый шаг — новый id. Весь batch одной миграции идёт строго по очереди; параллелить шаги нельзя.

conn:close

Закрывает соединение.

conn:close()

Возвращает

Ничего. Помечает соединение закрытым сразу; сам сокет освобождается позже, когда рабочий поток до него дойдёт (или при остановке сервера, если запросов на нём больше нет). Запросы, уже отправленные до :close(), доигрывают и получают res.error.

Документация

Справочник API

mysql — Объект соединения

Объект соединения

conn:query

Аргументы

Возвращает

Пример

conn:exec

Аргументы

Возвращает

Пример

conn:find

Аргументы

opts

Возвращает

Пример

conn:create

Аргументы

Возвращает

Пример

conn:update

Аргументы

opts

Возвращает

Пример

conn:delete

Аргументы

opts

Возвращает

Пример

conn:migrate

Аргументы

opts

Возвращает

Ответ

Пример

conn:close

Возвращает

​Объект соединения

​conn:query

​Аргументы

​Возвращает

​Пример

​conn:exec

​Аргументы

​Возвращает

​Пример

​conn:find

​Аргументы

​opts

​Возвращает

​Пример

​conn:create

​Аргументы

​Возвращает

​Пример

​conn:update

​Аргументы

​opts

​Возвращает

​Пример

​conn:delete

​Аргументы

​opts

​Возвращает

​Пример

​conn:migrate

​Аргументы

​opts

​Возвращает

​Ответ

​Пример

​conn:close

​Возвращает

Объект соединения

conn:query

Аргументы

Возвращает

Пример

conn:exec

Аргументы

Возвращает

Пример

conn:find

Аргументы

opts

Возвращает

Пример

conn:create

Аргументы

Возвращает

Пример

conn:update

Аргументы

opts

Возвращает

Пример

conn:delete

Аргументы

opts

Возвращает

Пример

conn:migrate

Аргументы

opts

Возвращает

Ответ

Пример

conn:close

Возвращает