oxmysql para FiveM: qué es, errores comunes y la skill de IA

oxmysql es la librería de base de datos para FiveM que sustituyó a mysql-async y ghmattimysql. Corre solo en el servidor, habla con MySQL o MariaDB y expone una API Lua pequeña bajo el global MySQL. Si tu recurso guarda algo (datos de jugador, vehículos, inventarios, logs), esta es la capa contra la que escribes. El SKILL.md recomienda MariaDB sobre MySQL 8 por compatibilidad.

Qué te da oxmysql

El setup es una línea en fxmanifest.lua, colocada antes del resto de scripts de servidor: server_script '@oxmysql/lib/MySQL.lua'. A partir de ahí, la tabla MySQL está disponible en todos los scripts de servidor del recurso.

• MySQL.query y MySQL.query.await: ejecutan cualquier sentencia. Un SELECT devuelve filas; el resto devuelve insertId o affectedRows.
• MySQL.insert: inserta una fila y devuelve el nuevo insert id.
• MySQL.update: actualiza filas y devuelve el número de filas afectadas.
• MySQL.single: una fila o nil, la llamada correcta para “carga este jugador”.
• MySQL.scalar: un valor de una fila y una columna, para contadores y saldos.
• MySQL.prepare: sentencias preparadas solo con placeholders ?, más rápidas cuando repites la misma consulta muchas veces.
• MySQL.rawExecute: ejecución cruda sin forma de resultado automática.
• MySQL.transaction: varias consultas que se aplican o fallan juntas.

Todas las funciones reciben parámetros mediante placeholders ?. Los valores nunca van dentro de la cadena SQL. La referencia está en coxdocs.dev/oxmysql.

Errores comunes con oxmysql

• Usar la API de mysql-async. MySQL.Sync.fetchAll y MySQL.Async.execute vienen de una librería que ya no se mantiene. En código nuevo fallan o dependen de una capa de compatibilidad que no controlas. Usa MySQL.query.await, MySQL.insert y el resto de la API de oxmysql.
• Llamar a MySQL desde un script de cliente. La librería es solo de servidor. Un cliente no tiene acceso a la base de datos ni global MySQL. Pon la consulta en un script de servidor y entrega el resultado al cliente por un evento o un callback.
• Concatenar valores en el SQL. 'SELECT * FROM users WHERE identifier = "' .. identifier .. '"' es una inyección esperando a ocurrir. Escribe MySQL.single.await('SELECT * FROM users WHERE identifier = ?', { identifier }).
• Esperar una consulta por fila dentro de un bucle. Guardar 300 vehículos con MySQL.update.await dentro de un for son 300 viajes a la base de datos. Agrupa el trabajo en una sola sentencia cuando puedas, o envuelve el conjunto en MySQL.transaction.
• Olvidar la línea de la lib en el manifest. El síntoma es “attempt to index a nil value (global ‘MySQL’)” en la primera consulta. Añade server_script '@oxmysql/lib/MySQL.lua' antes del resto de scripts de servidor.

Por qué los asistentes de IA se equivocan con oxmysql

Los asistentes genéricos han leído una década de scripts de FiveM, y la mayoría usa mysql-async. Pide “guardar el dinero del jugador” y recibes MySQL.Async.execute con el valor concatenado en la cadena, a veces dentro de un archivo de cliente. No corre en ningún sitio, o peor, corre y deja el servidor abierto a inyecciones.

La skill de oxmysql da al asistente un archivo de reglas por función: placeholders.md, query.md, insert.md, prepare.md, update.md, single.md, scalar.md, rawExecute.md y transaction.md. Cada uno indica qué devuelve la función y cómo se pasan los parámetros. El asistente lee la regla que coincide con tu petición y escribe código que usa la API real en el lado correcto de la red.

Instala la skill de oxmysql en 30 segundos

1. Haz clic en “Download SKILL.md” en la parte superior de esta página.
2. Descomprímelo en la carpeta de skills o rules de tu herramienta de IA. La sección de instalación de abajo muestra la ruta exacta para Claude Code, Cursor y VS Code.
3. Pide al asistente algo concreto, como “carga el saldo bancario de un jugador por identifier”, y comprueba que usa MySQL.scalar.await con un placeholder ? en un script de servidor.