ai-mysql pour les développeurs

ai-mysql répond exactement à l’API d’oxmysql (signatures, règles des callbacks, formes des résultats), donc la documentation propre à oxmysql s’applique. Cette page liste ce à quoi il répond et les détails qui comptent.

L’utiliser depuis LuaCopy Anchor Link

Chargez l’enveloppe d’oxmysql ; le chemin pointe vers ai-mysql :

server_script '@oxmysql/lib/MySQL.lua'

-- Attend le résultat : à appeler dans un thread ou un gestionnaire d’event.
local row = MySQL.single.await('SELECT money FROM my_accounts WHERE owner = ?', { identifier })

-- Forme callback : n’attend pas.
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)

ExportsCopy Anchor Link

Chaque export est côté serveur et répond sous exports['ai-mysql'] et exports.oxmysql. Chacun prend (query, params?, callback?) :

• query : le texte SQL, avec des marqueurs ? ou des marqueurs nommés @name / :name.
• params : un tableau pour ?, un objet pour les marqueurs nommés. Peut être omis ; le callback peut alors être le deuxième argument.
• callback : appelé avec le résultat. Sans lui, l’appel s’exécute quand même.

Chaque export a aussi une forme promise <name>_async et <name>Sync (query_async(query, params) renvoie une Promise qui est rejetée en cas d’erreur).

transactionCopy Anchor Link

Exécute plusieurs instructions sur une seule connexion ; toutes réussissent ou aucune.

Côté : serveur · Attend : non (répond via le callback ; transaction_async renvoie une 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 } },
})

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Rien directement ; le callback reçoit true ou false. Un rollback affiche l’erreur dans la console et déclenche oxmysql:transaction-error.

startTransactionCopy Anchor Link

Ouvre une transaction et donne à votre fonction un utilitaire query lié à elle. Renvoyez false depuis votre fonction pour faire un rollback. Elle expire au bout de 30 secondes.

Côté : serveur · Attend : oui (Promise)

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

RetourCopy Anchor Link

Promise<boolean> : true après un commit. false quand votre fonction a renvoyé false, a levé une erreur, ou que les 30 secondes se sont écoulées.

ExempleCopy Anchor Link

// Une ressource JavaScript ou TypeScript simple sans @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; // pas assez d’argent : rollback
    await query("UPDATE my_accounts SET money = money + ? WHERE owner = ?", [amount, to]);
  });
}

Anciens noms d’exportsCopy Anchor Link

Règles des callbacks et des erreursCopy Anchor Link

Elles suivent oxmysql :

• Succès : le callback reçoit le résultat.
• Échec avec une forme promise (ou .await en Lua) : la promise est rejetée avec le texte de l’erreur.
• Échec avec un simple callback : l’erreur est affichée dans la console et le callback n’est pas appelé.

EventsCopy Anchor Link

oxmysql:errorCopy Anchor Link

Côté : serveur (local) · se déclenche quand une requête échoue.

oxmysql:transaction-errorCopy Anchor Link

Côté : serveur (local) · se déclenche quand une transaction fait un rollback. Contenu { message: string, resource: string }.

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