Almost every modern FiveM roleplay framework — QBCore, ESX, and the ox ecosystem — depends on a database, and the resource that talks to that database is oxmysql. It is the maintained MySQL/MariaDB wrapper from Overextended, and it replaced the older mysql-async and ghmattimysql resources you may still see referenced in old tutorials. If your server logs are full of “database not connected” errors, or players lose their characters on restart, the cause is almost always a misconfigured connection string. This guide walks through installing oxmysql, building a correct mysql_connection_string, managing your database with HeidiSQL, and using the query handlers in your own scripts.
What oxmysql is and why you need it
oxmysql is a standalone FXServer resource that opens a connection pool to your MySQL or MariaDB database and exposes query functions to every other resource on the server. Frameworks list it as a dependency in their fxmanifest.lua, so it must start before anything that uses it. It automatically uses prepared statements, which sanitises parameters and protects against SQL injection — a big reason not to hand-roll your own database code.
Both MySQL and MariaDB work. MariaDB is a drop-in MySQL fork and is what most Linux-based FiveM hosts ship by default; the connection string format is identical for both. If you are still choosing where to run your server, see our managed FiveM hosting plans, which come with a database ready to go so you can skip most of the setup below.
Step 1: Install oxmysql
- Download the latest release from the official Overextended oxmysql GitHub releases page. Use the packaged release, not the source ZIP.
- Extract it and rename the folder to exactly
oxmysql(no version numbers or trailing characters), then drop it into yourresourcesfolder. - Add it to your
server.cfgand make sure it starts before any dependent resource — it is usually the very first thing you start.
# server.cfg — start oxmysql before frameworks and scripts
ensure oxmysql
ensure es_extended # or qb-core, etc. — must come AFTER oxmysqlUse ensure rather than start so the resource restarts cleanly if it stops. If you run multiple frameworks or a custom load order, confirm against the current docs, because resource names occasionally change between major versions.
Step 2: Set the mysql_connection_string convar
oxmysql reads its database credentials from a single convar, mysql_connection_string, which you set in server.cfg. The docs support two interchangeable formats: a URI style and a semicolon-separated key/value style. Pick whichever your credentials work with.
# URI format
set mysql_connection_string "mysql://root:12345@localhost:3306/es_extended"
# Semicolon / key-value format
set mysql_connection_string "user=root;password=12345;host=localhost;port=3306;database=es_extended"Replace root, the password, localhost, the port (3306 is the MySQL/MariaDB default), and the database name with your own values. Use set, never setr — setr replicates the value to clients, which would leak your database password to every player who connects.
A very common gotcha is a password containing reserved characters. Characters such as ; , / ? : @ & = + $ # can break a connection string. If your connection fails and the password contains any of these, the simplest fix is to switch to the other connection string format, or change the password to alphanumeric-only characters. The full list of caveats is documented on coxdocs.dev / overextended.dev — check it if you hit edge cases.
Step 3: Manage your database with HeidiSQL
HeidiSQL is the free Windows tool most FiveM admins use to create databases, import framework SQL files, and inspect player data. To connect, open HeidiSQL, create a new session, and enter the same host, user, password, and port you put in your connection string. Once connected you can create the database (for example es_extended or qbcore) and import the .sql file shipped with your framework.
- Hostname / IP: the same host as your connection string (often
127.0.0.1locally). - User & Password: match the credentials in
mysql_connection_string. - Port:
3306unless your host uses a custom port.
On a managed host you’ll usually be given these details (and sometimes phpMyAdmin instead of HeidiSQL). Linux server admins can use the mysql CLI or DBeaver, which work the same way cross-platform.
Step 4: Verify the connection
Start the server and watch the console. A healthy oxmysql start logs a message confirming it established a connection to your database and the MySQL/MariaDB version. If you instead see authentication or “unable to connect” errors, work through this checklist:
| Symptom | Likely cause | Fix |
|---|---|---|
| Access denied for user | Wrong user/password | Re-check credentials in HeidiSQL, then mirror them in the convar |
| Can’t connect / timeout | Wrong host or port, DB not running | Confirm host/port; ensure MySQL/MariaDB service is started |
| Unknown database | Database name doesn’t exist | Create it in HeidiSQL and import the framework SQL |
| Password parse errors | Reserved characters in password | Swap connection string format or use an alphanumeric password |
Using oxmysql query handlers in your scripts
oxmysql exposes a set of query functions for your own server-side Lua, JS, or C# resources. The main handlers documented by Overextended include query, scalar, single, insert, update, prepare, and transaction. Each has an asynchronous (callback) form and an .await form for use inside a coroutine.
MySQL.query— returns all matching rows; for non-SELECT statements returns metadata likeinsertIdandaffectedRows.MySQL.single— returns the first matching row only.MySQL.scalar— returns a single value from the first column of the first row.MySQL.insert— runs an INSERT and returns the newinsertId.MySQL.prepare— runs a frequently-called query faster and accepts multiple parameter sets.
-- Server-side Lua example (await form)
local player = MySQL.single.await(
'SELECT * FROM users WHERE identifier = ?',
{ source_identifier }
)
local count = MySQL.scalar.await('SELECT COUNT(*) FROM users')Always pass values as the second parameter array rather than concatenating them into the query string — that is what makes the prepared-statement protection work. Function signatures and the exact mysql-async backwards-compatibility layer are version-dependent, so confirm names and arguments in the current oxmysql function docs before shipping a script.
With the database connected you can move on to the rest of your stack: see our walkthroughs for installing QBCore and setting up ox_inventory, both of which require oxmysql to be running first. The official FiveM database docs and our FiveM setup documentation are good references when something doesn’t line up.
FAQ
Where do I set the oxmysql connection string?
In your server.cfg using the set mysql_connection_string convar. Use set (server-only) and never setr, because setr replicates the value — including your password — to connected clients.
Does oxmysql work with MariaDB?
Yes. MariaDB is a MySQL-compatible fork and uses the same connection string format. Most Linux FiveM hosts ship MariaDB by default, and oxmysql connects to it exactly as it does to MySQL.
Why does my server say the database isn’t connected?
The usual causes are wrong credentials, a database that doesn’t exist yet, the MySQL/MariaDB service not running, or reserved characters in the password breaking the connection string. Verify the credentials in HeidiSQL first, then mirror them exactly in your convar, and make sure ensure oxmysql appears before dependent resources.
Ready to play?
Run your own FiveM server with XGamingServer
Spin up an always-on FiveM server your friends can join in minutes — no port-forwarding, no tech headaches.
