agh-schema-migration

Apply numbered, registry-backed migrations to AGH SQLite databases.

182|8|Updated Apr 4, 2026
One-click install
npx skills add https://github.com/compozy/agh --skill agh-schema-migration
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: agh-schema-migration
Source: https://github.com/compozy/agh/tree/main/.agents/skills/agh/agh-schema-migration
Command: npx skills add https://github.com/compozy/agh --skill agh-schema-migration

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill prevents AGH database schema drift by forcing every SQLite schema change to go through a numbered, registry-backed migration with transactional safety and idempotence.

Core Features & Use Cases

  • Migration registry enforcement: Ensures schema changes are recorded and applied via the schema_migrations mechanism instead of fragile EnsureSchema-style reconciliation.
  • Transactional, idempotent DDL: Requires wrapping changes in BEGIN IMMEDIATE, guarding against re-application, and making operations resume safely after partial runs.
  • SQLite recovery hygiene: Verifies that when migrations touch SQLite recovery, the -wal and -shm companion files are renamed alongside the .db to avoid corruption and missing-column failures after restarts.
  • Test-driven migration correctness: Requires fresh-DB and reopen-after-restart tests to confirm schema expectations and data preservation/backfill behavior.

Quick Start

Use this skill when you are editing any AGH code path that issues SQLite DDL for persistent stores, and author a numbered migration that is registered, transactional, idempotent, recorded in schema_migrations, and covered by fresh DB and restart tests.

Frequently Asked Questions about agh-schema-migration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I safely migrate a SQLite schema in AGH without causing database corruption?

To safely migrate an AGH SQLite schema, apply numbered, registry-backed migrations using transactional BEGIN IMMEDIATE execution and idempotent guards to prevent partial run failures and database corruption.

What is the best way to prevent SQLite schema drift in AdGuard Home persistent stores?

Preventing SQLite schema drift in AdGuard Home requires recording every DDL change in a schema_migrations registry instead of using fragile EnsureSchema-style reconciliation, ensuring changes are tracked and applied consistently.

Why do I get missing column failures after restarting a SQLite migration involving WAL files?

Missing column failures after restarts happen because the -wal and -shm companion files were not renamed alongside the .db file, causing SQLite recovery behaviors to fail when reading the updated persistent scheduler stores.

How do I test SQLite schema migrations for idempotence and restart safety?

Testing SQLite schema migrations for idempotence requires running fresh-DB tests and reopen-after-restart tests to confirm schema expectations, verify data preservation, and ensure backfill behaviors survive partial execution.

When do I need to use a numbered migration registry instead of EnsureSchema for SQLite DDL?

You need a numbered migration registry instead of EnsureSchema when applying SQLite DDL changes to durable stores like agh.db or events.db, ensuring transactional safety and preventing out-of-band schema reconciliation.