ai-mysql para desenvolvedores
Os exports do oxmysql que o ai-mysql responde, o que cada um retorna, as formas com promise, o wrapper MySQL.lua e os eventos de erro.
Escrevendo um recurso no estilo ai-* em TypeScript? Não use o ai-mysql. Use o pacote de banco de dados do AI Core @aicore-fivem/mysql no seu próprio recurso (sem salto de export por consulta, tabelas tipadas). Veja Banco de dados. O ai-mysql é para scripts Lua e JavaScript escritos para o oxmysql.
O ai-mysql responde à API do oxmysql exatamente (assinaturas, regras de callback, formatos de resultado), então a própria documentação do oxmysql vale. Esta página lista o que ele responde e os detalhes que importam.
Usando a partir do Lua
Carregue o wrapper do oxmysql; o caminho aponta para o ai-mysql:
server_script '@oxmysql/lib/MySQL.lua'-- Espera o resultado: chame dentro de uma thread ou de um handler de evento.
local row = MySQL.single.await('SELECT money FROM my_accounts WHERE owner = ?', { identifier })
-- Forma com callback: não espera.
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)Exports
Todo export é do lado do servidor e responde em exports['ai-mysql'] e exports.oxmysql. Cada um recebe (query, params?, callback?):
query: o texto SQL, com placeholders?ou placeholders nomeados@name/:name.params: um array para?, um objeto para placeholders nomeados. Pode ser omitido; o callback pode então ser o segundo argumento.callback: chamado com o resultado. Sem ele, a chamada ainda roda.
Cada export também tem uma forma com promise <name>_async e <name>Sync (query_async(query, params) retorna uma Promise que é rejeitada em caso de erro).
| Export | Responde | Use para |
|---|---|---|
query | as linhas (array de objetos) para um SELECT, ou o cabeçalho de resultado para outros comandos | qualquer coisa; execute e fetch são aliases antigos |
single | a primeira linha, ou null | uma linha por chave |
scalar | a primeira coluna da primeira linha, ou null | uma contagem, um valor |
insert | o id da nova linha (insertId), ou null | INSERT |
update | o número de linhas afetadas, ou null | UPDATE, DELETE |
prepare | prepared statement (protocolo binário); INSERT responde o id, UPDATE / DELETE as linhas afetadas, SELECT a primeira linha (ou seu único valor). Várias listas de valores o rodam uma vez cada. | a mesma consulta muitas vezes |
rawExecute | prepared statement com os resultados completos, sem formatação | quando você precisa do resultado bruto |
transaction | true quando confirmada, false depois de um rollback (sempre pelo callback) | vários comandos que precisam dar certo todos |
startTransaction | uma Promise de true quando confirmada, false depois de um rollback | uma transação com lógica entre as consultas |
store | devolve o texto da consulta ao callback | código antigo que guardava consultas |
isReady | boolean: o pool está aberto | verificações na inicialização |
awaitConnection | uma Promise de true assim que conectado | esperar na inicialização |
transaction
Roda vários comandos em uma única conexão; todos dão certo ou nenhum.
Lado: Servidor · Espera: não (responde pelo callback; transaction_async retorna uma Promise)
transaction(queries: Array<string | [string, unknown[] | object] | { query: string; values?: unknown[] | object; parameters?: unknown[] | object }>, params?: unknown[] | object, cb?: (committed: boolean) => void): voidlocal 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 } },
})Parâmetros
Prop
Type
Retorno
Nada diretamente; o callback recebe true ou false. Um rollback imprime o erro no console e dispara oxmysql:transaction-error.
startTransaction
Abre uma transação e dá à sua função um helper query ligado a ela. Retorne false da sua função para fazer rollback. Ela expira depois de 30 segundos.
Lado: Servidor · Espera: sim (Promise)
startTransaction(work: (query: (sql: string, params?: unknown[] | object) => Promise<unknown>) => Promise<boolean | void>): Promise<boolean>Retorno
Promise<boolean>: true quando confirmada. false quando sua função retornou false, lançou um erro, ou os 30 segundos acabaram.
Exemplo
// Um recurso JavaScript ou TypeScript puro sem @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; // dinheiro insuficiente: rollback
await query("UPDATE my_accounts SET money = money + ? WHERE owner = ?", [amount, to]);
});
}Nomes de exports antigos
| Recurso antigo | Nomes | O mesmo que |
|---|---|---|
| ghmattimysql | execute, scalar, transaction, store (e executeSync, scalarSync, ...) | query, scalar, transaction, store |
| mysql-async | mysql_execute, mysql_insert, mysql_fetch_all, mysql_fetch_scalar, mysql_transaction, mysql_store | update, insert, query, scalar, transaction, store |
Regras de callback e de erro
Elas seguem o oxmysql:
- Sucesso: o callback recebe o resultado.
- Falha com uma forma com promise (ou
.awaitem Lua): a promise é rejeitada com o texto do erro. - Falha com um callback simples: o erro é impresso no console e o callback não é chamado.
Eventos
oxmysql:error
Lado: Servidor (local) · disparado quando uma consulta falha.
Prop
Type
oxmysql:transaction-error
Lado: Servidor (local) · disparado quando uma transaction faz rollback. Payload { message: string, resource: string }.
on("oxmysql:error", (e: { query?: string; message: string; resource: string }) => {
console.log(`[db] ${e.resource}: ${e.message} (${e.query ?? "?"})`);
});Sempre passe valores como parâmetros, nunca os juntando ao texto SQL. Um valor de um jogador colocado direto no SQL deixa ele rodar as próprias consultas.
ai-mysql
O motor de banco de dados para scripts de terceiros. Substitui o oxmysql, o mysql-async e o ghmattimysql.
ai-lib
A UI compartilhada do jogador que todo script usa (notificações, barra de progresso, avisos, menus, caixas de entrada, minigames) e os helpers do AI Core para recursos em Lua e JavaScript.