Skip to content

Commit d689529

Browse files
thawnthawn
authored
Merge pull request #103 from thawn/copilot/document-database-migration-process
Add migration documentation for database and library transfer
2 parents d53f863 + 3e19e7c commit d689529

File tree

4 files changed

+145
-2
lines changed

4 files changed

+145
-2
lines changed

‎docs/getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,4 +51,4 @@ Click "Create GME" button, wait for conversion (1-5 minutes).
5151
* Use unique OID numbers
5252
* Include cover images for easier identification
5353
* Test print quality with [OID table](https://github.com/thawn/ttmp32gme/blob/master/src/assets/images/oid-table.png)
54-
* Backup `~/.ttmp32gme/` directory regularly
54+
* Backup `~/.ttmp32gme/` directory regularly (see [Migration Guide](migration.md))

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ getting-started
2424
installation
2525
usage
2626
print-configuration
27+
migration
2728
troubleshooting
2829
```
2930

‎docs/migration.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Data Migration
2+
3+
This guide explains how to migrate your ttmp32gme configuration database and library folder from one computer to another.
4+
5+
## What to Migrate
6+
7+
ttmp32gme stores two types of data:
8+
9+
1. **Configuration Database** (`config.sqlite`) - Contains application settings, album metadata, and OID assignments
10+
2. **Library Folder** - Contains audio files, GME files, cover images, and generated content
11+
12+
## Data Locations
13+
14+
### Default Locations
15+
16+
**Linux**:
17+
- Database: `~/.ttmp32gme/config.sqlite`
18+
- Library: `~/.ttmp32gme/library/`
19+
20+
**macOS**:
21+
- Database: `~/Library/Application Support/ttmp32gme/config.sqlite`
22+
- Library: `~/Library/Application Support/ttmp32gme/library/`
23+
24+
**Windows**:
25+
- Database: `%APPDATA%\ttmp32gme\config.sqlite`
26+
- Library: `%APPDATA%\ttmp32gme\library\`
27+
28+
### Custom Locations
29+
30+
If you started ttmp32gme with `--database` or `--library` flags, your data is in those custom locations instead.
31+
32+
## Migration Steps
33+
34+
### Option 1: Same-Platform Migration (Recommended)
35+
36+
Use this method when migrating between computers running the same operating system (Linux to Linux, macOS to macOS, Windows to Windows) or between Linux and macOS.
37+
38+
Migrate both database and library to preserve all data and settings.
39+
40+
**On the source computer**:
41+
42+
1. Stop ttmp32gme if running
43+
2. Locate your data directory:
44+
- Linux: `~/.ttmp32gme/`
45+
- macOS: `~/Library/Application Support/ttmp32gme/`
46+
- Windows: `%APPDATA%\ttmp32gme\`
47+
3. Copy the entire directory to a USB drive or network location
48+
49+
**On the destination computer**:
50+
51+
1. Install ttmp32gme (see [Installation](installation.md))
52+
2. Stop ttmp32gme if it auto-started
53+
3. Locate the data directory (same locations as above)
54+
4. Copy the entire directory from your backup to this location
55+
5. Start ttmp32gme - all albums, settings, and files will be available
56+
57+
### Option 2: Cross-Platform Migration (Windows to macOS/Linux)
58+
59+
Use this method **only** when migrating between Windows and another operating system (macOS or Linux). This process requires re-importing your audio files.
60+
61+
**Note**: For migrations between macOS and Linux, use **Option 1** instead.
62+
63+
**On the source computer (Windows)**:
64+
65+
1. Stop ttmp32gme if running
66+
2. Locate your library folder: `%APPDATA%\ttmp32gme\library\`
67+
3. Copy all album folders from the library to a USB drive or network location
68+
4. Each album folder contains the original MP3 files and cover images
69+
70+
**On the destination computer (macOS/Linux)**:
71+
72+
1. Install ttmp32gme (see [Installation](installation.md))
73+
2. Start ttmp32gme to create the initial configuration
74+
3. For each album from your backup:
75+
- Navigate to the Upload page
76+
- Upload the MP3 files from the album folder
77+
- Upload the cover image (if present: `cover.jpg` or `cover.png`)
78+
- Configure album settings (title, artist, OID) to match your original setup
79+
- Click "Create GME" to generate the GME files
80+
81+
## Custom Paths
82+
83+
If using custom database or library paths with `--database` or `--library` flags:
84+
85+
1. Copy the files from your custom locations instead of default locations
86+
2. Start ttmp32gme with the same flags on the new computer:
87+
```bash
88+
ttmp32gme --database /path/to/config.sqlite --library /path/to/library
89+
```
90+
91+
## Verification
92+
93+
After migration:
94+
95+
1. Start ttmp32gme
96+
2. Check Library page - all albums should be visible
97+
3. Check Config page - settings should match your old setup
98+
4. Test printing a control sheet to verify OID codes are preserved
99+
100+
## Troubleshooting
101+
102+
**Albums missing after migration**:
103+
- Verify you copied the entire data directory including `config.sqlite`
104+
- Refresh the Library page (F5)
105+
- Check that the database file has read/write permissions
106+
107+
**Permission errors**:
108+
- Ensure copied files have proper read/write permissions
109+
- On Linux: `chmod -R u+rw ~/.ttmp32gme/`
110+
- On macOS: `chmod -R u+rw ~/Library/Application\ Support/ttmp32gme/`
111+
112+
## Backup Recommendations
113+
114+
Regular backups prevent data loss:
115+
116+
- **Automatic**: Create a scheduled backup of the entire data directory
117+
- **Before updates**: Backup before upgrading ttmp32gme
118+
- **After changes**: Backup after creating new albums or changing settings
119+
120+
Example backup command (Linux):
121+
```bash
122+
# Create timestamped backup
123+
tar -czf ttmp32gme-backup-$(date +%Y%m%d).tar.gz ~/.ttmp32gme/
124+
```
125+
126+
Example backup command (macOS):
127+
```bash
128+
# Create timestamped backup
129+
tar -czf ttmp32gme-backup-$(date +%Y%m%d).tar.gz ~/Library/Application\ Support/ttmp32gme/
130+
```
131+
132+
Example backup command (Windows PowerShell):
133+
```powershell
134+
# Create timestamped backup
135+
Compress-Archive -Path $env:APPDATA\ttmp32gme -DestinationPath "ttmp32gme-backup-$(Get-Date -Format 'yyyyMMdd').zip"
136+
```
137+
138+
## See Also
139+
140+
- [Installation](installation.md) - Installing ttmp32gme on a new system
141+
- [Usage Guide](usage.md) - Using ttmp32gme after migration
142+
- [Troubleshooting](troubleshooting.md) - Common issues and solutions

‎docs/usage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,4 +68,4 @@ ttmp32gme --debug # Debug mode
6868
- Use unique OID numbers
6969
- Include cover images
7070
- Print at 1200 DPI
71-
- Backup `~/.ttmp32gme/` directory
71+
- Backup `~/.ttmp32gme/` directory (see [Migration Guide](migration.md))

0 commit comments

Comments
 (0)