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 complete FiveM frameworks guide, 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) — https://fivemx.com/blog/adapter-patterns
Converting FiveM Scripts – ESX, QBCore, QBOX (Framework Guide) — https://fivemx.com/blog/converting-fivem-scripts/ (Pillar)

What changes between ESX and QBCore/QBOX

Perguntas Frequentes

Ao migrar do ESX para o QBCore/QBOX, por que é necessário converter os identificadores?

O ESX normalmente usa `identifier` (como `license:xxx` ou `steam:xxx`) como chave primária do jogador, enquanto o QBCore e QBOX utilizam `citizenid`, um token gerado pelo servidor. Essa diferença fundamental exige um processo de migração para garantir que os dados do jogador, como saldos e posse de veículos, sejam corretamente associados ao novo sistema de identificadores no framework de destino. Não migrar os identificadores resultará em perda de progresso e associações quebradas no jogo.

Quais são as 'regras de ouro' críticas a seguir ao realizar a migração SQL?

Antes de iniciar a migração SQL, é essencial congelar todas as operações de escrita no banco de dados, parando o servidor do jogo e quaisquer bots externos. Em seguida, faça um backup completo do banco de dados acompanhado de um dump das estruturas das tabelas, armazenando ambos com timestamps para facilitar a restauração. Sempre que possível, execute as operações dentro de transações por tabela para manter a integridade dos dados, e certifique-se de que as etapas sejam idempotentes (repetíveis sem efeitos adversos). Por fim, valide os dados a cada passo. Essas precauções são importantes para minimizar a perda de dados e garantir uma transição suave.

Além do identificador do jogador, quais outras estruturas de dados importantes exigem migração ao trocar do ESX para o QBCore/QBOX, e como suas estruturas diferem?

Além dos identificadores dos jogadores, o modelo de dinheiro e os registros de posse de veículos exigem migração. O ESX comumente usa contas separadas (cash/bank/black_money) armazenadas como JSON ou em linhas separadas de `user_accounts`. O QBCore/QBOX normalmente armazena um único JSON de `money` na tabela `players` (ex.: `{ "cash": 1000, "bank": 5000 }`).

Como posso validar se minha migração SQL do ESX para o QBCore/QBOX foi bem-sucedida?

A validação é uma etapa crítica. Após executar os scripts de migração, faça referências cruzadas dos dados entre as estruturas antigas e novas do banco de dados. Verifique se saldos dos jogadores, posse de veículos e outros dados importantes foram transferidos com precisão e associados ao `citizenid` correto. Você pode usar consultas SQL para comparar dados entre tabelas. Tenha uma conta de teste com dinheiro e veículos para garantir que foram transferidos.

Como funciona a Migração de SQL & Identificadores: steam/license para citizenid? | FiveMX

Caso de uso: Você está migrando do ESX para o QBCore ou QBOX (qbx_core) e precisa de uma migração limpa e auditável dos identificadores e saldos dos jogadores. Este guia fornece SQL pronto para produção, um plano reversível e etapas de validação.