oxmysql para FiveM: o que é, erros comuns e a skill de IA

oxmysql é a biblioteca de banco de dados para FiveM que substituiu o mysql-async e o ghmattimysql. Roda apenas no servidor, conversa com MySQL ou MariaDB e expõe uma API Lua pequena no global MySQL. Se o seu recurso guarda qualquer coisa (dados de jogador, veículos, inventários, logs), esta é a camada contra a qual você escreve. O SKILL.md recomenda MariaDB em vez de MySQL 8 por compatibilidade.

O que o oxmysql oferece

O setup é uma linha no fxmanifest.lua, colocada antes dos outros scripts de servidor: server_script '@oxmysql/lib/MySQL.lua'. A partir daí, a tabela MySQL fica disponível em todos os scripts de servidor do recurso.

• MySQL.query e MySQL.query.await: executam qualquer instrução. Um SELECT retorna linhas; as demais retornam insertId ou affectedRows.
• MySQL.insert: insere uma linha e retorna o novo insert id.
• MySQL.update: atualiza linhas e retorna o número de linhas afetadas.
• MySQL.single: uma linha ou nil, a chamada certa para “carregue este jogador”.
• MySQL.scalar: um valor de uma linha e uma coluna, para contagens e saldos.
• MySQL.prepare: instruções preparadas apenas com placeholders ?, mais rápidas quando você repete a mesma consulta muitas vezes.
• MySQL.rawExecute: execução crua sem formato de resultado automático.
• MySQL.transaction: várias consultas que são aplicadas ou falham juntas.

Todas as funções recebem parâmetros por placeholders ?. Os valores nunca entram na string SQL. A referência está em coxdocs.dev/oxmysql.

Erros comuns com oxmysql

• Usar a API do mysql-async. MySQL.Sync.fetchAll e MySQL.Async.execute vêm de uma biblioteca que não é mais mantida. Em código novo, falham ou dependem de uma camada de compatibilidade que você não controla. Use MySQL.query.await, MySQL.insert e o resto da API do oxmysql.
• Chamar MySQL de um script de cliente. A biblioteca é só de servidor. O cliente não tem acesso ao banco nem ao global MySQL. Coloque a consulta em um script de servidor e entregue o resultado ao cliente por evento ou callback.
• Concatenar valores no SQL. 'SELECT * FROM users WHERE identifier = "' .. identifier .. '"' é uma injeção esperando para acontecer. Escreva MySQL.single.await('SELECT * FROM users WHERE identifier = ?', { identifier }).
• Esperar uma consulta por linha dentro de um loop. Salvar 300 veículos com MySQL.update.await dentro de um for são 300 idas ao banco. Agrupe o trabalho em uma única instrução quando puder, ou envolva o conjunto em MySQL.transaction.
• Esquecer a linha da lib no manifest. O sintoma é “attempt to index a nil value (global ‘MySQL’)” na primeira consulta. Adicione server_script '@oxmysql/lib/MySQL.lua' antes dos outros scripts de servidor.

Por que assistentes de IA erram com oxmysql

Assistentes genéricos leram uma década de scripts FiveM, e a maioria usa mysql-async. Peça “salvar o dinheiro do jogador” e você recebe MySQL.Async.execute com o valor concatenado na string, às vezes dentro de um arquivo de cliente. Não roda em lugar nenhum, ou pior, roda e deixa o servidor aberto a injeções.

A skill do oxmysql dá ao assistente um arquivo de regras por função: placeholders.md, query.md, insert.md, prepare.md, update.md, single.md, scalar.md, rawExecute.md e transaction.md. Cada um indica o que a função retorna e como os parâmetros são passados. O assistente lê a regra que corresponde ao seu pedido e escreve código que usa a API real do lado certo da rede.

Instale a skill do oxmysql em 30 segundos

1. Clique em “Download SKILL.md” no topo desta página.
2. Descompacte na pasta de skills ou rules da sua ferramenta de IA. A seção de instalação abaixo mostra o caminho exato para Claude Code, Cursor e VS Code.
3. Peça ao assistente algo concreto, como “carregue o saldo bancário de um jogador pelo identifier”, e confira se ele usa MySQL.scalar.await com um placeholder ? em um script de servidor.