SQL & Identifiers Migration: steam/license to citizenid
1. Freeze writes during migration (stop the game server + any external bots touching DB). 2. Full backup and a dump of table structures. Store both with timestamps. 3.
Introduction to Use‑case: You’re moving from ESX to QBCore or QBOX
Use‑case: You’re moving from ESX to QBCore or QBOX (qbx_core) and need a clean, auditable migration of player identifiers and balances. This guide gives you production‑ready SQL, a reversible plan, and validation steps.
This guide is part of our , where we compare ESX, QBCore, and QBOX in depth and help you choose the right one.
Related reads:
- Adapter Patterns: ESX↔QBCore↔QBOX (Exports, Events & Player Models) —
- Converting – ESX, QBCore, QBOX (Framework Guide) — (Pillar)
What changes between ESX and QBCore/QBOX
| Topic | ESX (common) | QBCore / QBOX (common) | |
Häufig gestellte Fragen
When migrating from ESX to QBCore/QBOX, why is it necessary to convert identifiers?
ESX typically uses `identifier` (like `license:xxx` or `steam:xxx`) as the primary player key, while QBCore and QBOX utilize `citizenid`, a server-generated token. This fundamental difference requires a migration process to ensure player data, like balances and vehicle ownership, is correctly associated with the new identifier system in the target framework. Failing to migrate identifiers will result in loss of progress and broken associations within the game.
What are the critical 'golden rules' to follow when performing the SQL migration?
Before initiating the SQL migration, it's essential to freeze all write operations to the database by stopping the game server and any external bots. Next, perform a complete database backup accompanied by a dump of table structures, storing both with timestamps for easy restoration. Where possible, execute operations within transactions per table to maintain data integrity, and make sure steps are idempotent (repeatable without adverse effects). Lastly, validate the data at each step. These precautions are important to minimize data loss and ensure a smooth transition.
Besides the player identifier, what other key data structures require migration when switching from ESX to QBCore/QBOX, and how do their structures differ?
Aside from player identifiers, the money model and vehicle ownership records require migration. ESX commonly uses separate accounts (cash/bank/black_money) stored as JSON or in separate `user_accounts` rows. QBCore/QBOX commonly store a single `money` JSON on the `players` table (e.g., `{ "cash": 0, "bank": 5000 }`). For vehicles, ESX's `owned_vehicles.owner` refers to the ESX `identifier`, while QBCore/QBOX's `player_vehicles.citizenid` column stores the new citizen ID.
