{"id":199542,"date":"2025-10-02T15:33:52","date_gmt":"2025-10-02T13:33:52","guid":{"rendered":"https:\/\/fivemx.com\/?p=199542"},"modified":"2026-08-10T07:53:36","modified_gmt":"2026-08-10T05:53:36","slug":"how-to-migrate-esx-qbcore","status":"publish","type":"post","link":"https:\/\/fivemx.com\/es\/how-to-migrate-esx-qbcore\/","title":{"rendered":"C\u00f3mo Migrar ESX \u2192 QBCore de la Manera Correcta"},"content":{"rendered":"\n

You want a clean switch from ESX to QBCore without losing data or breaking core systems. Follow this plan. You will finish with stable identifiers, oxmysql queries, and ox_lib powered code.<\/p>\n\n\n\n

Goal: move your server from ESX to QBCore with minimal downtime.<\/strong><\/p>\n\n\n\n

\n\n\n\n

Prerequisites<\/h2>\n\n\n\n
    \n
  1. Tools\n
      \n
    1. GIT and a separate branch for the migration.<\/li>\n\n\n\n
    2. MariaDB or MySQL 8 with full backups enabled.<\/li>\n\n\n\n
    3. A staging server that mirrors production.<\/li>\n<\/ol>\n<\/li>\n\n\n\n
    4. Server artifacts\n
        \n
      1. FXServer<\/a> updated to the same build as production.<\/li>\n\n\n\n
      2. QBCore<\/a> base framework and default resources.<\/li>\n<\/ol>\n<\/li>\n\n\n\n
      3. Libraries you will use\n
          \n
        1. oxmysql<\/code> for database.<\/li>\n\n\n\n
        2. ox_lib<\/code> for callbacks, UI helpers, and utility wrappers.<\/li>\n<\/ol>\n<\/li>\n<\/ol>\n\n\n\n
          \n\n\n\n

          Step 1. Make a Plan and a Rollback Point<\/h2>\n\n\n\n
            \n
          1. Freeze production changes. Stop new script installs and DB writes not required for testing.<\/li>\n\n\n\n
          2. Back up your entire database dump as a named snapshot.<\/li>\n\n\n\n
          3. Branch your server repository and create a dedicated migrate-esx-to-qbcore<\/code> branch.<\/li>\n\n\n\n
          4. Write a runbook. Include commands to start and stop the staging server, restore DB, and run health checks.<\/li>\n<\/ol>\n\n\n\n
            \n\n\n\n

            Step 2. Build a Clean QBCore Base<\/h2>\n\n\n\n
              \n
            1. Deploy a fresh QBCore base to staging.<\/li>\n\n\n\n
            2. Keep only essentials enabled. Disable jobs, inventories, and custom scripts until after DB migration.<\/li>\n\n\n\n
            3. Install and start these resources first\n
                \n
              1. qb-core<\/code><\/li>\n\n\n\n
              2. qb-vehicles<\/code> or your preferred replacements<\/li>\n\n\n\n
              3. oxmysql<\/code><\/li>\n\n\n\n
              4. ox_lib<\/code><\/li>\n<\/ol>\n<\/li>\n<\/ol>\n\n\n\n
                \n\n\n\n

                Step 3. Replace mysql-async with oxmysql<\/h2>\n\n\n\n

                If any remaining ESX scripts still use MySQL.Async<\/code>, convert the calls to oxmysql. Use simple find and replace with verification.<\/p>\n\n\n\n

                Common conversions<\/h3>\n\n\n\n
                -- ESX mysql-async\nMySQL.Async.fetchAll('SELECT * FROM users WHERE identifier = @id', {['@id'] = identifier}, function(rows)\n -- ...\nend)\n<\/pre>\n\n\n\n
                -- QBCore oxmysql\nlocal rows = MySQL.query.await('SELECT * FROM players WHERE citizenid = ?', { citizenid })\n-- rows is a Lua table; handle nil and length checks directly\n<\/pre>\n\n\n\n
                -- ESX scalar example\nMySQL.Async.fetchScalar('SELECT COUNT(1) FROM owned_vehicles', {}, function(count)\n -- ...\nend)\n<\/pre>\n\n\n\n
                -- oxmysql scalar\nlocal count = MySQL.scalar.await('SELECT COUNT(1) FROM player_vehicles')\n<\/pre>\n\n\n\n
                -- ESX insert\nMySQL.Async.execute('INSERT INTO addon_account VALUES (@owner, @name, @money)', {\n ['@owner'] = identifier, ['@name'] = name, ['@money'] = money\n})\n<\/pre>\n\n\n\n
                -- oxmysql insert\nMySQL.prepare.await('INSERT INTO player_accounts (citizenid, name, amount) VALUES (?, ?, ?)', { citizenid, name, amount })\n<\/pre>\n\n\n\n
                Notes<\/p>\n\n\n\n
                  \n
                1. Prefer query.await<\/code>, scalar.await<\/code>, and prepare.await<\/code> for clean flow.<\/li>\n\n\n\n
                2. Use prepared statements for write operations.<\/li>\n<\/ol>\n\n\n\n
                  \n\n\n\n
                  Step 4. Map ESX Data Structures to QBCore<\/h2>\n\n\n\n
                  You will move player identities and owned entities. Use this reference to map tables.<\/p>\n\n\n\n
                  ESX table<\/th>Key column<\/th>QBCore table<\/th>Key column<\/th>Notes<\/th><\/tr><\/thead>
                  users<\/code><\/td>identifier<\/code><\/td>players<\/code><\/td>citizenid<\/code><\/td>Convert identifiers and create citizenid<\/code> for each row<\/td><\/tr>
                  owned_vehicles<\/code><\/td>owner<\/code><\/td>player_vehicles<\/code><\/td>citizenid<\/code><\/td>Convert plate casing and JSON payloads<\/td><\/tr>
                  datastore_data<\/code><\/td>owner<\/code><\/td>player_metadata<\/code><\/td>citizenid<\/code><\/td>If you store JSON, merge carefully<\/td><\/tr>
                  addon_account_data<\/code><\/td>owner<\/code><\/td>player_accounts<\/code><\/td>citizenid<\/code><\/td>Map account names to QBCore banking or cash<\/td><\/tr>
                  addon_inventory_items<\/code><\/td>owner<\/code><\/td>player_inventories<\/code><\/td>citizenid<\/code><\/td>If you move to ox_inventory<\/code>, migrate separately<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                  You can keep custom tables. Adjust only foreign keys that reference ESX identifiers.<\/p>\n\n\n\n
                  \n\n\n\n
                  Step 5. Stabilize Identifiers<\/h2>\n\n\n\n
                  ESX often stores a CFX identifier like license:xxxx<\/code> or historical steam:xxxx<\/code>. QBCore uses citizenid<\/code> as the stable player key and keeps the runtime identifiers for authentication only.<\/p>\n\n\n\n
                  You will<\/p>\n\n\n\n
                    \n
                  1. Create a citizenid<\/code> for every player.<\/li>\n\n\n\n
                  2. Link legacy identifiers to the new record.<\/li>\n\n\n\n
                  3. Keep a lookup table for support and audits.<\/li>\n<\/ol>\n\n\n\n
                    SQL bootstrap<\/h3>\n\n\n\n
                    Run this on a copy of your ESX database to prepare QBCore tables.<\/p>\n\n\n\n
                    -- 1) Create players table if missing. Adjust to your QBCore schema.\nCREATE TABLE IF NOT EXISTS players (\n citizenid VARCHAR(11) PRIMARY KEY,\n license VARCHAR(64) UNIQUE,\n identifiers JSON NOT NULL,\n name VARCHAR(64),\n charinfo JSON NOT NULL,\n metadata JSON NOT NULL,\n money JSON NOT NULL,\n job JSON NOT NULL,\n position VARCHAR(128) DEFAULT NULL,\n created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;\n\n-- 2) Helper function equivalent in SQL using a deterministic generator would be complex.\n-- Instead, stage the mapping in a separate table and generate citizenid in Lua.\nCREATE TABLE IF NOT EXISTS legacy_identifier_map (\n license VARCHAR(64) PRIMARY KEY,\n steam VARCHAR(64) NULL,\n fivem VARCHAR(64) NULL,\n discord VARCHAR(64) NULL,\n xbl VARCHAR(64) NULL,\n liveid VARCHAR(64) NULL,\n citizenid VARCHAR(11) UNIQUE\n);\n\n-- 3) Seed the mapping from ESX users\nINSERT INTO legacy_identifier_map (license)\nSELECT DISTINCT REPLACE(identifier, 'identifier:', '')\nFROM users\nWHERE identifier LIKE 'license:%' OR identifier LIKE 'steam:%';\n<\/pre>\n\n\n\n
                    Generate citizenid and insert players in Lua<\/h3>\n\n\n\n
                    Run once on staging. Back up first.<\/p>\n\n\n\n
                    -- server\/migrate_identifiers.lua\nlocal QBCore = exports['qb-core']:GetCoreObject()\n\nlocal function generateCitizenId()\n local charset = {}\n for c = 65, 90 do table.insert(charset, string.char(c)) end\n for n = 48, 57 do table.insert(charset, string.char(n)) end\n math.randomseed(GetGameTimer())\n local id = {}\n for i = 1, 11 do id[i] = charset[math.random(1, #charset)] end\n return table.concat(id)\nend\n\nlocal rows = MySQL.query.await('SELECT license FROM legacy_identifier_map WHERE citizenid IS NULL')\nfor _, r in ipairs(rows) do\n local citizenid = generateCitizenId()\n MySQL.prepare.await('UPDATE legacy_identifier_map SET citizenid = ? WHERE license = ?', { citizenid, r.license })\nend\n\n-- Build players from ESX users\nlocal users = MySQL.query.await([[SELECT u.identifier, u.firstname, u.lastname, u.dateofbirth, u.sex, u.height\n FROM users u]])\nfor _, u in ipairs(users) do\n local license = u.identifier\n local map = MySQL.single.await('SELECT citizenid FROM legacy_identifier_map WHERE license = ?', { license })\n if map and map.citizenid then\n local name = string.format('%s %s', u.firstname or 'John', u.lastname or 'Doe')\n local charinfo = json.encode({ firstname = u.firstname, lastname = u.lastname, birthdate = u.dateofbirth, gender = u.sex, height = u.height })\n local metadata = json.encode({ hunger = 100, thirst = 100 })\n local money = json.encode({ cash = 0, bank = 0, crypto = 0 })\n local job = json.encode({ name = 'unemployed', label = 'Unemployed', grade = { name = '0', level = 0 }})\n\n MySQL.prepare.await('INSERT IGNORE INTO players (citizenid, license, identifiers, name, charinfo, metadata, money, job) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', {\n map.citizenid,\n license,\n json.encode({ license = license }),\n name,\n charinfo,\n metadata,\n money,\n job\n })\n end\nend\nprint('Identifier migration finished')\n<\/pre>\n\n\n\n
                    Move owned vehicles<\/h3>\n\n\n\n
                    INSERT IGNORE INTO player_vehicles (citizenid, plate, vehicle, garage, state)\nSELECT m.citizenid,\n UPPER(JSON_UNQUOTE(JSON_EXTRACT(v.vehicle, '$.plate'))),\n v.vehicle,\n 'legion',\n 1\nFROM owned_vehicles v\nJOIN legacy_identifier_map m ON m.license = v.owner;\n<\/pre>\n\n\n\n
                    Validate random samples in game. Verify plate formats and garages.<\/p>\n\n\n\n
                    \n\n\n\n
                    Step 6. Port ESX Code to QBCore with ox_lib<\/h2>\n\n\n\n
                    Replace the ESX runtime API with QBCore equivalents. Use ox_lib for callbacks and notifications.<\/p>\n\n\n\n
                    Player object<\/h3>\n\n\n\n
                    -- ESX\nlocal xPlayer = ESX.GetPlayerFromId(src)\nxPlayer.addMoney(100)\n<\/pre>\n\n\n\n
                    -- QBCore\nlocal Player = QBCore.Functions.GetPlayer(src)\nPlayer.Functions.AddMoney('cash', 100)\n<\/pre>\n\n\n\n
                    Jobs<\/h3>\n\n\n\n
                    -- ESX job check\nif xPlayer.getJob().name == 'police' then\n -- ...\nend\n<\/pre>\n\n\n\n
                    -- QBCore job check\nlocal job = Player.PlayerData.job\nif job and job.name == 'police' then\n -- ...\nend\n<\/pre>\n\n\n\n
                    Callbacks and UI<\/h3>\n\n\n\n
                    -- ESX server callback\nESX.RegisterServerCallback('resource:getData', function(source, cb)\n cb({ ok = true })\nend)\n<\/pre>\n\n\n\n
                    -- ox_lib callback\nlib.callback.register('resource:getData', function(source)\n return { ok = true }\nend)\n<\/pre>\n\n\n\n
                    -- Notification\nlib.notify(source, { title = 'Job', description = 'Promotion granted', type = 'success' })\n<\/pre>\n\n\n\n
                    Commands<\/h3>\n\n\n\n
                    -- ESX\nRegisterCommand('pay', function(src, args)\n local amount = tonumber(args[1]) or 0\n xPlayer.removeMoney(amount)\nend)\n<\/pre>\n\n\n\n
                    -- QBCore with permissions\nQBCore.Commands.Add('pay', 'Pay cash', {{name = 'amount', help = 'Amount'}}, false, function(src, args)\n local amount = tonumber(args[1]) or 0\n local Player = QBCore.Functions.GetPlayer(src)\n Player.Functions.RemoveMoney('cash', amount)\nend)\n<\/pre>\n\n\n\n
                    \n\n\n\n
                    Step 7. Inventory and Items<\/h2>\n\n\n\n
                    If you move from es_extended<\/code> inventories to qb-inventory<\/code> or ox_inventory<\/code>, treat this as a separate sub\u2011migration.<\/p>\n\n\n\n
                      \n
                    1. Freeze item additions.<\/li>\n\n\n\n
                    2. Export the item master list.<\/li>\n\n\n\n
                    3. Map item names one to one.<\/li>\n\n\n\n
                    4. Migrate player inventories in batches. Validate stack sizes and weights.<\/li>\n<\/ol>\n\n\n\n
                      Example item mapping CSV<\/p>\n\n\n\n
                      esx_name,qb_name,notes\nbread,bread,\nwater,water,\nlockpick,lockpick,\n<\/pre>\n\n\n\n
                      \n\n\n\n
                      Step 8. Test and Roll Out<\/h2>\n\n\n\n
                        \n
                      1. Unit tests\n
                          \n
                        1. Test identifier lookups for a random set of players.<\/li>\n\n\n\n
                        2. Test money transfers, job changes, and vehicle ownership.<\/li>\n<\/ol>\n<\/li>\n\n\n\n
                        3. Gameplay tests\n
                            \n
                          1. Spawn players with old ESX identifiers and confirm auto mapping.<\/li>\n\n\n\n
                          2. Run a police duty flow, a store robbery, and a vehicle purchase.<\/li>\n<\/ol>\n<\/li>\n\n\n\n
                          3. Performance tests\n
                              \n
                            1. Use resmon<\/code> to watch CPU and memory.<\/li>\n\n\n\n
                            2. Confirm DB query counts dropped after oxmysql conversion.<\/li>\n<\/ol>\n<\/li>\n\n\n\n
                            3. Rollout plan\n
                                \n
                              1. Move staging DB to production during a maintenance window.<\/li>\n\n\n\n
                              2. Announce a 60 minute downtime.<\/li>\n\n\n\n
                              3. Monitor logs for missing identifiers and foreign key errors.<\/li>\n<\/ol>\n<\/li>\n<\/ol>\n\n\n\n
                                \n\n\n\n
                                Troubleshooting<\/h2>\n\n\n\n
                                  \n
                                1. Duplicated citizens\n
                                    \n
                                  1. Cause. Running the migration twice.<\/li>\n\n\n\n
                                  2. Fix. Enforce unique keys on citizenid<\/code> and use INSERT IGNORE<\/code> during seeding.<\/li>\n<\/ol>\n<\/li>\n\n\n\n
                                  3. Missing vehicles\n
                                      \n
                                    1. Cause. Owner key mismatch between owned_vehicles.owner<\/code> and legacy_identifier_map.license<\/code>.<\/li>\n\n\n\n
                                    2. Fix. Normalize owner values and re\u2011run the vehicle insert for the affected plates.<\/li>\n<\/ol>\n<\/li>\n\n\n\n
                                    3. Players spawn without inventory\n
                                        \n
                                      1. Cause. Inventory migration skipped.<\/li>\n\n\n\n
                                      2. Fix. Rebuild the inventory mapping and re\u2011import.<\/li>\n<\/ol>\n<\/li>\n\n\n\n
                                      3. Scripts fail with MySQL.Async<\/code> not found\n
                                          \n
                                        1. Cause. Script still depends on mysql-async.<\/li>\n\n\n\n
                                        2. Fix. Replace calls with oxmysql and remove mysql-async from the server.<\/li>\n<\/ol>\n<\/li>\n<\/ol>\n\n\n\n
                                          \n\n\n\n
                                          Cutover Checklist<\/h2>\n\n\n\n
                                            \n
                                          1. Back up production database with a timestamp.<\/li>\n\n\n\n
                                          2. Stop the server and lock player joins.<\/li>\n\n\n\n
                                          3. Restore the final staging dump to production.<\/li>\n\n\n\n
                                          4. Deploy QBCore build with qb-core<\/code>, oxmysql<\/code>, ox_lib<\/code> first in the ensure order.<\/li>\n\n\n\n
                                          5. Run the identifier seeding script once.<\/li>\n\n\n\n
                                          6. Enable converted scripts only when their queries are on oxmysql.<\/li>\n\n\n\n
                                          7. Reopen the server and watch logs for 30 minutes.<\/li>\n\n\n\n
                                          8. Post a rollback plan if critical errors appear.<\/li>\n<\/ol>\n\n\n\n
                                            \n\n\n\n
                                            Appendix A. Example fxmanifest for migration helper<\/h2>\n\n\n\n
                                            fx_version 'cerulean'\ngame 'gta5'\n\nlua54 'yes'\n\nserver_scripts {\n '@oxmysql\/lib\/MySQL.lua',\n '@ox_lib\/init.lua',\n 'server\/migrate_identifiers.lua'\n}\n<\/pre>\n\n\n\n
                                            \n\n\n\n
                                            Appendix B. Safe JSON helpers<\/h2>\n\n\n\n
                                            local function safeDecode(jsonStr, fallback)\n if type(jsonStr) ~= 'string' or jsonStr == '' then return fallback end\n local ok, result = pcall(json.decode, jsonStr)\n if not ok then return fallback end\n return result\nend\n<\/pre>\n\n\n\n
                                            \n\n\n\n
                                            What you achieved<\/h2>\n\n\n\n
                                              \n
                                            1. Stable player records keyed by citizenid<\/code>.<\/li>\n\n\n\n
                                            2. A clean oxmysql layer with prepared statements and awaits.<\/li>\n\n\n\n
                                            3. ESX code ported to QBCore using ox_lib callbacks and utilities.<\/li>\n\n\n\n
                                            4. A versioned plan you can repeat for future servers.<\/li>\n<\/ol>\n\n\n\n
                                              \n\n\n\n