Updated 2026-09-26 · 7 min read
ESX to QBCore Migration Guide
This is a schema-first migration procedure, not a universal SQL converter. The previous generic SQL on this page made unsafe assumptions about identifiers, ESX columns and target inventory tables. Those statements have been withdrawn. No production migration or data conversion was executed as part of this source review.
Why teams migrate
A framework change should serve a concrete resource or maintenance requirement. List the features you need and confirm that suitable implementations work together. A different framework does not automatically make a customized server faster or secure.
For ESX Legacy reference material, see ESX Framework. Confirm the exact source APIs and database schema against your installed version of ESX Core before converting data.
Pre-migration checklist
Record the following before writing a converter:
| Required evidence | What to record |
|---|---|
| Source | ESX commit, multicharacter implementation, inventory and owned-vehicle resources |
| Target | QBCore commit, character system, inventory and vehicle/garage resources |
| Schemas | Actual CREATE TABLE definitions from both isolated databases |
| Identity | Account identifiers, character identifiers and verified ownership mapping |
| Recovery | Tested file/database backup and a matching pre-migration resource snapshot |
| Acceptance | Counts, balances, inventory quantities and end-to-end gameplay checks |
Freeze changes during the final capture. Perform all development and rehearsals on isolated copies, with production credentials removed. See backup and restore.
Framework concept mapping
| Source concept | Target decision |
|---|---|
| Account identifier | Match the actual license used by the target login ownership check |
| Character identifier | Preserve a mapping to a distinct target citizenid |
| Job and grade | Resolve against target Shared.Jobs and build the expected nested grade |
| Cash and bank | Explicitly map account names and amounts; reconcile totals |
| Inventory | Convert through the selected inventory's documented schema/API |
| Owned vehicles | Map ownership through the same character map, not display names |
| Housing, contacts and custom tables | Migrate each dependent owner reference explicitly |
Do not assume an ESX field exists because another installation has it. The target's core schema reference is an orientation aid, not a replacement for inspecting your installed schema.
Phase 1 – Prepare QBCore baseline
Install a clean, isolated target and create test characters through the real character flow. Inspect their stored records and the target resource SQL before building conversion rules.
Run these read-only inspections in the corresponding staging database connections:
-- Source connection: verify the real table name first.
SHOW CREATE TABLE users;
-- Target connection: inspect the installed core table.
SHOW CREATE TABLE players;
SELECT citizenid, license, cid, charinfo, money, job, gang, metadata
FROM players
LIMIT 5;Do not paste real identity data into public support channels. Record source/target commits and
schema hashes in the migration report. Use explicit column lists, not INSERT ... SELECT *.
Phase 2 – Migrate player data
1. Create staging tables
Design a migration-owned mapping table or file before any writes. At minimum, each mapping needs:
- Source account identifier and source character identifier
- Verified target account license and target character slot
- Unique target
citizenid, chosen to fit the installed column and character-generation rules - Conversion status, validation errors and migration batch ID
This is a required data contract, not SQL that assumes your column sizes. Add uniqueness constraints appropriate to your actual character model. More than one character can share an account license.
2. Transform ESX player rows
Never derive a license by removing steam: from an identifier. Different identifier types are
not interchangeable encodings. In the pinned target, login compares the connecting player's actual
license with the stored character license. An incorrect mapping can make characters inaccessible.
Resolve identities from verified account records or a controlled ownership-verification process. Quarantine missing or ambiguous matches; do not guess. Reuse the saved character map on retries so one source character cannot become a second target character.
For each normalized source record, the converter must:
- Validate account/character mapping and target field lengths.
- Map money accounts without resetting balances to sample defaults.
- Resolve the target job and grade; flag missing definitions rather than silently demoting players.
- Build
job.gradeas a table with numericlevel, name, payment and boss fields matching the target. - Map charinfo, gang, position and metadata using the selected resource versions.
- Emit a test-run report before enabling writes.
At the pinned QBCore revision, SetJob stores salary in job.grade.payment. A flat numeric grade
from an old example is not the shape the target Player validation expects.
3. Migrate owned items
Select the inventory adapter first. Do not invent a universal players_inventory table, assume
esx_addoninventory.items exists, or assume that item metadata uses the same field names on both sides.
Test individual and shared storage separately: player stacks, slot numbers, unique items, serials, metadata, stashes, trunks and gloveboxes. Unknown items, conflicting slots and unsupported metadata must be reported for review, not discarded silently. See inventory update boundaries.
Reconcile both per-character quantities and the overall totals. Stack count is not item quantity.
Phase 3 – Convert resources
Event mapping quick reference
| Source behavior | Target behavior to implement |
|---|---|
| Obtain framework object | exports['qb-core']:GetCoreObject() in the correct Lua runtime |
| Find an online player | QBCore.Functions.GetPlayer(source); handle nil |
| Register server callback | QBCore.Functions.CreateCallback(name, handler); reply in every branch |
| Observe constructed Player | Local QBCore:Server:PlayerLoaded hook receives a Player at the pinned revision |
| Observe character unload | Local QBCore:Server:OnPlayerUnload hook receives a server ID |
| Mutate inventory | Use the selected inventory's supported server API |
This maps behavior, not strings for blind search-and-replace. An ESX event and a QBCore method are not interchangeable simply because they both mention items or jobs.
Example conversion
-- server.lua: example read-only callback, not a migration writer.
local QBCore = exports['qb-core']:GetCoreObject()
QBCore.Functions.CreateCallback('docs_migration:getCharacterId', function(src, cb)
local Player = QBCore.Functions.GetPlayer(src)
cb(Player and Player.PlayerData.citizenid or false)
end)Port privileged operations with fresh server authorization. Do not forward old client-supplied prices, roles, ownership claims or reward amounts unchanged.
Phase 4 – Functional testing
Use a fixed test cohort including multiple characters on one account, an offline character, custom jobs, zero balances, unique items and shared storage. Check:
| Test | Required evidence |
|---|---|
| Test run | No writes; every row converted or explicitly quarantined |
| Retry | A repeated batch creates no duplicate character, money or item |
| Identity | Account can access its own characters and cannot access another account's characters |
| Reconciliation | Row counts, money totals and item quantities agree or have approved exceptions |
| Persistence | Login, job change, save, disconnect and reconnect retain the expected data |
| Dependencies | Vehicle, housing, phone and inventory ownership all resolve to the same character map |
| Recovery | Files and database restore together to the pre-migration state |
Useful read-only target checks after a rehearsal:
SELECT citizenid, COUNT(*) AS copies
FROM players
GROUP BY citizenid
HAVING COUNT(*) > 1;
SELECT citizenid, JSON_EXTRACT(job, '$.name') AS job_name,
JSON_EXTRACT(job, '$.grade.level') AS grade_level
FROM players
LIMIT 20;Run totals through the actual mapped account fields. Missing values and malformed JSON should fail validation, not be coerced into an apparently successful total.
Phase 5 – Production rollout
Only after a successful rehearsal: enter maintenance, stop all source writes, capture and verify the final backup, run the reviewed converter, reconcile again, then deploy the matching target resources. Define abort criteria before starting: failed ownership checks, unexplained total differences, unhandled records or essential gameplay failures.
Rollback means restoring both resource versions and the matching database. If players have already created new progress after cutover, a simple restore loses that progress; define that tradeoff and a controlled reconciliation procedure before opening the server.
Post-migration tasks
Retain the mapping, source snapshot and reconciliation report under restricted access. Record exceptions, monitor failed character loads and inventory saves, and remove obsolete converter credentials. Plan subsequent changes through resource updates.
Sources
Your recorded ESX, inventory and character-system commits are additional mandatory sources for an executable conversion. This page deliberately does not claim a universal, tested database writer.
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
