Skip to Content
QBCore docs – powered by Nextra 4
MigrationQBCore v1 to v2 Migration Guide

QBCore v1 to v2 Migration Guide

This guide will help you migrate your QBCore server from version 1.x to version 2.x. This is a major version upgrade with significant changes and improvements.

Pre-Migration Checklist

Before starting the migration, ensure you have:

  • Complete server backup (files, database, configurations)
  • List of all custom resources and their versions
  • Database backup with verified restore capability
  • Test server environment for migration testing
  • Scheduled maintenance window for production migration
  • Rollback plan documented and tested

Major Changes in v2

Framework Architecture Changes

⚠️ Breaking Changes

QBCore v2 introduces several breaking changes. Custom resources will likely need updates.

1. Player Object Restructure

Before (v1):

local Player = QBCore.Functions.GetPlayer(source)
local playerData = Player.PlayerData
local job = playerData.job.name
local money = playerData.money['cash']

After (v2):

local Player = QBCore.Functions.GetPlayer(source)
local citizenId = Player.PlayerData.citizenid
local job = Player.PlayerData.job.name
local money = Player.Functions.GetMoney('cash')

2. Event System Updates

Before (v1):

-- Old event names
TriggerEvent('QBCore:Server:PlayerLoaded', source)
TriggerClientEvent('QBCore:Client:OnPlayerLoaded', source)

After (v2):

-- New event names with better organization
TriggerEvent('QBCore:Server:OnPlayerLoaded', source)
TriggerClientEvent('QBCore:Client:OnPlayerLoaded', source)

3. Database Schema Changes

New required columns in players table:

  • phone_number VARCHAR(20)
  • last_updated TIMESTAMP
  • metadata LONGTEXT (JSON format)

Resource Structure Changes

New File Organization

resources/[qb]/
├── qb-core/
│   ├── client/
│   ├── server/
│   ├── shared/
│   └── config/
├── qb-multicharacter/
└── [other resources]/

Step-by-Step Migration Process

Phase 1: Preparation

1. Backup Current Installation

# Create backup directory
mkdir -p /backups/qbcore-v1-backup-$(date +%Y%m%d)
 
# Backup server files
cp -r /path/to/server /backups/qbcore-v1-backup-$(date +%Y%m%d)/
 
# Backup database
mysqldump -u username -p database_name > /backups/qbcore-v1-backup-$(date +%Y%m%d)/database.sql

2. Document Current Setup

Create an inventory of:

  • All installed resources
  • Custom modifications
  • Database customizations
  • Server configuration

Phase 2: Test Environment Setup

1. Clone Production Environment

# Set up test server
cp -r /production/server /test/server
mysql -u username -p test_database < production_backup.sql

2. Install QBCore v2

# Remove old qb-core
rm -rf resources/[qb]/qb-core
 
# Clone QBCore v2
git clone -b v2.0 https://github.com/qbcore-framework/qb-core.git resources/[qb]/qb-core

Phase 3: Database Migration

1. Run Database Update Scripts

-- Add new columns to players table
ALTER TABLE `players` 
ADD COLUMN `phone_number` VARCHAR(20) DEFAULT NULL,
ADD COLUMN `last_updated` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
ADD COLUMN `metadata` LONGTEXT DEFAULT NULL;
 
-- Update existing data
UPDATE `players` SET `metadata` = '{}' WHERE `metadata` IS NULL;
 
-- Create new indexes for performance
CREATE INDEX `idx_phone_number` ON `players` (`phone_number`);
CREATE INDEX `idx_last_updated` ON `players` (`last_updated`);

2. Migrate Player Data

-- Convert old money format to new format
UPDATE `players` SET 
`money` = JSON_SET(
  COALESCE(`money`, '{}'),
  '$.cash', COALESCE(JSON_EXTRACT(`money`, '$.cash'), 0),
  '$.bank', COALESCE(JSON_EXTRACT(`money`, '$.bank'), 0),
  '$.crypto', COALESCE(JSON_EXTRACT(`money`, '$.crypto'), 0)
);

Phase 4: Resource Updates

1. Update Core Resources

Essential resources that need updating:

  • qb-multicharacter → v2.0+
  • qb-spawn → v2.0+
  • qb-apartments → v2.0+
  • qb-garages → v2.0+
  • qb-inventory → v2.0+

2. Update Custom Resources

For each custom resource, check for:

Player Data Access:

-- Update calls to player data
-- Old way
local money = Player.PlayerData.money['cash']
 
-- New way  
local money = Player.Functions.GetMoney('cash')

Event Names:

-- Update event registrations
-- Old
RegisterNetEvent('QBCore:PlayerLoaded')
 
-- New
RegisterNetEvent('QBCore:Client:OnPlayerLoaded')

Phase 5: Configuration Updates

1. Update qb-core/config/config.lua

Key configuration changes:

Config = {
    MaxPlayers = 64, -- Updated default
    DefaultSpawn = vector4(-1035.71, -2731.87, 12.86, 0.0), -- New spawn system
    UpdateInterval = 5, -- New setting for data updates
    -- New features
    UseDebug = false,
    ServerCallbacks = {},
    ServerTimezone = 'UTC'
}

2. Update server.cfg

Add new convars:

# QBCore v2 specific settings
set qb_locale "en"
set qb_debug "false"
set qb_update_interval "5000"

# New resource order
ensure qb-core
ensure qb-multicharacter
ensure qb-spawn

Phase 6: Testing

1. Functionality Testing

  • Player login/character creation
  • Money transactions
  • Job system functionality
  • Inventory system
  • Vehicle spawning/garages
  • Housing system
  • All custom resources

2. Performance Testing

  • Server startup time
  • Player count stress test
  • Memory usage monitoring
  • Database performance

3. Integration Testing

  • Resource interdependencies
  • Event system flow
  • API functionality
  • Third-party integrations

Common Migration Issues

Issue 1: Player Data Not Loading

Symptoms: Players lose character data or cannot login

Solution:

-- Check for data format issues
SELECT citizenid, charinfo, money FROM players WHERE JSON_VALID(charinfo) = 0;
 
-- Fix invalid JSON data
UPDATE players SET charinfo = '{}' WHERE JSON_VALID(charinfo) = 0;

Issue 2: Resource Compatibility Errors

Symptoms: Resources throwing errors about missing functions

Solution:

  1. Update all QBCore resources to v2 compatible versions
  2. Check custom resources for deprecated function calls
  3. Update event names to new format

Issue 3: Database Performance Issues

Symptoms: Slow queries, high database load

Solution:

-- Add missing indexes
CREATE INDEX idx_citizenid ON players (citizenid);
CREATE INDEX idx_license ON players (license);
CREATE INDEX idx_job ON players ((JSON_EXTRACT(job, '$.name')));

Rollback Procedure

If migration fails, follow these steps:

1. Stop Server

# Stop FiveM server
pkill -f FXServer

2. Restore Files

# Restore server files
rm -rf /path/to/server
cp -r /backups/qbcore-v1-backup-*/server /path/to/

3. Restore Database

# Restore database
mysql -u username -p database_name < /backups/qbcore-v1-backup-*/database.sql

4. Restart Server

# Start server with original configuration
./run.sh

Post-Migration Checklist

After successful migration:

  • Performance monitoring - Monitor server performance for 24-48 hours
  • Player feedback - Collect feedback from players about any issues
  • Error logging - Monitor server logs for any unexpected errors
  • Backup verification - Ensure new backup system is working
  • Documentation update - Update internal documentation
  • Resource updates - Plan regular resource update schedule

Additional Resources

✅ Migration Complete

Once you’ve completed all steps and verified functionality, your QBCore v2 migration is complete! Remember to update your documentation and inform your community about any new features.

Last updated on
Database Migration ToolsQB-Core Overview