Migrating to v1.9.0

Complete guide for upgrading Dime Skills from v1.7.x to v1.9.0.

CRITICAL: Backup your database before proceeding! This migration modifies your database structure.

Overview

Version 1.9.0 introduces a new normalized database structure and requires migration from the old JSON column format. This guide walks you through the entire process safely.

Time Required: 15-30 minutes
Downtime: Minimal (depends on player count)
Reversible: Yes (with backup)

Prerequisites

Before starting the migration:

Step 1: Backup Everything

Never skip backups! This is your safety net if something goes wrong.

Database Backup

# Full database backup
mysqldump -u root -p your_database > dime_skills_backup_$(date +%Y%m%d).sql

# Verify backup was created
ls -lh dime_skills_backup_*.sql

Resource Backup

# Backup current resource
cp -r resources/dime_skills resources/dime_skills_v17_backup

# Or on Windows
xcopy /E /I resources\dime_skills resources\dime_skills_v17_backup

Step 2: Test in Development (Recommended)

If you have a test/development server, run the migration there first.

Restore database backup to test server
Deploy v1.9.0 files
Run migration
Verify everything works
Then proceed with production

Step 3: Stop Your Server

# Stop FiveM server gracefully
# Ensure all players are disconnected
# Allow time for final data saves

Don't skip this step! Running the migration on a live server can cause data corruption.

Step 4: Update Resource Files

Download v1.9.0

Download latest version from your purchase source
Extract the archive

Replace Files

# Remove old resource (after backing up!)
rm -rf resources/dime_skills

# Copy new version
cp -r dime_skills_v1.9.0 resources/dime_skills

# Or on Windows
rmdir /s resources\dime_skills
xcopy /E /I dime_skills_v1.9.0 resources\dime_skills

Preserve Your Configuration

Compare your old config.lua with the new structure and migrate your settings.

Changes in config:

disableSafetyCheck removed (always enabled now)
New GlobalMultipliers section added
Better organization and comments

Step 5: Start Server

Start your server normally:

# The resource will detect the old database structure
# It will NOT automatically migrate - you control when

When the server starts, you'll see:

[Dime Skills] Old database structure detected
[Dime Skills] Run 'migrate_skills' command to upgrade to v1.9.0

Step 6: Run Migration

Automatic Migration (Recommended)

In your server console:

migrate_skills

The migration process will:

Create backup table (player_skills_backup_v17)
Create new tables (normalized structure)
Migrate all data (preserves levels, XP, statlevel)
Verify integrity (shows summary)

Expected Output

[Dime Skills Migration] Creating backup of old table...
✓ Backup created successfully!

[Dime Skills Migration] Creating new normalized tables...
✓ New tables created successfully!

[Dime Skills Migration] Migrating player data...
✓ Migrated 1543 players with 0 errors!

[Dime Skills Migration] Total Players: 1543
[Dime Skills Migration] Total Skill Entries: 16973

[Dime Skills Migration] Skill Statistics:
  driving: 1543 players, Avg Level: 12.50, Avg XP: 450.25
  shooting: 1543 players, Avg Level: 8.30, Avg XP: 320.10
  ...

========================================
✓ Migration completed successfully!
========================================

Manual Migration (Alternative)

If you prefer SQL, run migration.sql directly:

mysql -u root -p your_database < migration.sql

Step 7: Verify Migration

Run the verification script:

test_migration

Verification Tests

The script runs 10 automated tests:

✓ Check new tables exist
✓ Check backup table exists
✓ Compare player counts
✓ Verify skill data migrated
✓ Check for data loss
✓ Verify indexes exist
✓ Check foreign keys
✓ Check for orphaned data
✓ Performance test
✓ Data type verification

Expected Result

========================================
[Test Results]
========================================
Passed: 10
Failed: 0
Warnings: 0

✓ All tests passed! Migration successful.
You can now safely use v1.9.0

Note: You can delete player_skills_backup_v17 after confirming everything works.
========================================

If any tests fail, DO NOT proceed! Check the error messages and consider rolling back.

Step 8: Update Custom Scripts

If you have custom resources using Dime Skills, update them:

Export Name Changes

-- Old (still works but deprecated)
local skills = exports.dime_skills:grabSkills(source)
local skill = exports.dime_skills:grabSkill(source, 'driving')
exports.dime_skills:addEXP(source, 'driving', 100)
exports.dime_skills:remoEXP(source, 'driving', 50)

-- New (recommended)
local skills = exports.dime_skills:getSkills(source)
local skill = exports.dime_skills:getSkill(source, 'driving')
exports.dime_skills:addXP(source, 'driving', 100)
exports.dime_skills:removeXP(source, 'driving', 50)

Remove Manual Sync

-- Old (no longer needed - remove this)
TriggerClientEvent('dime_skills:sendPlayerSkills', source, skillData)

-- New (automatic via statebags - no code needed)
-- Skills sync automatically when changed!

Step 9: Test Thoroughly

Before announcing to players:

Functional Tests

Join Server Tests

Log in with test character
Open skills UI (/skills or U key)
Verify your skills are correct
Do actions that give XP
Check level progression
Test with multiple players

Database Verification

-- Check player count
SELECT COUNT(*) FROM player_skills;

-- Check skill data
SELECT skill_name, COUNT(*) as players, AVG(level) as avg_level
FROM player_skill_data
GROUP BY skill_name;

-- Spot check a player
SELECT * FROM player_skill_data WHERE citizenID = 'ABC12345';

Step 10: Monitor & Optimize

After migration:

Monitor Performance

Watch server console for errors
Check database query times
Monitor memory usage
Gather player feedback

Optional Cleanup

After confirming everything works for 24-48 hours:

-- Remove backup table (ONLY after confirming everything works!)
DROP TABLE IF EXISTS player_skills_backup_v17;

Keep the backup table for at least a week before deleting it.

Troubleshooting

Rollback Procedure

If something goes wrong and you need to revert:

Only rollback if you encounter critical issues. Test thoroughly before deciding.

Step 1: Stop Server

# Stop FiveM server

Step 2: Restore Database

-- Remove new tables
DROP TABLE IF EXISTS player_skill_data;
DROP TABLE IF EXISTS player_skills;

-- Restore from backup
RENAME TABLE player_skills_backup_v17 TO player_skills;

Or restore from SQL backup:

mysql -u root -p your_database < dime_skills_backup_YYYYMMDD.sql

Step 3: Restore v1.7.x Files

# Restore old resource files
rm -rf resources/dime_skills
cp -r resources/dime_skills_v17_backup resources/dime_skills

Step 4: Restart Server

Your server is now back to v1.7.x state.

Post-Migration Checklist

After successful migration:

Getting Help

If you encounter issues:

Before Asking for Help

Run test_migration and save output
Enable Debug = true in config
Check F8 and server console for errors
Note your FiveM version and artifacts
Document exact steps that cause issues

Support Channels

Discord Community - Fastest response
Troubleshooting Guide
Direct support (check your purchase source)

Information to Provide

- FiveM Version: (artifacts version)
- Framework: (QBOX/ESX/etc)
- Server OS: (Windows/Linux)
- Player Count: (approximate)
- Migration Method: (automatic/manual)
- Test Results: (test_migration output)
- Error Messages: (exact text)
- Steps to Reproduce: (detailed)

FAQ

Q: How long does migration take?
A: 5-15 minutes for most servers. Depends on player count.

Q: Will players lose progress?
A: No! All skill data is preserved (levels, XP, statlevel).

Q: Can I migrate with players online?
A: Not recommended. Stop server and migrate offline for safety.

Q: Is the migration reversible?
A: Yes, with your backup. Keep it for at least a week.

Q: Do I have to update immediately?
A: No, v1.7.x still works. But v1.9.0 has major improvements.

Q: Will my custom skills migrate?
A: Yes, all skills (built-in and custom) migrate automatically.

Q: What if I have a very large database?
A: Test in development first. Migration handles thousands of players fine.

Q: Can I migrate incrementally?
A: No, it's all-or-nothing. But the process is automated and safe.

Update your server documentation
Inform players of any changes
Share new features with your community

Optimize

Monitor performance metrics
Tune configuration as needed
Consider new use cases for global multipliers

Congratulations on upgrading to v1.9.0! 🎉

Enjoy the improved performance and new features!

Migration to v1.9.0

Migration shows errors

Skills not syncing to clients

Data appears missing

Performance issues

Custom scripts broken

On this page