{"id":22055,"date":"2026-06-11T11:34:01","date_gmt":"2026-06-11T11:34:01","guid":{"rendered":"https:\/\/xgamingserver.com\/blog\/fivem-oxmysql-database-guide\/"},"modified":"2026-06-11T11:34:01","modified_gmt":"2026-06-11T11:34:01","slug":"fivem-oxmysql-database-guide","status":"publish","type":"post","link":"https:\/\/xgamingserver.com\/blog\/fivem-oxmysql-database-guide\/","title":{"rendered":"FiveM oxmysql Database Guide: Connecting MySQL\/MariaDB"},"content":{"rendered":"\n

Almost every modern FiveM roleplay framework \u2014 QBCore, ESX, and the ox ecosystem \u2014 depends on a database, and the resource that talks to that database is oxmysql<\/code>. 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<\/code>, managing your database with HeidiSQL, and using the query handlers in your own scripts.<\/p>\n\n\n\n

What oxmysql is and why you need it<\/h2>\n\n\n\n

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<\/code>, so it must start before<\/strong> anything that uses it. It automatically uses prepared statements, which sanitises parameters and protects against SQL injection \u2014 a big reason not to hand-roll your own database code.<\/p>\n\n\n\n

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<\/a>, which come with a database ready to go so you can skip most of the setup below.<\/p>\n\n\n\n

Step 1: Install oxmysql<\/h2>\n\n\n\n
    \n
  1. Download the latest release from the official Overextended oxmysql GitHub releases page. Use the packaged release, not the source ZIP.<\/li>\n
  2. Extract it and rename the folder to exactly oxmysql<\/code> (no version numbers or trailing characters), then drop it into your resources<\/code> folder.<\/li>\n
  3. Add it to your server.cfg<\/code> and make sure it starts before any dependent resource \u2014 it is usually the very first thing you start.<\/li>\n<\/ol>\n\n\n\n
    # server.cfg \u2014 start oxmysql before frameworks and scripts\nensure oxmysql\nensure es_extended   # or qb-core, etc. \u2014 must come AFTER oxmysql<\/code><\/pre>\n\n\n\n
    Use ensure<\/code> rather than start<\/code> 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.<\/p>\n\n\n\n
    Step 2: Set the mysql_connection_string convar<\/h2>\n\n\n\n
    oxmysql reads its database credentials from a single convar, mysql_connection_string<\/code>, which you set in server.cfg<\/code>. The docs support two interchangeable formats: a URI style and a semicolon-separated key\/value style. Pick whichever your credentials work with.<\/p>\n\n\n\n
    # URI format\nset mysql_connection_string \"mysql:\/\/root:12345@localhost:3306\/es_extended\"\n\n# Semicolon \/ key-value format\nset mysql_connection_string \"user=root;password=12345;host=localhost;port=3306;database=es_extended\"<\/code><\/pre>\n\n\n\n
    Replace root<\/code>, the password, localhost<\/code>, the port (3306<\/code> is the MySQL\/MariaDB default), and the database name with your own values. Use set<\/code>, never setr<\/code> \u2014 setr<\/code> replicates the value to clients, which would leak your database password to every player who connects.<\/p>\n\n\n\n
    A very common gotcha is a password containing reserved characters. Characters such as ; , \/ ? : @ & = + $ #<\/code> 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 \u2014 check it if you hit edge cases.<\/p>\n\n\n\n
    Step 3: Manage your database with HeidiSQL<\/h2>\n\n\n\n
    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<\/code> or qbcore<\/code>) and import the .sql<\/code> file shipped with your framework.<\/p>\n\n\n\n