Module schema 

Database schema and migrations

TRACES: UR-002 | DR-012 | IR-013

Constants

MIGRATIONS

List of migrations to apply in order. Each migration is a tuple of (name, sql).

MIGRATION_001 🔒

Initial schema migration

MIGRATION_002 🔒

Migration to remove access_token column from users table Tokens are now stored in the system keyring (or encrypted file fallback)

MIGRATION_003 🔒

Migration to relax foreign key constraints on user_data table Allows tracking playback progress for items not yet synced to local database

MIGRATION_004 🔒

Migration to enhance downloads table with priority and bytes_downloaded

MIGRATION_005 🔒

Migration to relax foreign key constraint on downloads.item_id Allows downloading items that haven’t been synced to local database yet

MIGRATION_006 🔒

Migration to store item metadata directly in downloads table This eliminates dependency on items table being synced and fixes UUID display issues

MIGRATION_007 🔒

Migration to enhance thumbnail caching with LRU eviction support

MIGRATION_008 🔒

Migration to add video download support and item pinning

MIGRATION_009 🔒

Migration to add people/cast caching support

MIGRATION_010 🔒

Migration to add playback context tracking

MIGRATION_011 🔒

Migration to add user-specific player settings

MIGRATION_012 🔒

Migration to track download source (user-initiated vs auto-cached)

MIGRATION_013 🔒

Migration to add composite index for offline mode filtering

MIGRATION_014 🔒

Migration to add series audio track preferences

MIGRATION_015 🔒

Migration to add device ID storage

MIGRATION_016 🔒

Migration to add autoplay episode limit setting

MIGRATION_017 🔒

Migration to persist the resolved stream URL and target directory on each download row. This lets the backend queue pump start a pending download by itself (replaying the stored URL) once a concurrency slot frees up, instead of relying on the frontend to re-issue every queued item.

MIGRATION_018 🔒

Migration to record whether a cached item is a folder/container vs a playable leaf. Needed so channel items (which can be either) route to the player or to a browse list correctly. Existing cached rows predate the column and have an unknown folder flag, so we force a refresh by clearing their synced_at, causing the hybrid repository to re-fetch them from the server on next browse.

MIGRATION_019 🔒

Migration to cache the full server genre catalog. Previously genres were derived on the fly from cached albums, which meant offline (and the hybrid cache-first race) only ever saw genres for the handful of locally-cached albums — collapsing the variety on the music/TV/movie landing pages. This table stores the complete genre list per library so offline has the real catalog and cache-first routing returns the right thing.

MIGRATION_020 🔒

Migration to index items.season_id.

MIGRATION_021 🔒

Discard and rebuild the FTS index from the items table.

MIGRATION_022 🔒

Full-text index over people, mirroring items_fts.

MIGRATION_023 🔒

Give temporary downloads a life limit.