Run any Skill in Manus with one click

houndarr-database

Stars250

Forks3

UpdatedMay 22, 2026 at 21:57

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.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

av1155

av1155/houndarr

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Database ArchitectsComputer and Mathematical Occupations·SOC 15-1243

SKILL.md

readonly

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"]

Houndarr database conventions

Database basics

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.

Schema reference

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.

Migration constants are version-locked

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 bump checklist

Bump SCHEMA_VERSION at the top of database.py.
Add a _migrate_to_vN(conn) function that performs the migration.
If the migration renames a value used in CHECK constraints, introduce a fresh _FOO_TYPES_VN snapshot and reference it in the new migration.
Add an entry to _MIGRATIONS keyed by the new version.
Update _SCHEMA_SQL if the canonical fresh-install DDL changed.
Add tests under tests/test_database/ covering the migration path.

More from this repository

same repository

houndarr-architecture

av1155/houndarr

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.

2026-05-22250

houndarr-changelog

av1155/houndarr

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.

2026-05-04250

houndarr-ci

av1155/houndarr

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.

2026-05-04250

houndarr-python

av1155/houndarr

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.

2026-05-04250

houndarr-testing

av1155/houndarr

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.

2026-05-04250

verify-algorithms

av1155/houndarr

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".

2026-05-04250

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"]

Houndarr database conventions

Database basics

Schema reference

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.

Migration constants are version-locked

Schema bump checklist

Bump SCHEMA_VERSION at the top of database.py.
Add a _migrate_to_vN(conn) function that performs the migration.
If the migration renames a value used in CHECK constraints, introduce a fresh _FOO_TYPES_VN snapshot and reference it in the new migration.
Add an entry to _MIGRATIONS keyed by the new version.
Update _SCHEMA_SQL if the canonical fresh-install DDL changed.
Add tests under tests/test_database/ covering the migration path.