¿Cómo conectar una base de datos MySQL a un servidor FiveM con oxmysql?
Crear la base en el panel, instalar oxmysql, escribir mysql_connection_string en server.cfg, importar el SQL de ESX o QBCore y corregir los errores de
oxmysql es el recurso que conecta un servidor FiveM o RedM a una base de datos MySQL o MariaDB. ESX Legacy, QBCore y Qbox dependen de él: sin conexión a la base, el framework no arranca. En ACLClouds, la base está alojada en un servidor MariaDB aparte e incluida en el plan: 1 base con Dev, 2 con City, 3 con Empire.
Procedimiento paso a paso
-
Crear la base
En «Bases de datos», haga clic en «Nueva base de datos», dele un nombre corto como esx o qbcore y deje «Conexiones desde» vacío para autorizar el servidor de juego y su PC. El panel añade un prefijo al nombre: la base se llama, por ejemplo, s12345_esx.
-
Recopilar identificadores
Abra la base en la lista: el panel muestra el «Punto de conexión» (host y puerto), el «Nombre de usuario», la «Contraseña» y una cadena de conexión JDBC. El host es la dirección del servidor de bases de datos, nunca localhost ni 127.0.0.1.
-
Instalar oxmysql
Descargue oxmysql.zip de la última versión publicada en la página Releases del repositorio de GitHub overextended/oxmysql, no el código fuente: solo el archivo publicado contiene los archivos compilados. Descomprímalo en resources/[standalone]/oxmysql con «Archivos». Las recetas ESX y QBCore de txAdmin ya lo instalan.
-
Escribir la conexión en server.cfg
Añada set mysql_connection_string con el usuario, la contraseña, el host, el puerto y el nombre de la base, y luego ensure oxmysql antes del framework y de todos los recursos que usan la base.
-
Importar las tablas
Los frameworks y muchos scripts incluyen un archivo .sql. Impórtelo desde su PC con HeidiSQL, DBeaver o el cliente mariadb, con las credenciales del panel. Una receta de txAdmin crea sus propias tablas.
-
Reiniciar y leer la consola
Al arrancar, oxmysql indica en la consola que está conectado a la base, con la versión de MariaDB. Un error casi siempre nombra su causa: host, contraseña o nombre de la base.
Conexión en server.cfg (formato URL)
set mysql_connection_string "mysql://u12345_AbCdEf:PASSWORD@HOST:3306/s12345_esx?charset=utf8mb4"
ensure oxmysql
ensure es_extended
Otro formato aceptado por oxmysql
set mysql_connection_string "host=HOST;port=3306;user=u12345_AbCdEf;password=PASSWORD;database=s12345_esx"
Opciones útiles de oxmysql
set mysql_slow_query_warning 150
set mysql_ui true
Importar y exportar desde un PC
mariadb -h HOST -P 3306 -u u12345_AbCdEf -p s12345_esx < es_extended.sql
mariadb-dump -h HOST -P 3306 -u u12345_AbCdEf -p s12345_esx > backup.sql
Antes de empezar
Las bases de datos están incluidas en los planes FiveM de pago, hasta el límite indicado arriba en «Bases de datos». Cada base tiene su propio usuario y sus propios permisos. Todos los scripts de un mismo servidor suelen compartir la misma base.
- Detenga el servidor antes de modificar server.cfg.
- Con txAdmin, modifique el server.cfg de la receta, en la carpeta txData, y no el de la raíz.
- No ejecute mysql-async ni ghmattimysql al mismo tiempo: oxmysql ofrece sus funciones a los scripts antiguos.
Caracteres especiales en la contraseña
En el formato URL, los caracteres @, :, /, #, ? y % de la contraseña rompen la cadena. Codifíquelos (@ pasa a ser %40), use el formato key=value o reutilice la cadena JDBC del panel, donde la contraseña ya está codificada, quitando el prefijo jdbc:.
El botón de rotación de la contraseña genera una nueva: actualice server.cfg enseguida o oxmysql no podrá conectarse en el siguiente arranque.
Hacer copia de la base
Las copias de seguridad del panel copian los archivos del servidor, no la base de datos. Expórtela con regularidad con mariadb-dump o la exportación de HeidiSQL, sobre todo antes de cada actualización del framework, y guarde una copia fuera del servidor.
Errores habituales y soluciones
oxmysql escribe la causa del fallo en la consola al arrancar el servidor.
- ECONNREFUSED o ETIMEDOUT: host o puerto incorrectos. Vuelva a copiar el «Punto de conexión»; localhost no funciona, la base no está en el contenedor del juego.
- ER_ACCESS_DENIED_ERROR: usuario o contraseña incorrectos, a menudo por un carácter especial sin codificar, o un valor de «Conexiones desde» que excluye el servidor de juego.
- ER_BAD_DB_ERROR: nombre de base desconocido. Indique el nombre completo con su prefijo, por ejemplo s12345_esx.
- ER_NO_SUCH_TABLE: la base está vacía o incompleta. Importe el archivo .sql del framework o del script correspondiente.
- No such export sobre oxmysql al cargar un script: oxmysql arranca demasiado tarde. Coloque ensure oxmysql antes del framework.
Verificación rápida
- La consola muestra la conexión de oxmysql a la base, sin errores.
- ensure oxmysql está antes del framework.
- Las tablas del framework aparecen en HeidiSQL o DBeaver.
- Hay una exportación .sql reciente guardada fuera del servidor.
Preguntas frecuentes
¿Hay que instalar MySQL en el servidor FiveM?
No. La base está alojada en un servidor MariaDB separado, incluido en el plan: la crea en «Bases de datos» y oxmysql se conecta a ella por la red. MariaDB es compatible con MySQL para ESX, QBCore y Qbox.
¿Cómo ver y modificar las tablas?
Conéctese desde su PC con HeidiSQL o DBeaver, con el host, el puerto, el usuario y la contraseña que muestra el panel. Haga una exportación antes de cualquier cambio manual.
¿Se puede usar una base de datos externa?
Sí. oxmysql se conecta a cualquier servidor MySQL o MariaDB accesible desde el servidor de juego: indique su host y sus credenciales en mysql_connection_string. Una base cercana al servidor de juego responde más rápido, algo importante para los scripts que la consultan a menudo.
La consola habla de consultas lentas, ¿qué hago?
oxmysql señala las consultas que superan mysql_slow_query_warning (200 ms por defecto) y nombra el recurso responsable. Añada un índice en la columna que filtra o sustituya el script: un recurso que consulta la base en bucle ralentiza todo el servidor.