ACLClouds
ACLClouds

How do I connect a MySQL database to a FiveM server with oxmysql?

Create the database in the panel, install oxmysql, write mysql_connection_string in server.cfg, import the ESX or QBCore SQL and fix the usual connection

oxmysql is the resource that connects a FiveM or RedM server to a MySQL or MariaDB database. ESX Legacy, QBCore and Qbox depend on it: without a database connection, the framework does not start. On ACLClouds, the database runs on a separate MariaDB server and is included in the plan: 1 database with Dev, 2 with City, 3 with Empire.

Step-by-step procedure

  1. Create the database

    In “Databases”, click “New Database”, give it a short name such as esx or qbcore and leave “Connections From” empty to allow both the game server and your PC. The panel prefixes the name: the database is called s12345_esx, for example.

  2. Collect identifiers

    Open the database in the list: the panel shows the “Endpoint” (host and port), the “Username”, the “Password” and a JDBC connection string. The host is the address of the database server, never localhost or 127.0.0.1.

  3. Install oxmysql

    Download oxmysql.zip from the latest release on the Releases page of the overextended/oxmysql GitHub repository, not the source code: only the release archive contains the built files. Extract it to resources/[standalone]/oxmysql with “Files”. The txAdmin ESX and QBCore recipes already install it.

  4. Write the connection in server.cfg

    Add set mysql_connection_string with the user, password, host, port and database name, then ensure oxmysql before the framework and before every resource that uses the database.

  5. Import the tables

    Frameworks and many scripts ship a .sql file. Import it from your PC with HeidiSQL, DBeaver or the mariadb client, using the panel credentials. A txAdmin recipe creates its own tables.

  6. Restart and read the console

    On start, oxmysql reports in the console that it is connected to the database, with the MariaDB version. An error almost always names its cause: host, password or database name.

Connection in server.cfg (URL format)

set mysql_connection_string "mysql://u12345_AbCdEf:PASSWORD@HOST:3306/s12345_esx?charset=utf8mb4"

ensure oxmysql
ensure es_extended

Other format accepted by oxmysql

set mysql_connection_string "host=HOST;port=3306;user=u12345_AbCdEf;password=PASSWORD;database=s12345_esx"

Useful oxmysql options

set mysql_slow_query_warning 150
set mysql_ui true

Import and export from a 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

Before you start

Databases are included in the paid FiveM plans, up to the limit shown at the top of “Databases”. Each database has its own user and permissions. All the scripts of one server usually share the same database.

  • Stop the server before editing server.cfg.
  • With txAdmin, edit the recipe’s server.cfg in the txData folder, not the one at the root.
  • Do not run mysql-async or ghmattimysql at the same time: oxmysql provides their functions for older scripts.

Special characters in the password

In the URL format, the @, :, /, #, ? and % characters in the password break the string. Encode them (@ becomes %40), use the key=value format, or reuse the panel’s JDBC string, where the password is already encoded, without its jdbc: prefix.

The password rotation button generates a new one: update server.cfg right away, otherwise oxmysql cannot connect on the next start.

Back up the database

Panel backups copy the server files, not the database. Export it regularly with mariadb-dump or the HeidiSQL export, especially before every framework update, and keep a copy off the server.

Common errors and fixes

oxmysql writes the cause of the failure in the console when the server starts.

  • ECONNREFUSED or ETIMEDOUT: wrong host or port. Copy the “Endpoint” again; localhost does not work, because the database is not inside the game container.
  • ER_ACCESS_DENIED_ERROR: wrong user or password, often because of an unencoded special character, or a “Connections From” value that excludes the game server.
  • ER_BAD_DB_ERROR: unknown database name. Use the full name with its prefix, for example s12345_esx.
  • ER_NO_SUCH_TABLE: the database is empty or incomplete. Import the .sql file of the framework or script concerned.
  • No such export on oxmysql when a script loads: oxmysql starts too late. Put ensure oxmysql before the framework.

Quick check

  • The console shows oxmysql connected to the database, with no error.
  • ensure oxmysql comes before the framework.
  • The framework tables show up in HeidiSQL or DBeaver.
  • A recent .sql export is stored off the server.

Frequently asked questions

Do I need to install MySQL on the FiveM server?

No. The database runs on a separate MariaDB server included in the plan: you create it in “Databases” and oxmysql connects to it over the network. MariaDB is compatible with MySQL for ESX, QBCore and Qbox.

How do I view and edit the tables?

Connect from your PC with HeidiSQL or DBeaver, using the host, port, user and password shown in the panel. Take an export before any manual change.

Can I use an external database?

Yes. oxmysql connects to any MySQL or MariaDB server reachable from the game server: put its host and credentials in mysql_connection_string. A database close to the game server answers faster, which matters for scripts that query it often.

The console mentions slow queries, what can I do?

oxmysql flags queries slower than mysql_slow_query_warning (200 ms by default) and names the resource involved. Add an index on the column it filters, or replace the script: a resource that queries the database in a loop slows down the whole server.