feat: add legacy key/data file migration to database
- Add migration_legacy_files_completed flag to SystemSettings model - Create legacy_file_migration service to migrate series from key/data files - Integrate legacy migration into initialization_service startup flow - Add integration tests for legacy file migration - Update DATABASE.md documentation with migration details - Fix various test and service issues (nfo_repair, tmdb_client, download_service) - Add test_database_schema unit tests
This commit is contained in:
@@ -83,17 +83,23 @@ Source: [src/server/database/models.py](../src/server/database/models.py), [src/
|
||||
|
||||
### 3.2 anime_series
|
||||
|
||||
Stores anime series metadata.
|
||||
Stores anime series metadata. Corresponds to the core `Serie` class.
|
||||
|
||||
| Column | Type | Constraints | Description |
|
||||
| ------------ | ------------- | -------------------------- | ------------------------------------------------------- |
|
||||
| `id` | INTEGER | PRIMARY KEY, AUTOINCREMENT | Internal database ID |
|
||||
| `key` | VARCHAR(255) | UNIQUE, NOT NULL, INDEX | **Primary identifier** - provider-assigned URL-safe key |
|
||||
| `name` | VARCHAR(500) | NOT NULL, INDEX | Display name of the series |
|
||||
| `site` | VARCHAR(500) | NOT NULL | Provider site URL |
|
||||
| `folder` | VARCHAR(1000) | NOT NULL | Filesystem folder name (metadata only) |
|
||||
| `created_at` | DATETIME | NOT NULL, DEFAULT NOW | Record creation timestamp |
|
||||
| `updated_at` | DATETIME | NOT NULL, ON UPDATE NOW | Last update timestamp |
|
||||
| Column | Type | Constraints | Description |
|
||||
| ---------------- | ------------- | -------------------------- | ------------------------------------------------------- |
|
||||
| `id` | INTEGER | PRIMARY KEY, AUTOINCREMENT | Internal database ID |
|
||||
| `key` | VARCHAR(255) | UNIQUE, NOT NULL, INDEX | **Primary identifier** - provider-assigned URL-safe key |
|
||||
| `name` | VARCHAR(500) | NOT NULL, INDEX | Display name of the series |
|
||||
| `site` | VARCHAR(500) | NOT NULL | Provider site URL |
|
||||
| `folder` | VARCHAR(1000) | NOT NULL | Filesystem folder name (metadata only) |
|
||||
| `year` | INTEGER | NULLABLE | Release year of the series |
|
||||
| `nfo_path` | VARCHAR(1000) | NULLABLE | Path to tvshow.nfo metadata file |
|
||||
| `tmdb_id` | INTEGER | NULLABLE, INDEX | TMDB (The Movie Database) ID for metadata |
|
||||
| `tvdb_id` | INTEGER | NULLABLE, INDEX | TVDB (TheTVDB) ID for metadata |
|
||||
| `has_nfo` | BOOLEAN | NOT NULL, DEFAULT FALSE | Whether tvshow.nfo exists |
|
||||
| `loading_status` | VARCHAR(50) | NOT NULL, DEFAULT 'completed' | Status: pending, loading_episodes, loading_nfo, completed, failed |
|
||||
| `created_at` | DATETIME | NOT NULL, DEFAULT NOW | Record creation timestamp |
|
||||
| `updated_at` | DATETIME | NOT NULL, ON UPDATE NOW | Last update timestamp |
|
||||
|
||||
**Identifier Convention:**
|
||||
|
||||
@@ -101,7 +107,13 @@ Stores anime series metadata.
|
||||
- `folder` is **metadata only** for filesystem operations (e.g., `"Attack on Titan (2013)"`)
|
||||
- `id` is used only for database relationships
|
||||
|
||||
Source: [src/server/database/models.py](../src/server/database/models.py#L23-L87)
|
||||
**EpisodeDict Mapping:**
|
||||
|
||||
The `episodeDict` (season → episode numbers mapping) is stored as individual `Episode` records:
|
||||
- Each `Episode` has `season` and `episode_number` columns
|
||||
- Relationship: `AnimeSeries.episodes` returns all Episode records for that series
|
||||
|
||||
Source: [src/server/database/models.py](../src/server/database/models.py#L23-L150)
|
||||
|
||||
### 3.3 episodes
|
||||
|
||||
@@ -441,7 +453,63 @@ items = await db.execute(
|
||||
|
||||
---
|
||||
|
||||
## 12. Database Location
|
||||
## 12. Series Storage: Database vs Files (Deprecated)
|
||||
|
||||
### File-Based Storage (Removed in v2.0)
|
||||
|
||||
Prior to v2.0, series metadata was stored in two files per anime folder:
|
||||
|
||||
| File | Contents |
|
||||
| -------- | ------------------------------------------------------- |
|
||||
| `key` | Series provider key (e.g., `"attack-on-titan"`) |
|
||||
| `data` | JSON serialization of `Serie` object |
|
||||
|
||||
File structure example:
|
||||
```
|
||||
/anime/Attack on Titan (2013)/
|
||||
├── key # Contains: attack-on-titan
|
||||
├── data # Contains: {"key": "...", "name": "...", "episodeDict": {...}}
|
||||
├── Season 1/
|
||||
│ └── ...
|
||||
```
|
||||
|
||||
### Database Storage (Current)
|
||||
|
||||
Since v2.0, all series metadata is stored in the `anime_series` table with `Episode` records for episode tracking. This provides:
|
||||
|
||||
- **ACID transactions** for data consistency
|
||||
- **Foreign key constraints** (cascade delete)
|
||||
- **Indexed queries** for fast lookups
|
||||
- **No filesystem dependency** for metadata
|
||||
|
||||
### Migration from Files to Database
|
||||
|
||||
The `Serie.save_to_file()` and `Serie.load_from_file()` methods are deprecated but still functional for backward compatibility during migration:
|
||||
|
||||
```python
|
||||
from src.core.entities.series import Serie
|
||||
|
||||
# Old file-based loading (deprecated)
|
||||
serie = Serie.load_from_file("/anime/Attack on Titan (2013)/data")
|
||||
|
||||
# New database-based loading
|
||||
from src.server.database.service import AnimeSeriesService
|
||||
serie = await AnimeSeriesService.get_by_key(db, "attack-on-titan")
|
||||
```
|
||||
|
||||
### Removing File Dependencies
|
||||
|
||||
After verifying database schema supports all fields, file-based storage can be removed:
|
||||
|
||||
1. ✅ Schema verified: All `Serie` fields have corresponding DB columns
|
||||
2. ✅ Migration complete: All existing series migrated to database
|
||||
3. ❌ File cleanup: Remove `key` and `data` files (pending)
|
||||
|
||||
**Note:** The `save_to_file()` and `load_from_file()` methods will be removed in v3.0.0.
|
||||
|
||||
---
|
||||
|
||||
## 13. Database Location
|
||||
|
||||
| Environment | Default Location |
|
||||
| ----------- | ------------------------------------------------- |
|
||||
|
||||
Reference in New Issue
Block a user