oxmysql can't connect: ECONNREFUSED, access denied, unknown database

When your server starts, oxmysql prints one of these and every script that touches the database fails after it:

Error: connect ECONNREFUSED 127.0.0.1:3306
ER_ACCESS_DENIED_ERROR: Access denied for user 'root'@'localhost' (using password: YES)
Unknown database 'fivem'

Each line means something different. This guide shows how to read them, how to write the connection string, and what to check on the database server.

#The connection string

oxmysql gets everything from one convar in server.cfg. The URL form:

set mysql_connection_string "mysql://user:password@localhost/dbname?charset=utf8mb4"

The key=value form does the same:

set mysql_connection_string "user=fivem;password=yourpassword;host=127.0.0.1;port=3306;database=fivem"

Put it above ensure oxmysql, and above any script that uses the database:

set mysql_connection_string "mysql://fivem:yourpassword@localhost/fivem?charset=utf8mb4"

ensure oxmysql
ensure ox_lib
ensure es_extended

Tip: txAdmin recipes create this line for you. If you edit it by hand, keep the quotes, and keep it on a single line.

#ECONNREFUSED: nothing is listening

ECONNREFUSED means the database server refused the connection or is not running at that address and port. Work through these in order:

1. Is MariaDB or MySQL running? On Windows with XAMPP, start MySQL in the control panel. With a service install, check Services. On Linux:

sudo systemctl status mariadb
# or: sudo systemctl status mysql
sudo systemctl start mariadb

2. Is the host and port right? localhost and 127.0.0.1 are the same machine, the default port is 3306. If your database is on another machine or a managed host, use its address and port, and check that its firewall allows your game server's IP.
3. Is the database bound to the right address? If it only listens on the local machine, a remote game server cannot reach it.

#ER_ACCESS_DENIED_ERROR: wrong login

Access denied for user means the server answered, but rejected the user, the password, or the host that user is allowed to connect from.

• Check the user and password by logging in yourself with the same values:

mysql -u fivem -p -h 127.0.0.1

• Create a dedicated user instead of using root. In the MariaDB or MySQL console:

CREATE DATABASE fivem CHARACTER SET utf8mb4;
CREATE USER 'fivem'@'localhost' IDENTIFIED BY 'yourpassword';
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;

• A user is tied to a host. 'fivem'@'localhost' cannot connect from another machine. For a remote game server, create the user for that host instead.
• root on a fresh Linux install often uses socket authentication, so a password login over the network fails. A separate user avoids the problem.

#Special characters in the password

In the mysql:// form, the password sits inside a URL. Characters with a meaning in URLs break it, and the error you get is usually access denied. Encode them:

So the password p@ss#1 becomes:

set mysql_connection_string "mysql://fivem:p%40ss%231@localhost/fivem?charset=utf8mb4"

The simplest alternatives are a password made of letters and digits only, or the user=...;password=... form, where only ; in the password is a problem.

#Unknown database: the name does not exist

Unknown database 'fivem' means the login worked, but no database with that name exists. Two causes:

• The name is misspelled. The name in the connection string must match exactly. On Linux, database names are case sensitive.
• You never created it. Create it, then import your framework's SQL file into it:

CREATE DATABASE fivem CHARACTER SET utf8mb4;

After that, the next problem is usually missing tables, covered in Table 'db.x' doesn't exist.

#Check that it worked

Restart oxmysql from the server console and read the output:

restart oxmysql

When the connection succeeds, oxmysql reports the database server version and no error follows. If a script still fails, the problem is that script's own query, not the connection.

#Order in server.cfg

oxmysql has to be started before anything that queries the database. Here is the order that works for an ESX server:

set mysql_connection_string "mysql://fivem:yourpassword@localhost/fivem?charset=utf8mb4"

ensure oxmysql
ensure ox_lib
ensure es_extended
ensure my_script

On QBCore or QBox, swap es_extended for qb-core or qbx_core. A core that starts before oxmysql can fail with errors that look like framework problems, for example the ones in ESX is nil.

#Checklist