manage-sqlite-migrations

Manage SQLite Migrations

Produce a committed Drizzle migration that succeeds both from an empty database and from a representative snapshot without modifying the user's real rudder.db.

Preserve the safety boundary

• Treat src/db/schema.ts as the declarative schema and committed folders under drizzle/ as the runtime history.
• Never run migration experiments against the real database. openDb() applies pending migrations automatically, so do not point application code at the real RUDDER_HOME while authoring a migration.
• Never use drizzle-kit push; generate a migration file and review its SQL.
• Treat migrations already present on origin/main as immutable. Add a forward migration instead of rewriting published history.
• Do not delete data, drop schema objects, or replace the real database unless the user explicitly authorized that destructive outcome.
• Do not edit almanac/ during ordinary migration work. Use it as read-only context unless the user invokes a CodeAlmanac maintenance workflow.

Follow the workflow

1. Inspect .agentsignore, git status, src/db/schema.ts, src/db/client.ts, drizzle.config.ts, the current drizzle/ history, and migration tests. Search CodeAlmanac for the affected database files or concept when architectural context is relevant.

2. Before changing shared database infrastructure, run the repository baseline:

   npm run typecheck
   npm test
   npm run build
   

   Install dependencies first when node_modules/ is absent. Report pre-existing failures before continuing.

3. State the intended schema and data invariants. Classify the change as additive, data-transforming, or destructive. For a destructive change, preserve required data in a new shape before removing the old shape; stop for user approval when data loss was not explicitly requested.

4. Edit src/db/schema.ts, then generate a named migration:

   npm run db:generate -- --name <short-kebab-name>