EN

Game servers

How to Install and Configure oxmysql on FiveM

Install or update oxmysql on your FiveM Linux server, write a correct MariaDB connection string, check the connection and fix the most common errors.

7 min read, updated on 18 November 2026

On this page

oxmysql is the resource that connects your FiveM server to its database. ESX Legacy, QBCore and many scripts depend on it. This guide explains how to install or update it, write the connection string, check that it works and fix common errors.

Prerequisites

  • A server installed with the guide Create a FiveM Server
  • MariaDB installed, with the fivem database and the fivem user created in that guide
  • Access to txAdmin, for CFG Editor and Live Console

Check What Is Already Installed

The ESX Legacy and QBCore recipes already install oxmysql. First locate your server folder, whose name ends in .base:

Terminal
sudo find /home/fivem/txData -maxdepth 1 -type d -name '*.base'

If several folders appear, the right one is the one in Server Data Folder, under Settings, FXServer tab. Then open a fivem session and look for the resource, replacing FOLDER_NAME:

Terminal
sudo -iu fivem
BASE=/home/fivem/txData/FOLDER_NAME.base
find "$BASE/resources" -type d -name oxmysql
grep -E "^version" "$(find "$BASE/resources" -type f -path '*/oxmysql/fxmanifest.lua' | head -n 1)"
exit

Note the path displayed. On the ESX Legacy and QBCore recipes, it is resources/[standalone]/oxmysql. If find returns no path, oxmysql is not installed and grep reports a harmless error.

Install or Update oxmysql

Back up the server, install unzip, then stop the service:

Terminal
sudo /usr/local/sbin/backup-fivem.sh
sudo apt install -y unzip
sudo systemctl stop fivem.service
sudo -iu fivem

In the fivem session, download the latest version and replace the old one. Adjust TARGET if the path you noted above is different:

Terminal
BASE=/home/fivem/txData/FOLDER_NAME.base
TARGET="$BASE/resources/[standalone]/oxmysql"

TMP=$(mktemp -d "$HOME/oxmysql.XXXXXX")
curl -fL -o "$TMP/oxmysql.zip" https://github.com/overextended/oxmysql/releases/latest/download/oxmysql.zip
unzip -q "$TMP/oxmysql.zip" -d "$TMP"
grep -E "^version" "$TMP/oxmysql/fxmanifest.lua"

rm -rf "$HOME/oxmysql.previous"
[ -d "$TARGET" ] && mv "$TARGET" "$HOME/oxmysql.previous"
mkdir -p "$(dirname "$TARGET")"
mv "$TMP/oxmysql" "$TARGET"
rm -rf "$TMP"
ls "$TARGET"
exit

The folder must contain fxmanifest.lua, dist and lib. The old version stays in /home/fivem/oxmysql.previous, outside resources so that FXServer does not load it.

Configure server.cfg

In txAdmin, open CFG Editor. The connection string must be defined before the resources start:

Text
set mysql_connection_string "mysql://fivem:GENERATED_PASSWORD@127.0.0.1/fivem?charset=utf8mb4"

ensure oxmysql

Place ensure oxmysql before the framework and the resources that use the database. The QBCore recipe does not have this line: it starts the whole [standalone] folder, and qb-core launches oxmysql as a dependency. There is no need to add it in that case.

The Two String Formats

oxmysql accepts two equivalent syntaxes:

Text
set mysql_connection_string "mysql://fivem:GENERATED_PASSWORD@127.0.0.1:3306/fivem?charset=utf8mb4"
set mysql_connection_string "user=fivem;password=GENERATED_PASSWORD;host=127.0.0.1;port=3306;database=fivem;charset=utf8mb4"

Keep only one of these lines.

Element Value Note
User fivem Do not use root
Password Generated value Letters and digits only, with openssl rand -hex 16
Host 127.0.0.1 Prevents localhost from being resolved to IPv6 while MariaDB listens on IPv4
Port 3306 Optional if it is the default port
Database fivem Or fivem_rp if you created another one
charset utf8mb4 Keeps accents and emojis

The oxmysql documentation advises against these characters in values: ; , / ? : @ & = + $ #. The simplest approach is not to use any in the password.

Check the Connection

First test the credentials directly with MariaDB. The command asks for the password:

Terminal
mariadb -h 127.0.0.1 -P 3306 -u fivem -p fivem -e "SELECT VERSION();"

If the version is displayed, start the server and look for the oxmysql success message:

Terminal
sudo systemctl start fivem.service
sudo grep -a 'Database server connection established' /home/fivem/fxserver.log

If you only modified server.cfg, restart the server from txAdmin instead. Finally, check that the resource is active:

Terminal
curl -fsS http://127.0.0.1:30120/info.json | grep -o '"oxmysql"'

Useful Settings

These variables go in server.cfg, before ensure oxmysql, always with set:

Variable Effect Default value
mysql_slow_query_warning Threshold, in milliseconds, above which a query is reported as slow 200
mysql_debug Displays queries in the console false
mysql_ui Enables the in-game monitoring interface, opened with the /mysql command false

The /mysql interface also requires the command.mysql permission: see Manage ACE Permissions on FiveM. The oxmysql documentation reserves it for development or servers with few players.

To follow a single resource without restarting, type in Live Console, then remove it once the analysis is finished:

Text
oxmysql_debug add es_extended
oxmysql_debug remove es_extended

Do not leave mysql_debug enabled permanently: the displayed queries may contain player data and fill the logs.

Rolling Back to the Previous Version

Terminal
sudo systemctl stop fivem.service
sudo -iu fivem
Terminal
BASE=/home/fivem/txData/FOLDER_NAME.base
TARGET="$BASE/resources/[standalone]/oxmysql"
rm -rf "$HOME/oxmysql.failed"
mv "$TARGET" "$HOME/oxmysql.failed"
mv "$HOME/oxmysql.previous" "$TARGET"
exit
Terminal
sudo systemctl start fivem.service

Troubleshooting

When the connection fails, oxmysql displays Unable to establish a connection to the database, followed by a code in parentheses. Find it with:

Terminal
sudo grep -a -A2 'Unable to establish a connection' /home/fivem/fxserver.log

Unable to establish a connection to the database (ECONNREFUSED)

MariaDB does not respond at the given address.

  • Check the service with sudo systemctl status mariadb.
  • Check the listening port with sudo ss -ltnp | grep ':3306'.
  • If the error mentions ::1, replace localhost with 127.0.0.1 in the string.

ER_ACCESS_DENIED_ERROR

Read the account quoted in the message carefully:

  • 'fivem'@'localhost' (using password: YES): the password is incorrect. Compare it with the one tested by the mariadb command.
  • 'root'@'localhost' (using password: NO): oxmysql did not read your string and is using its fallback value. Check that the line is written set mysql_connection_string, that it is not commented out, and that it is located before ensure oxmysql.
  • 'fivem'@'127.0.0.1': MariaDB does not link this address to the localhost account, which happens notably with the skip_name_resolve option. Create an account for this address in sudo mariadb:
SQL
CREATE USER 'fivem'@'127.0.0.1' IDENTIFIED BY 'GENERATED_PASSWORD';
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'127.0.0.1';
FLUSH PRIVILEGES;

ER_BAD_DB_ERROR

The Unknown database message indicates that the database does not exist. Compare the name in the string with the list returned by sudo mariadb -e "SHOW DATABASES;".

ER_DBACCESS_DENIED_ERROR

The user exists but has no rights on this database. Grant them in sudo mariadb:

SQL
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;

The password contains special characters

A : or a / in the password splits the string in the wrong place, and the error then reports an unexpected host or user. Generate a new password with openssl rand -hex 16, apply it in sudo mariadb, then update server.cfg:

SQL
ALTER USER 'fivem'@'localhost' IDENTIFIED BY 'GENERATED_PASSWORD';

Could not find dependency oxmysql for resource

The quoted resource needs oxmysql, which cannot be found. Check that the folder directly contains fxmanifest.lua, and not an oxmysql/oxmysql subfolder. Then type refresh followed by ensure oxmysql in Live Console.

Resource 'oxmysql' can't run

If the following line says server needs to be 12913 or higher, Update FXServer Artifacts, or roll back to the previous version of oxmysql in the meantime.

Table 'fivem.xxx' doesn't exist

A resource expects a table that was not created. Import the .sql file provided with this resource, after making a backup:

Terminal
sudo mariadb fivem < /path/to/file.sql

took 350.0000ms to execute a query

This message reports a slow query, with the name of the resource that launched it. It is normal at startup and can also come from a general slowdown of the server. If it often comes back in game for the same resource, follow Diagnose Crashes and Lag on a FiveM Server.

Conflict with mysql-async or ghmattimysql

oxmysql replaces these two resources and responds in their place. Remove their ensure line and delete their folder, after making a backup.