| name | archestra-dev-migrations |
| description | Use when changing Drizzle schemas, generating migrations, editing migration SQL, creating data-only migrations, diagnosing drizzle-kit check failures, or resolving migration/generated-client conflicts. |
Archestra Database Migrations
Use this skill for migration work.
Run commands from platform/ unless specifically instructed otherwise.
Large / hot tables
If the migration touches the interactions table (or any other very large,
write-hot table), read archestra-dev-interactions-migrations first. A blocking
operation on that table stalls the LLM proxy's write path, and its most common
trap — rebuilding an index inside a transactional migration — cannot be made
concurrent. That skill covers safe vs risky operations and a read-only audit of
the staging table.
Merge/rebase conflicts
When git reports merge/rebase conflicts in Drizzle migration metadata or generated clients, follow resolve-conflicts.md instead of the normal migration flow.
That subpage overrides the default working directory rule and runs its procedure from the repo root where needed.
Common commands
pnpm db:generate
pnpm --dir backend exec drizzle-kit check
pnpm --dir backend check:migrations
pnpm db:migrate
pnpm db:studio
Ask before applying migrations locally if the command will modify database state. Generating migrations and checking consistency are safe.
Schema migrations
When creating migrations that include schema changes and data migration logic:
- Update the Drizzle schema files with the schema changes.
- Run
pnpm db:generate.
- Add the data migration SQL to the generated file.
- Run
pnpm --dir backend exec drizzle-kit check and pnpm --dir backend check:migrations
to verify consistency and journal ordering.
Drizzle creates a migration with a generated name such as 0119_military_alice.sql. Use that generated filename. Never create manually named migration files because Drizzle tracks migrations through backend/src/database/migrations/meta/_journal.json, which references generated file names.
Data migration SQL
Data migration SQL can include statements such as INSERT, UPDATE, and other data-changing statements inside the generated migration file.
Keep schema DDL before data migration statements when the data migration references newly created tables or columns.
Always verify with pnpm --dir backend exec drizzle-kit check and
pnpm --dir backend check:migrations after editing generated SQL.
Custom data-only migrations
For pure data migrations with no schema changes, create an empty custom migration tracked by Drizzle:
pnpm --dir backend exec drizzle-kit generate --custom --name=<descriptive-name>
Then add the SQL to the generated file and run:
pnpm --dir backend exec drizzle-kit check
Database connection
PostgreSQL runs in Kubernetes when managed by Tilt.
kubectl exec -n archestra-dev postgresql-0 -- env PGPASSWORD=archestra_dev_password psql -U archestra -d archestra_dev
Useful read-only inspection commands inside psql include \dt, \d table_name, and SELECT COUNT(*) FROM drizzle.__drizzle_migrations;.
