ai-mysql для разработчиков

ai-mysql отвечает на API oxmysql в точности (сигнатуры, правила колбэков, форматы результатов), поэтому собственная документация oxmysql применима. На этой странице перечислено, на что он отвечает, и важные детали.

Использование из LuaCopy Anchor Link

Загрузите обёртку oxmysql; путь указывает на ai-mysql:

server_script '@oxmysql/lib/MySQL.lua'

-- Ждёт результата: вызывайте внутри потока или обработчика события.
local row = MySQL.single.await('SELECT money FROM my_accounts WHERE owner = ?', { identifier })

-- Форма с колбэком: не ждёт.
MySQL.update('UPDATE my_accounts SET money = money - ? WHERE owner = ? AND money >= ?', { 100, identifier, 100 }, function(affected)
    if affected == 1 then print('paid') end
end)

ЭкспортыCopy Anchor Link

Каждый экспорт серверный и отвечает под exports['ai-mysql'] и exports.oxmysql. Каждый принимает (query, params?, callback?):

• query: текст SQL с плейсхолдерами ? или именованными плейсхолдерами @name / :name.
• params: массив для ?, объект для именованных плейсхолдеров. Можно не указывать; тогда колбэк может быть вторым аргументом.
• callback: вызывается с результатом. Без него вызов всё равно выполняется.

У каждого экспорта также есть форма с промисом <name>_async и <name>Sync (query_async(query, params) возвращает Promise, который отклоняется при ошибке).

transactionCopy Anchor Link

Выполняет несколько запросов на одном соединении; либо все выполняются успешно, либо ни один.

Сторона: сервер · Ожидание: нет (отвечает через колбэк; transaction_async возвращает Promise)

transaction(queries: Array<string | [string, unknown[] | object] | { query: string; values?: unknown[] | object; parameters?: unknown[] | object }>, params?: unknown[] | object, cb?: (committed: boolean) => void): void

local ok = MySQL.transaction.await({
    { query = 'UPDATE my_accounts SET money = money - ? WHERE owner = ?', values = { 100, from } },
    { query = 'UPDATE my_accounts SET money = money + ? WHERE owner = ?', values = { 100, to } },
})

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

Напрямую ничего; колбэк получает true или false. Откат печатает ошибку в консоль и вызывает oxmysql:transaction-error.

startTransactionCopy Anchor Link

Открывает транзакцию и передаёт вашей функции привязанный к ней помощник query. Верните false из своей функции, чтобы откатить. Время ожидания 30 секунд.

Сторона: сервер · Ожидание: да (Promise)

startTransaction(work: (query: (sql: string, params?: unknown[] | object) => Promise<unknown>) => Promise<boolean | void>): Promise<boolean>

ВозвращаетCopy Anchor Link

Promise<boolean>: true при фиксации. false, если ваша функция вернула false, выбросила ошибку или истекли 30 секунд.

ПримерCopy Anchor Link

// Ресурс на чистом JavaScript или TypeScript без @aicore-fivem/mysql.
const db = exports.oxmysql;

async function pay(from: string, to: string, amount: number): Promise<boolean> {
  return db.startTransaction(async (query: (sql: string, params?: unknown[]) => Promise<any>) => {
    const res = await query("UPDATE my_accounts SET money = money - ? WHERE owner = ? AND money >= ?", [amount, from, amount]);
    if (res.affectedRows !== 1) return false; // не хватает денег: откат
    await query("UPDATE my_accounts SET money = money + ? WHERE owner = ?", [amount, to]);
  });
}

Старые имена экспортовCopy Anchor Link

Правила колбэков и ошибокCopy Anchor Link

Они повторяют oxmysql:

• Успех: колбэк получает результат.
• Ошибка в форме с промисом (или .await в Lua): промис отклоняется с текстом ошибки.
• Ошибка с обычным колбэком: ошибка печатается в консоль, а колбэк не вызывается.

СобытияCopy Anchor Link

oxmysql:errorCopy Anchor Link

Сторона: сервер (локальное) · срабатывает, когда запрос завершается ошибкой.

oxmysql:transaction-errorCopy Anchor Link

Сторона: сервер (локальное) · срабатывает, когда transaction откатывается. Данные { message: string, resource: string }.

on("oxmysql:error", (e: { query?: string; message: string; resource: string }) => {
  console.log(`[db] ${e.resource}: ${e.message} (${e.query ?? "?"})`);
});