# 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](https://esx-fivem.com/).
Confirm the exact source APIs and database schema against your installed version of
[ESX Core](https://github.com/esx-framework/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](/docs/migration/tools/backup-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](/docs/database/core-schema) 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:

```sql
-- 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:

1. Validate account/character mapping and target field lengths.
2. Map money accounts without resetting balances to sample defaults.
3. Resolve the target job and grade; flag missing definitions rather than silently demoting players.
4. Build `job.grade` as a table with numeric `level`, name, payment and boss fields matching the target.
5. Map charinfo, gang, position and metadata using the selected resource versions.
6. 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](/docs/troubleshooting/inventory-updates).

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

```lua
-- 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:

```sql
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](/docs/migration/resource-updates).

## Sources

- [Target login ownership check and Player validation](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/player.lua)
- [Target callbacks and disconnect handlers](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/events.lua)

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.
