Crate db 

Kopuz persistence layer (issue #347).

Owns the SQLite schema and all persistence behind a single async Storage trait. Native targets implement it with sqlx; wasm (not a shipped target) gets a thin in-memory stub so the build stays green. Everything above this crate (reactive hooks, UI) is driver-agnostic.

Dependency direction: db sits ABOVE config/reader (it persists their types), so those crates stay pure model definitions and all save/load lives here.

Structs

Db

Cheap-Clone handle to the active storage backend, shared via Dioxus context.

ImportReport

What a one-shot legacy-JSON import did. ran == false means it was skipped (already migrated, or no legacy JSON present); the counts are then all zero.

Page

A window into a list query (for virtual-scrolled big lists).

QueueSnapshot

The queue/progress snapshot, reconstructed from the queue_state row. The in-memory PersistedQueueState (in the app crate) maps directly from this.

ReadDb

Read-only view of the storage backend — the surface the UI gets, so it cannot reach a write method (those live on Storage, not ReadStore).

TrackFilter

What a windowed track listing selects: which source, how it’s sorted, and an optional case-insensitive search across title/artist/album. Drives WHERE/ORDER BY so only the needed rows are materialized. Narrower listings (one album, one artist, one genre, a folder) have dedicated Storage methods instead of filter fields — there is deliberately no way to pull a whole source and filter it in memory.

Enums

DbError

Errors surfaced by the storage layer. String-wrapped so the type is identical on native and wasm (sqlx isn’t compiled for wasm).

Source

Where a track/playlist/favorite comes from, and what the app is currently sourcing from: the local library, or a specific media server.

TrackSort

Sort order for a track listing — maps to an indexed ORDER BY.

Traits

ReadStore

The read side of the persistence API — every query, no mutation. Carried as a supertrait of Storage, so any dyn Storage is also a dyn ReadStore.

Storage

The persistence API: every mutation plus admin/dev ops, layered on top of the read-only ReadStore. One impl per target (sqlx native / in-mem stub).

Functions

config_dir

<config_dir> for kopuz (matches the legacy JSON store location).

default_db_path

The on-disk database path: KOPUZ_DB_PATH override, else <config_dir>/kopuz.db (release) or kopuz-debug.db (debug builds, so dx run never touches real data).

init

Open the database and apply migrations. Native callers should block_on this in main() before mounting.

peek_config

Blocking pre-boot read of the config blob — for the few values needed before the app (and its async runtime/log subscriber) exists: the tracing toggle and the titlebar mode. Opens the DB read-only without running migrations; None if the DB or blob doesn’t exist yet (first launch). Server/creds fields are NOT hydrated — blob fields only.

release_db_path

The RELEASE database path (kopuz.db), independent of build profile — the debug panel’s “load release DB” source.

Type Aliases

ArtistImages

Per-artist images, source-agnostic: (overrides, photos). overrides are user-set custom photos (always a local path, highest priority); photos are the synced photo per artist as a uniform reader::ArtistImageRef (a server URL or a local path — server wins when both exist), resolved by the cover seam so callers never branch on origin. Both keyed by normalized artist name.