// Houndarr's SQLite schema and migration discipline. Loads when reading or editing src/houndarr/database.py. Covers the schema table reference, the SCHEMA_VERSION bump checklist, and the version-locking rule for migration constants that prevents later renames from retroactively breaking earlier rebuild migrations.
Houndarr's source layout and architectural patterns at file granularity. Loads when reading or editing src/houndarr/. Covers the per-file purpose for auth/, clients/, engine/, routes/, services/; the wire-models vs domain-models split; the *arr API spec snapshots under docs/api/; and pointers to the more specific database / engine skills for narrower scopes.
Houndarr's CHANGELOG.md style guide and entry rules. Loads when reading or editing CHANGELOG.md or VERSION. Covers the noun-led present-tense voice, the 80-160 character length target, vocabulary the operator can act on, banned phrasings, what does not belong in a changelog, separator rules, and the bullet-justification protocol that prevents drafting from PR titles or memory.
Houndarr's CI workflow reference and branch protection. Loads when reading or editing .github/workflows/. Covers the 11 required status checks (exact names matter for branch protection), the additional non-required workflows, the paths-ignore + ci-skip pattern that keeps docs-only PRs green, and the rule against changing required check job names.
Houndarr-specific Python conventions on top of the global python skill. Loads when reading or editing .py files in this repo. Covers the noqa/nosec suppression table, the AppSettings-as-plain-dataclass decision, the frozen-dataclass-with-slots invariant for domain models, the per-module logger pattern, and the background-task error-handling shape.
Houndarr's pytest patterns. Loads when reading or editing tests/ files. Covers the fixture dependency graph, the FK seeding pattern for cooldowns/search_log tests, the local _login() and CSRF helpers in route tests, and the auth-state reset in test_settings.
Verify probabilistic, distributional, or random behaviour empirically before changing search-engine code. Loads when reading or editing src/houndarr/engine/. Use when a user, code review, or another AI surfaces a claim about bias, ordering, page selection, randomness, or "we are searching the same things over and over".
| name | houndarr-database |
| description | Houndarr's SQLite schema and migration discipline. Loads when reading or editing src/houndarr/database.py. Covers the schema table reference, the SCHEMA_VERSION bump checklist, and the version-locking rule for migration constants that prevents later renames from retroactively breaking earlier rebuild migrations. |
| paths | ["src/houndarr/database.py"] |
SQLite via aiosqlite. get_db() is an async context manager that opens
a fresh connection per call (FKs enabled per connection; WAL mode set
once in init_db()). Schema version is currently 19. Bump
SCHEMA_VERSION and add a _migrate_to_vN when changing schema.
| Table | Purpose | Key constraints |
|---|---|---|
settings | Key-value config store | key TEXT PK |
widget_api_key | External widget API key, single row (v19) | id INTEGER PRIMARY KEY CHECK(id = 1); hash is SHA-256 hex digest with CHECK(length(hash) = 64 AND hash NOT GLOB '*[^0-9a-f]*'); no FK |
instances | *arr instance configs | type CHECK IN ('radarr','sonarr','lidarr','readarr','whisparr_v2','whisparr_v3'); many policy columns with CHECK constraints; monitored_total / unreleased_count / snapshot_refreshed_at populated by the supervisor's snapshot refresh task |
cooldowns | Per-item search cooldown tracking | instance_id FK→instances ON DELETE CASCADE; UNIQUE(instance_id, item_id, item_type); search_kind CHECK IN ('missing','cutoff','upgrade') (v15) |
search_log | Audit trail | instance_id FK→instances ON DELETE SET NULL; action CHECK IN ('searched','skipped','error','info') |
Full DDL and migrations live in src/houndarr/database.py.
Rebuild migrations (CREATE TABLE foo_new ... INSERT INTO foo_new SELECT ...)
must reference a snapshot constant frozen at the introducing schema version,
never the current _ITEM_TYPES / _INSTANCE_TYPES alias. The snapshots
(_ITEM_TYPES_V5, _ITEM_TYPES_V10, _ITEM_TYPES_V15, _ITEM_TYPES_V16,
_INSTANCE_TYPES_V5, _INSTANCE_TYPES_V10) live at the top of database.py
and are immutable after their migration ships. Fresh-install DDL in
_SCHEMA_SQL uses the latest snapshot via the _ITEM_TYPES /
_INSTANCE_TYPES aliases.
When adding a migration that renames a value: introduce a new
_FOO_TYPES_VN constant, point the _FOO_TYPES alias at it, write the new
migration with the new constant plus a CASE WHEN translation in its COPY,
and leave the prior snapshot (and prior migrations) untouched. This prevents
the class of bug where a later rename retroactively breaks an earlier
rebuild migration's CHECK clause.
SCHEMA_VERSION at the top of database.py._migrate_to_vN(conn) function that performs the migration._FOO_TYPES_VN snapshot and reference it in the new migration._MIGRATIONS keyed by the new version._SCHEMA_SQL if the canonical fresh-install DDL changed.tests/test_database/ covering the migration path.