Skip to content

Commit cec40e3

Browse files
IntelliIntelli
committed
Added database migration documentation
1 parent 86d164e commit cec40e3

File tree

3 files changed

+160
-0
lines changed

3 files changed

+160
-0
lines changed

‎docs/commands.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ ___
1616
| [/co reload](#co-reload) | Reload the configuration file |
1717
| [/co status](#co-status) | View the plugin status |
1818
| [/co consumer](#co-consumer) | Toggle consumer processing |
19+
| [/co migrate-db](#co-migrate-db) | Migrate between SQLite and MySQL |
1920

2021
### Alias Commands
2122

@@ -128,6 +129,19 @@ ___
128129
Console command to pause or resume consumer queue processing.
129130
___
130131

132+
### /co migrate-db
133+
Migrate your CoreProtect database between SQLite and MySQL. Console-only command.
134+
135+
| Command | Parameters |
136+
| --- | --- |
137+
| /co migrate-db | `<sqlite\|mysql>` |
138+
139+
> **Note:** This feature is exclusive to CoreProtect 23.0+ Patreon builds for Patron supporters.
140+
141+
For complete migration instructions, safety guidelines, and troubleshooting information, see the [Database Migration documentation](/database-migration/).
142+
143+
___
144+
131145

132146
## Parameter Details
133147

‎docs/database-migration.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Database Migration (SQLite ↔ MySQL)
2+
3+
CoreProtect 23.0+ includes the ability to migrate your database between SQLite and MySQL without losing any data.
4+
5+
> **Note:** Database migration functionality is exclusive to CoreProtect 23.0+ Patreon builds for Patron supporters.
6+
7+
## Overview
8+
9+
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:
10+
11+
* Starting with SQLite and wanting to upgrade to MySQL for better performance
12+
* Moving from MySQL back to SQLite for simpler server setups
13+
* Transferring data between different server configurations
14+
15+
## Command Usage
16+
17+
| Command | Parameters | Description |
18+
| --- | --- | --- |
19+
| `/co migrate-db` | `<sqlite\|mysql>` | Migrate to the specified database type |
20+
21+
**Examples:**
22+
* `/co migrate-db mysql` - Migrate from SQLite to MySQL
23+
* `/co migrate-db sqlite` - Migrate from MySQL to SQLite
24+
25+
> **Console Only:** This command can only be executed from the server console, not from in-game.
26+
27+
---
28+
29+
## Migration Process
30+
31+
### Step 1: Preparation
32+
33+
**Before starting the migration:**
34+
35+
1. **Ensure your server is running** with your current CoreProtect database
36+
2. **Backup your existing database** (recommended safety measure)
37+
3. **Configure your target database** in `config.yml`:
38+
* For MySQL migration: Set up your MySQL connection details
39+
* For SQLite migration: Ensure the SQLite file path is configured
40+
4. **Important:** Do NOT restart your server or use `/co reload` after modifying the config
41+
42+
### Step 2: Execute Migration
43+
44+
1. **Run the migration command** from your server console:
45+
```
46+
co migrate-db <target_type>
47+
```
48+
49+
2. **Monitor the progress:**
50+
* The migration will display detailed progress information
51+
* Large databases may take considerable time to complete
52+
* Progress bars and speed indicators will show current status
53+
54+
3. **Do not interrupt the process:**
55+
* Avoid restarting your server during migration
56+
* Let the process complete naturally
57+
58+
### Step 3: Post-Migration
59+
60+
**After successful completion:**
61+
62+
1. **Automatic switchover:** CoreProtect will automatically begin using the new database
63+
2. **Verify configuration:** Ensure `use-mysql` is set correctly in your `config.yml`
64+
3. **Test functionality:** Perform basic CoreProtect operations to verify everything works
65+
4. **Clean up:** Once satisfied, you may manually delete your old database files
66+
67+
---
68+
69+
## Important Considerations
70+
71+
### Migration Safety
72+
73+
* **Non-destructive process:** The migration does not modify or delete your existing database
74+
* **Rollback capability:** If something goes wrong, simply delete the new database and continue using the old one
75+
* **Data verification:** The process includes automatic verification to ensure data integrity
76+
77+
### Performance & Requirements
78+
79+
* **Processing time:** Large databases with millions of records may take hours to migrate
80+
* **Resource usage:** The migration process is resource-intensive and may impact server performance
81+
* **Parallel processing:** SQLite to MySQL migrations use optimized parallel processing for better speed
82+
83+
### Restrictions & Limitations
84+
85+
* **Console only:** Cannot be executed from in-game chat
86+
* **Single direction:** Cannot migrate to the same database type currently in use
87+
* **Interruption handling:** If interrupted, the target database must be manually wiped before restarting
88+
* **Patreon exclusive:** Only available in CoreProtect 23.0+ Patreon builds
89+
90+
---
91+
92+
## Troubleshooting
93+
94+
### Common Issues
95+
96+
**Migration won't start:**
97+
* Verify you're using a CoreProtect 23.0+ Patreon build
98+
* Ensure you're not trying to migrate to the same database type
99+
* Check that no other CoreProtect operations are running
100+
101+
**Migration interrupted:**
102+
* Manually delete/wipe the target database
103+
* Verify server stability before restarting migration
104+
* Consider migrating during low-activity periods
105+
106+
**Performance issues:**
107+
* Monitor server resources during migration
108+
* Consider temporarily reducing server activity
109+
* Large tables may cause temporary slowdowns
110+
111+
**Data verification failures:**
112+
* Check database connectivity and permissions
113+
* Review server logs for specific error messages
114+
* Ensure sufficient disk space on target database
115+
116+
### Getting Help
117+
118+
If you encounter issues with database migration:
119+
120+
1. **Check server logs** for detailed error messages
121+
2. **Verify database permissions** and connectivity
122+
3. **Ensure adequate system resources** (RAM, CPU, disk space)
123+
4. **Contact support** through the CoreProtect Discord with specific error details
124+
125+
---
126+
127+
## Technical Details
128+
129+
The migration process includes several advanced features:
130+
131+
* **Batch processing** with dynamic sizing based on performance
132+
* **Automatic retry** mechanisms for temporary failures
133+
* **Data integrity verification** comparing source and target records
134+
* **Progress tracking** with estimated completion times
135+
* **Graceful error handling** with detailed logging
136+
137+
The migration handles all CoreProtect data types including:
138+
* Block changes and rollbacks
139+
* Container transactions
140+
* Player interactions and sessions
141+
* Chat messages and commands
142+
* User data and statistics
143+
* All metadata and configuration data

‎docs/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ A list of all language codes that can be used with CoreProtect.
1818
[**CoreProtect API Documentation**](/api/)
1919
Log your own block changes, perform lookups, rollbacks, restores, and more.
2020

21+
[**Database Migration**](/database-migration/)
22+
Migrate your CoreProtect database between SQLite and MySQL.
23+
2124
[**Compatible Third-Party Plugins & Tools**](/tools-integrations/)
2225
A list of plugins and tools that are compatible with CoreProtect.
2326

0 commit comments

Comments
 (0)