eng-schema-migration

Authors append-only Goose SQL migrations for Compozy SQLite streams with Atlas codegen.

2.7k|171|Updated Mar 28, 2026
One-click install
npx skills add https://github.com/compozy/compozy --skill eng-schema-migration
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: eng-schema-migration
Source: https://github.com/compozy/compozy/tree/main/.agents/skills/eng/eng-schema-migration
Command: npx skills add https://github.com/compozy/compozy --skill eng-schema-migration

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Changing SQLite schemas in Compozy requires keeping declarative schema sources, Goose migrations, Atlas checksums, sqlc output, and migration tests perfectly synchronized, and any drift or edited history can corrupt production databases.

Core Features & Use Cases

  • Append-only migration authoring: Classify the owning stream (global, memory, session, workspace), edit the declarative schema source, and let make codegen append the next gap-free Goose migration with refreshed atlas.sum.
  • Decision matrix and templates: Reference docs classify every change type (columns, indexes, constraints, seed data) and define the owner directory shape for schema sources and migrations.
  • Test contract enforcement: Canonical suites cover fresh apply, reopen with preserved data, ahead-version refusal, checksum drift, and migrations-to-declarative-schema equivalence.
  • Use Case: When adding a NOT NULL column to a table under internal/store, follow the procedure to update the declarative schema, run codegen, extend the owner test suite, and verify with make gate before pushing.

Quick Start

Ask the agent to add a new nullable column to a table in internal/store and generate the corresponding Goose migration with updated tests.

Frequently Asked Questions about eng-schema-migration

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

FAQPage Schema
How do I add a database migration in Compozy?

Edit the owning stream's declarative schema source (schema.sql or definitions fragments), then run make codegen. Atlas appends the next gap-free Goose SQL file, runs sqlcheck, refreshes atlas.sum, and regenerates sqlc output for review.

How do I add a NOT NULL column to an existing SQLite table?

A NOT NULL column requires a migration with a default expressible in SQL or a backfill in the same transaction. Add the column to the declarative source, run codegen, and add bounded data SQL only to the unpublished migration tail.

Can I edit or reorder an existing Goose migration file?

No. Existing migrations and their atlas.sum checksum entries must never be edited, renamed, renumbered, or deleted. A correction after publication is always a new appended migration.

What happens when the database schema version is ahead of the binary?

A recorded version above the embedded head is treated as schema_ahead and the open is refused. Prefer a newer compatible binary when state must be preserved; never mutate the database in place.

When does this migration workflow not apply?

It does not apply to in-memory cache shapes, derived Markdown memory such as internal/memory/MEMORY.md, or non-SQLite caches. Markdown is the source of truth there and the FTS5 catalog is derived via reindexing.