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.
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
fivemdatabase and thefivemuser 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:
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:
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)"
exitNote 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:
sudo /usr/local/sbin/backup-fivem.sh
sudo apt install -y unzip
sudo systemctl stop fivem.service
sudo -iu fivemIn the fivem session, download the latest version and replace the old one. Adjust TARGET if the path you noted above is different:
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"
exitThe 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:
set mysql_connection_string "mysql://fivem:GENERATED_PASSWORD@127.0.0.1/fivem?charset=utf8mb4"
ensure oxmysqlPlace 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:
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:
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:
sudo systemctl start fivem.service
sudo grep -a 'Database server connection established' /home/fivem/fxserver.logIf you only modified server.cfg, restart the server from txAdmin instead. Finally, check that the resource is active:
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:
oxmysql_debug add es_extended
oxmysql_debug remove es_extendedDo not leave mysql_debug enabled permanently: the displayed queries may contain player data and fill the logs.
Rolling Back to the Previous Version
sudo systemctl stop fivem.service
sudo -iu fivemBASE=/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"
exitsudo systemctl start fivem.serviceTroubleshooting
When the connection fails, oxmysql displays Unable to establish a connection to the database, followed by a code in parentheses. Find it with:
sudo grep -a -A2 'Unable to establish a connection' /home/fivem/fxserver.logUnable 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, replacelocalhostwith127.0.0.1in 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 themariadbcommand.'root'@'localhost' (using password: NO): oxmysql did not read your string and is using its fallback value. Check that the line is writtenset mysql_connection_string, that it is not commented out, and that it is located beforeensure oxmysql.'fivem'@'127.0.0.1': MariaDB does not link this address to thelocalhostaccount, which happens notably with theskip_name_resolveoption. Create an account for this address insudo mariadb:
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:
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:
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:
sudo mariadb fivem < /path/to/file.sqltook 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.