How to Migrate ESX → QBCore the Right Way

Migrating a FiveM server from ESX to QBCore in 2026 takes eight ordered steps: freeze production and create a rollback snapshot, build a clean QBCore base on staging, replace mysql-async with oxmysql, map ESX user data to QBCore player data, stabilize identifiers by generating citizenids, port resource code from ESX exports to QBCore plus ox_lib, migrate inventory and items, and run a staged cutover with health checks. The goal is a clean switch with stable identifiers, oxmysql queries, ox_lib powered code, and minimal downtime — typically one maintenance window of two to four hours on a 64-slot server. This VertexMods guide walks through every step with the exact SQL, Lua, and ox_lib patterns required, plus a runbook checklist for the cutover. Most successful migrations stage the work over two weeks of testing before the production switch.

This guide is part of our complete FiveM frameworks guide, where we compare ESX, QBCore, and QBOX in depth and help you choose the right one.

---

How does an ESX to QBCore migration work end-to-end in 2026?

An ESX to QBCore migration in 2026 follows a fixed eight-step sequence designed to keep the production server live until the very last cutover window. Step 1 freezes production changes and creates a named database snapshot as a rollback point. Step 2 deploys a clean QBCore base to a staging server with only the essentials enabled — qb-core, oxmysql, and ox_lib. Step 3 replaces every legacy mysql-async call with oxmysql so queries become await-based and parameterised. Step 4 maps ESX user data structures (identifier, accounts, job, inventory) to QBCore equivalents (citizenid, money, job, inventory). Step 5 stabilizes player identifiers by generating citizenids and rewriting owned-vehicle rows to point at the new keys. Step 6 ports resource code from ESX exports to QBCore plus ox_lib for callbacks, UI, and commands. Step 7 migrates inventory and item definitions. Step 8 runs the cutover with a documented health-check checklist. The full Overview index sits below.

Key takeaways:

• An ESX to QBCore migration in 2026 follows a fixed eight-step ordered sequence.
• An ESX to QBCore migration starts with a frozen production database and a named snapshot.
• An ESX to QBCore migration replaces mysql-async with oxmysql before any data is touched.
• An ESX to QBCore migration stabilizes identifiers by generating QBCore citizenids in Lua.
• An ESX to QBCore migration ends with a documented cutover runbook and health checks.

• Prerequisites
• Step 1. Make a Plan and a Rollback Point
• Step 2. Build a Clean QBCore Base
• Step 3. Replace mysql-async with oxmysql
  • Common conversions
  • Step 4. Map ESX Data Structures to QBCore
  • Step 5. Stabilize Identifiers
    • SQL bootstrap
    • Generate citizenid and insert players in Lua
    • Move owned vehicles
    • Step 6. Port ESX Code to QBCore with ox_lib
      • Player object
      • Jobs
      • Callbacks and UI
      • Commands
      • Step 7. Inventory and Items
      • Step 8. Test and Roll Out
      • Troubleshooting
      • Cutover Checklist
      • Appendix A. Example fxmanifest for migration helper
      • Appendix B. Safe JSON helpers
      • What you achieved
      • Useful links inside your site
      • External references

---

What prerequisites do I need before migrating ESX to QBCore in 2026?

The prerequisites for an ESX to QBCore migration in 2026 fall into three groups: development tools, server artifacts, and supporting libraries. The development tools group requires Git with a dedicated migration branch, MariaDB or MySQL 8 with full backups enabled, and a staging server that mirrors production hardware and player count expectations as closely as possible. The server artifacts group requires an FXServer build that exactly matches the production version, the QBCore base framework with its default resources, and a fresh database created on the staging instance to receive the migrated data. The supporting libraries group requires oxmysql for every database query in the new stack and ox_lib for callbacks, UI helpers, notification primitives, and utility wrappers — both are open source from Overextended and are the de facto standard on every modern QBCore build. Skipping any of these prerequisites is the most common reason a migration stalls in step 6 with broken player data or unrecoverable schema mismatches.

Key takeaways:

• An ESX to QBCore migration prerequisites Git with a dedicated migration branch.
• An ESX to QBCore migration prerequisites a staging server that mirrors production.
• An ESX to QBCore migration prerequisites an FXServer build matching the production version.
• An ESX to QBCore migration prerequisites oxmysql for all queries in the new QBCore stack.
• An ESX to QBCore migration prerequisites ox_lib for callbacks, UI helpers, and utilities.

1. Tools
   1. GIT and a separate branch for the migration.
   2. MariaDB or MySQL 8 with full backups enabled.
   3. A staging server that mirrors production.
   4. Server artifacts
      1. FXServer updated to the same build as production.
      2. QBCore base framework and default resources.
      3. Libraries you will use

         1. oxmysql for database.

         2. ox_lib for callbacks, UI helpers, and utility wrappers.

            ---

            Step 1. Make a Plan and a Rollback Point

            1. Freeze production changes. Stop new script installs and DB writes not required for testing.
            2. Back up your entire database dump as a named snapshot.
            3. Branch your server repository and create a dedicated migrate-esx-to-qbcore branch.
            4. Write a runbook. Include commands to start and stop the staging server, restore DB, and run health checks.

            ---

            Step 2. Build a Clean QBCore Base

            1. Deploy a fresh QBCore base to staging.
            2. Keep only essentials enabled. Disable jobs, inventories, and custom scripts until after DB migration.
            3. Install and start these resources first

               1. qb-core

               2. qb-vehicles or your preferred replacements

               3. oxmysql

               4. ox_lib

                  ---

                  Step 3. Replace mysql-async with oxmysql

                  If any remaining ESX scripts still use MySQL.Async, convert the calls to oxmysql. Use simple find and replace with verification.

                  Common conversions

                        -- ESX mysql-async
                        MySQL.Async.fetchAll('SELECT * FROM users WHERE identifier = @id', {['@id'] = identifier}, function(rows)
                          -- ...
                        end)
                        
                        -- QBCore oxmysql
                        local rows = MySQL.query.await('SELECT * FROM players WHERE citizenid = ?', { citizenid })
                        -- rows is a Lua table; handle nil and length checks directly
                        
                        -- ESX scalar example
                        MySQL.Async.fetchScalar('SELECT COUNT(1) FROM owned_vehicles', {}, function(count)
                          -- ...
                        end)
                        
                        -- oxmysql scalar
                        local count = MySQL.scalar.await('SELECT COUNT(1) FROM player_vehicles')
                        
                        -- ESX insert
                        MySQL.Async.execute('INSERT INTO addon_account VALUES (@owner, @name, @money)', {
                          ['@owner'] = identifier, ['@name'] = name, ['@money'] = money
                        })
                        
                        -- oxmysql insert
                        MySQL.prepare.await('INSERT INTO player_accounts (citizenid, name, amount) VALUES (?, ?, ?)', { citizenid, name, amount })

Notes

1. Prefer query.await, scalar.await, and prepare.await for clean flow.
2. Use prepared statements for write operations.

---

Step 4. Map ESX Data Structures to QBCore

You will move player identities and owned entities. Use this reference to map tables.	ESX table	Key column	QBCore table
Key column	Notes	users	identifier
players	citizenid	Convert identifiers and create citizenid for each row	owned_vehicles
owner	player_vehicles	citizenid	Convert plate casing and JSON payloads
datastore_data	owner	player_metadata	citizenid
If you store JSON, merge carefully	addon_account_data	owner	player_accounts
citizenid	Map account names to QBCore banking or cash	addon_inventory_items	owner
player_inventories	citizenid	If you move to ox_inventory, migrate separately	You can keep custom tables. Adjust only foreign keys that reference ESX identifiers.

---

Step 5. Stabilize Identifiers

                        ESX often stores a [CFX identifier](https://docs.fivem.net/docs/scripting-reference/runtimes/lua/functions/GetPlayerIdentifiers/) like `license:xxxx` or historical `steam:xxxx`. QBCore uses `citizenid` as the stable player key and keeps the runtime identifiers for authentication only.

You will

1. Create a citizenid for every player.
2. Link legacy identifiers to the new record.
3. Keep a lookup table for support and audits.

SQL bootstrap

Run this on a copy of your ESX database to prepare QBCore tables.

                        -- 1) Create players table if missing. Adjust to your QBCore schema.
                        CREATE TABLE IF NOT EXISTS players (
                          citizenid VARCHAR(11) PRIMARY KEY,
                          license VARCHAR(64) UNIQUE,

identifiers JSON NOT NULL,

                          name VARCHAR(64),

charinfo JSON NOT NULL, metadata JSON NOT NULL, money JSON NOT NULL, job JSON NOT NULL,

                          position VARCHAR(128) DEFAULT NULL,

created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP

                        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
                        
                        -- 2) Helper function equivalent in SQL using a deterministic generator would be complex.
                        -- Instead, stage the mapping in a separate table and generate citizenid in Lua.
                        CREATE TABLE IF NOT EXISTS legacy_identifier_map (
                          license VARCHAR(64) PRIMARY KEY,
                          steam VARCHAR(64) NULL,
                          fivem VARCHAR(64) NULL,
                          discord VARCHAR(64) NULL,
                          xbl VARCHAR(64) NULL,
                          liveid VARCHAR(64) NULL,
                          citizenid VARCHAR(11) UNIQUE
                        );
                        
                        -- 3) Seed the mapping from ESX users
                        INSERT INTO legacy_identifier_map (license)
                        SELECT DISTINCT REPLACE(identifier, 'identifier:', '')

FROM users

                        WHERE identifier LIKE 'license:%' OR identifier LIKE 'steam:%';

Generate citizenid and insert players in Lua

Run once on staging. Back up first.

                        -- server/migrate_identifiers.lua
                        local QBCore = exports['qb-core']:GetCoreObject()
                        
                        local function generateCitizenId()
                          local charset = {}
                          for c = 65, 90 do table.insert(charset, string.char(c)) end
                          for n = 48, 57 do table.insert(charset, string.char(n)) end
                          math.randomseed(GetGameTimer())
                          local id = {}
                          for i = 1, 11 do id[i] = charset[math.random(1, #charset)] end
                          return table.concat(id)
                        end
                        
                        local rows = MySQL.query.await('SELECT license FROM legacy_identifier_map WHERE citizenid IS NULL')
                        for _, r in ipairs(rows) do
                          local citizenid = generateCitizenId()
                          MySQL.prepare.await('UPDATE legacy_identifier_map SET citizenid = ? WHERE license = ?', { citizenid, r.license })
                        end
                        
                        -- Build players from ESX users
                        local users = MySQL.query.await([[SELECT u.identifier, u.firstname, u.lastname, u.dateofbirth, u.sex, u.height
                                                          FROM users u]])
                        for _, u in ipairs(users) do
                          local license = u.identifier
                          local map = MySQL.single.await('SELECT citizenid FROM legacy_identifier_map WHERE license = ?', { license })
                          if map and map.citizenid then
                            local name = string.format('%s %s', u.firstname or 'John', u.lastname or 'Doe')
                            local charinfo = json.encode({ firstname = u.firstname, lastname = u.lastname, birthdate = u.dateofbirth, gender = u.sex, height = u.height })
                            local metadata = json.encode({ hunger = 100, thirst = 100 })
                            local money = json.encode({ cash = 0, bank = 0, crypto = 0 })
                            local job = json.encode({ name = 'unemployed', label = 'Unemployed', grade = { name = '0', level = 0 }})
                        
                            MySQL.prepare.await('INSERT IGNORE INTO players (citizenid, license, identifiers, name, charinfo, metadata, money, job) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', {

map.citizenid, license,

                              json.encode({ license = license }),

name, charinfo, metadata, money, job

                            })
                          end
                        end
                        print('Identifier migration finished')

Move owned vehicles

                        INSERT IGNORE INTO player_vehicles (citizenid, plate, vehicle, garage, state)
                        SELECT m.citizenid,
                               UPPER(JSON_UNQUOTE(JSON_EXTRACT(v.vehicle, '$.plate'))),

v.vehicle,

                               'legion',

1 FROM owned_vehicles v

                        JOIN legacy_identifier_map m ON m.license = v.owner;

Validate random samples in game. Verify plate formats and garages.

---

Step 6. Port ESX Code to QBCore with ox_lib

Replace the ESX runtime API with QBCore equivalents. Use ox_lib for callbacks and notifications.

Player object

                        -- ESX
                        local xPlayer = ESX.GetPlayerFromId(src)
                        xPlayer.addMoney(100)
                        
                        -- QBCore
                        local Player = QBCore.Functions.GetPlayer(src)
                        Player.Functions.AddMoney('cash', 100)

Jobs

                        -- ESX job check
                        if xPlayer.getJob().name == 'police' then
                          -- ...
                        end
                        
                        -- QBCore job check
                        local job = Player.PlayerData.job
                        if job and job.name == 'police' then
                          -- ...
                        end

Callbacks and UI

                        -- ESX server callback
                        ESX.RegisterServerCallback('resource:getData', function(source, cb)
                          cb({ ok = true })
                        end)
                        
                        -- ox_lib callback
                        lib.callback.register('resource:getData', function(source)
                          return { ok = true }
                        end)
                        
                        -- Notification
                        lib.notify(source, { title = 'Job', description = 'Promotion granted', type = 'success' })

Commands

                        -- ESX
                        RegisterCommand('pay', function(src, args)
                          local amount = tonumber(args[1]) or 0
                          xPlayer.removeMoney(amount)
                        end)
                        
                        -- QBCore with permissions
                        QBCore.Commands.Add('pay', 'Pay cash', {{name = 'amount', help = 'Amount'}}, false, function(src, args)
                          local amount = tonumber(args[1]) or 0
                          local Player = QBCore.Functions.GetPlayer(src)
                          Player.Functions.RemoveMoney('cash', amount)
                        end)

---

Step 7. Inventory and Items

If you move from es_extended inventories to qb-inventory or ox_inventory, treat this as a separate sub‑migration.

1. Freeze item additions.
2. Export the item master list.
3. Map item names one to one.
4. Migrate player inventories in batches. Validate stack sizes and weights.

Example item mapping CSV

esx_name,qb_name,notes bread,bread, water,water, lockpick,lockpick,

---

Step 8. Test and Roll Out

1. Unit tests
   1. Test identifier lookups for a random set of players.
   2. Test money transfers, job changes, and vehicle ownership.
   3. Gameplay tests
      1. Spawn players with old ESX identifiers and confirm auto mapping.
      2. Run a police duty flow, a store robbery, and a vehicle purchase.
      3. Performance tests
         1. Use resmon to watch CPU and memory.
         2. Confirm DB query counts dropped after oxmysql conversion.
         3. Rollout plan

            1. Move staging DB to production during a maintenance window.

            2. Announce a 60 minute downtime.

            3. Monitor logs for missing identifiers and foreign key errors.

               ---

               Troubleshooting

               1. Duplicated citizens
                  1. Cause. Running the migration twice.
                  2. Fix. Enforce unique keys on citizenid and use INSERT IGNORE during seeding.
                  3. Missing vehicles
                     1. Cause. Owner key mismatch between owned_vehicles.owner and legacy_identifier_map.license.
                     2. Fix. Normalize owner values and re‑run the vehicle insert for the affected plates.
                     3. Players spawn without inventory
                        1. Cause. Inventory migration skipped.
                        2. Fix. Rebuild the inventory mapping and re‑import.
                        3. Scripts fail with MySQL.Async not found

                           1. Cause. Script still depends on mysql-async.

                           2. Fix. Replace calls with oxmysql and remove mysql-async from the server.

                              ---

                              Cutover Checklist

                              1. Back up production database with a timestamp.
                              2. Stop the server and lock player joins.
                              3. Restore the final staging dump to production.
                              4. Deploy QBCore build with qb-core, oxmysql, ox_lib first in the ensure order.
                              5. Run the identifier seeding script once.
                              6. Enable converted scripts only when their queries are on oxmysql.
                              7. Reopen the server and watch logs for 30 minutes.
                              8. Post a rollback plan if critical errors appear.

                              ---

                              Appendix A. Example fxmanifest for migration helper

                              fx_version 'cerulean'

                                                                game 'gta5'
                                                                
                                                                lua54 'yes'
                                                                
                                                                server_scripts {
                                                                  '@oxmysql/lib/MySQL.lua',
                                                                  '@ox_lib/init.lua',
                                                                  'server/migrate_identifiers.lua'
                                                                }

---

Appendix B. Safe JSON helpers

                                                                local function safeDecode(jsonStr, fallback)
                                                                  if type(jsonStr) ~= 'string' or jsonStr == '' then return fallback end
                                                                  local ok, result = pcall(json.decode, jsonStr)
                                                                  if not ok then return fallback end
                                                                  return result
                                                                end

---

What you achieved

1. Stable player records keyed by citizenid.
2. A clean oxmysql layer with prepared statements and awaits.
3. ESX code ported to QBCore using ox_lib callbacks and utilities.
4. A versioned plan you can repeat for future servers.

---

Useful links inside your site

1. Framework conversion hub. https://vertexmods.com/blog/converting-fivem-scripts
2. MySQL Async to oxmysql guide. https://vertexmods.com/blog/mysql-async-to-oxmysql
3. SQL identifiers migration. https://vertexmods.com/blog/sql-identifiers-migration
4. Adapter patterns for script ports. https://vertexmods.com/blog/adapter-patterns
5. QBCore install quickstart. https://vertexmods.com/blog/how-to-install-qbcore
6. Script conversion checklist. https://vertexmods.com/blog/converting-fivem-scripts
7. QBOX with ox stack overview. https://vertexmods.com/blog/qbox-ox-stack
8. Resmon and performance. https://vertexmods.com/blog/how-to-use-resmon-in-fivem-optimize-resources

External references

1. QBCore framework
2. oxmysql documentation.
3. ox_lib documentation.
4. CFX.re identifiers reference.