Archive/retro/database_backup/MIGRATION_GUIDE.txt

HABBO RETRO DATABASE MIGRATION GUIDE
=====================================

Created: December 6, 2025
Database: habbo_retro
Tables: 174
Size: 51.08 MB (database), 29 MB (dump), 3.3 MB (compressed)

FILES INCLUDED:
===============
✓ habbo_retro_complete_20251206_155812.sql (29 MB) - Full SQL dump
✓ habbo_retro_complete_20251206_155812.sql.gz (3.3 MB) - Compressed version
✓ MIGRATION_GUIDE.txt - This file

DATABASE INFORMATION:
=====================
Database Name: habbo_retro
Character Set: utf8mb4
Collation: utf8mb4_unicode_ci (default)
Tables: 174
Storage Engine: InnoDB (most tables)

INCLUDED FEATURES:
==================
✓ All table structures (CREATE TABLE)
✓ All table data (INSERT statements)
✓ Stored procedures and functions (--routines)
✓ Triggers (--triggers)
✓ Complete inserts (all column names specified)
✓ Drop table statements (clean import)

KEY TABLES:
===========
User Management:
- users (user accounts)
- users_settings (user preferences)
- user_ai_settings (AI provider settings)

Catalog System:
- catalog_items (51,678 items - NOW IN ENGLISH!)
- catalog_pages (2,311 pages - English)
- catalog_pages_backup (original Spanish backup)
- catalog_items_backup (original pre-translation)
- catalog_items_backup_translation (translation backup)

Game Data:
- items (furniture items)
- rooms (user rooms)
- room_models (room layouts)
- navigator_publics (public rooms)

Emulator:
- emulator_texts (server messages - 956 entries)
- emulator_settings (configuration)
- permissions (user ranks)

Website/CMS:
- website_languages (language support)
- website_settings (CMS configuration)

MIGRATION STEPS:
================

STEP 1: Prepare New Server
---------------------------
1. Install MySQL 8.0 or higher
2. Create database user:
   ```sql
   CREATE DATABASE habbo_retro CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'habbo_user'@'localhost' IDENTIFIED BY 'YOUR_SECURE_PASSWORD';
   GRANT ALL PRIVILEGES ON habbo_retro.* TO 'habbo_user'@'localhost';
   FLUSH PRIVILEGES;
   ```

STEP 2: Upload and Extract
---------------------------
1. Upload habbo_retro_complete_20251206_155812.sql.gz to your new server
2. Extract: `gunzip habbo_retro_complete_20251206_155812.sql.gz`

STEP 3: Import Database
------------------------
Option A - Command Line (Recommended):
```bash
mysql -u habbo_user -p habbo_retro < habbo_retro_complete_20251206_155812.sql
```

Option B - phpMyAdmin:
1. Login to phpMyAdmin
2. Select habbo_retro database
3. Go to Import tab
4. Upload the SQL file
5. Click "Go"

STEP 4: Verify Import
----------------------
```sql
USE habbo_retro;
SHOW TABLES;  -- Should show 174 tables
SELECT COUNT(*) FROM catalog_items;  -- Should show 51,678
SELECT COUNT(*) FROM catalog_pages;  -- Should show 2,311
SELECT COUNT(*) FROM users;  -- Check your user count
```

STEP 5: Update Configuration Files
-----------------------------------

Arcturus Emulator (config.ini):
```ini
db.hostname=YOUR_SERVER_IP
db.port=3306
db.username=habbo_user
db.password=YOUR_SECURE_PASSWORD
db.database=habbo_retro
```

AtomCMS (.env):
```env
DB_CONNECTION=mysql
DB_HOST=YOUR_SERVER_IP
DB_PORT=3306
DB_DATABASE=habbo_retro
DB_USERNAME=habbo_user
DB_PASSWORD=YOUR_SECURE_PASSWORD
```

IMPORTANT NOTES:
================

✓ TRANSLATIONS COMPLETED:
  - Catalog pages: 100% English (2,311 pages)
  - Catalog items: 99.93% English (51,643/51,678)
  - Only 32 items remain with accents (Pokémon, Café, Piñata)

✓ BACKUPS INCLUDED:
  - catalog_pages_backup (original Spanish pages)
  - catalog_items_backup (original items)
  - catalog_items_backup_translation (translation checkpoint)

✓ CHARACTER ENCODING:
  - Use UTF8MB4 for full emoji and special character support
  - Required for Pokémon names and special furniture

⚠ SECURITY:
  - Change default passwords immediately
  - Use strong passwords for MySQL users
  - Restrict database access to localhost if possible
  - Enable SSL for MySQL connections if available

⚠ PERFORMANCE:
  - Enable query cache if available
  - Optimize InnoDB buffer pool (recommended: 50-70% of RAM)
  - Create indexes if queries are slow (check EXPLAIN)

TROUBLESHOOTING:
================

"Access denied" error:
- Verify user has been created correctly
- Check password matches config files
- Ensure GRANT ALL was executed

"Table doesn't exist" error:
- Verify import completed successfully
- Check database name in config matches
- Run SHOW TABLES to see what imported

Slow queries:
- Check MySQL configuration (my.cnf)
- Increase innodb_buffer_pool_size
- Enable slow query log to identify issues

Connection refused:
- Verify MySQL is running
- Check firewall allows port 3306
- Ensure bind-address allows external connections

POST-MIGRATION CHECKLIST:
=========================
□ Database imported successfully
□ All 174 tables present
□ Sample queries return expected data
□ Emulator config.ini updated
□ CMS .env file updated
□ Test emulator connection to database
□ Test CMS connection to database
□ Verify user login works
□ Check catalog loads correctly
□ Backup new server database

SUPPORT:
========
If issues occur during migration:
1. Check MySQL error logs
2. Verify all steps were completed
3. Test database connection with MySQL client
4. Ensure character set is utf8mb4

Database Version: MySQL 9.5.0 (export server)
Compatible With: MySQL 5.7+, MariaDB 10.2+
Export Date: December 6, 2025 15:58:12