From cec40e384cd8ddc7da77262eb8f84f9ae2bac589 Mon Sep 17 00:00:00 2001 From: Intelli Date: Tue, 2 Sep 2025 14:52:27 -0600 Subject: [PATCH] Added database migration documentation --- docs/commands.md | 14 ++++ docs/database-migration.md | 143 +++++++++++++++++++++++++++++++++++++ docs/index.md | 3 + 3 files changed, 160 insertions(+) create mode 100644 docs/database-migration.md diff --git a/docs/commands.md b/docs/commands.md index ee00163..6f2de74 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -16,6 +16,7 @@ ___ | [/co reload](#co-reload) | Reload the configuration file | | [/co status](#co-status) | View the plugin status | | [/co consumer](#co-consumer) | Toggle consumer processing | +| [/co migrate-db](#co-migrate-db) | Migrate between SQLite and MySQL | ### Alias Commands @@ -128,6 +129,19 @@ ___ Console command to pause or resume consumer queue processing. ___ +### /co migrate-db +Migrate your CoreProtect database between SQLite and MySQL. Console-only command. + +| Command | Parameters | +| --- | --- | +| /co migrate-db | `` | + +> **Note:** This feature is exclusive to CoreProtect 23.0+ Patreon builds for Patron supporters. + +For complete migration instructions, safety guidelines, and troubleshooting information, see the [Database Migration documentation](/database-migration/). + +___ + ## Parameter Details diff --git a/docs/database-migration.md b/docs/database-migration.md new file mode 100644 index 0000000..939bd60 --- /dev/null +++ b/docs/database-migration.md @@ -0,0 +1,143 @@ +# Database Migration (SQLite ↔ MySQL) + +CoreProtect 23.0+ includes the ability to migrate your database between SQLite and MySQL without losing any data. + +> **Note:** Database migration functionality is exclusive to CoreProtect 23.0+ Patreon builds for Patron supporters. + +## Overview + +The `/co migrate-db` command allows you to seamlessly transfer all your CoreProtect data from SQLite to MySQL or vice versa. This is particularly useful when: + +* Starting with SQLite and wanting to upgrade to MySQL for better performance +* Moving from MySQL back to SQLite for simpler server setups +* Transferring data between different server configurations + +## Command Usage + +| Command | Parameters | Description | +| --- | --- | --- | +| `/co migrate-db` | `` | Migrate to the specified database type | + +**Examples:** +* `/co migrate-db mysql` - Migrate from SQLite to MySQL +* `/co migrate-db sqlite` - Migrate from MySQL to SQLite + +> **Console Only:** This command can only be executed from the server console, not from in-game. + +--- + +## Migration Process + +### Step 1: Preparation + +**Before starting the migration:** + +1. **Ensure your server is running** with your current CoreProtect database +2. **Backup your existing database** (recommended safety measure) +3. **Configure your target database** in `config.yml`: + * For MySQL migration: Set up your MySQL connection details + * For SQLite migration: Ensure the SQLite file path is configured +4. **Important:** Do NOT restart your server or use `/co reload` after modifying the config + +### Step 2: Execute Migration + +1. **Run the migration command** from your server console: + ``` + co migrate-db + ``` + +2. **Monitor the progress:** + * The migration will display detailed progress information + * Large databases may take considerable time to complete + * Progress bars and speed indicators will show current status + +3. **Do not interrupt the process:** + * Avoid restarting your server during migration + * Let the process complete naturally + +### Step 3: Post-Migration + +**After successful completion:** + +1. **Automatic switchover:** CoreProtect will automatically begin using the new database +2. **Verify configuration:** Ensure `use-mysql` is set correctly in your `config.yml` +3. **Test functionality:** Perform basic CoreProtect operations to verify everything works +4. **Clean up:** Once satisfied, you may manually delete your old database files + +--- + +## Important Considerations + +### Migration Safety + +* **Non-destructive process:** The migration does not modify or delete your existing database +* **Rollback capability:** If something goes wrong, simply delete the new database and continue using the old one +* **Data verification:** The process includes automatic verification to ensure data integrity + +### Performance & Requirements + +* **Processing time:** Large databases with millions of records may take hours to migrate +* **Resource usage:** The migration process is resource-intensive and may impact server performance +* **Parallel processing:** SQLite to MySQL migrations use optimized parallel processing for better speed + +### Restrictions & Limitations + +* **Console only:** Cannot be executed from in-game chat +* **Single direction:** Cannot migrate to the same database type currently in use +* **Interruption handling:** If interrupted, the target database must be manually wiped before restarting +* **Patreon exclusive:** Only available in CoreProtect 23.0+ Patreon builds + +--- + +## Troubleshooting + +### Common Issues + +**Migration won't start:** +* Verify you're using a CoreProtect 23.0+ Patreon build +* Ensure you're not trying to migrate to the same database type +* Check that no other CoreProtect operations are running + +**Migration interrupted:** +* Manually delete/wipe the target database +* Verify server stability before restarting migration +* Consider migrating during low-activity periods + +**Performance issues:** +* Monitor server resources during migration +* Consider temporarily reducing server activity +* Large tables may cause temporary slowdowns + +**Data verification failures:** +* Check database connectivity and permissions +* Review server logs for specific error messages +* Ensure sufficient disk space on target database + +### Getting Help + +If you encounter issues with database migration: + +1. **Check server logs** for detailed error messages +2. **Verify database permissions** and connectivity +3. **Ensure adequate system resources** (RAM, CPU, disk space) +4. **Contact support** through the CoreProtect Discord with specific error details + +--- + +## Technical Details + +The migration process includes several advanced features: + +* **Batch processing** with dynamic sizing based on performance +* **Automatic retry** mechanisms for temporary failures +* **Data integrity verification** comparing source and target records +* **Progress tracking** with estimated completion times +* **Graceful error handling** with detailed logging + +The migration handles all CoreProtect data types including: +* Block changes and rollbacks +* Container transactions +* Player interactions and sessions +* Chat messages and commands +* User data and statistics +* All metadata and configuration data diff --git a/docs/index.md b/docs/index.md index 96f980a..f1203fa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,6 +18,9 @@ A list of all language codes that can be used with CoreProtect. [**CoreProtect API Documentation**](/api/) Log your own block changes, perform lookups, rollbacks, restores, and more. +[**Database Migration**](/database-migration/) +Migrate your CoreProtect database between SQLite and MySQL. + [**Compatible Third-Party Plugins & Tools**](/tools-integrations/) A list of plugins and tools that are compatible with CoreProtect.