# Archestra Dev Migrations

> Archestra Dev Migrations is an Agent Skill for development published in the archestra-ai/archestra repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

- Skill name: `archestra-dev-migrations`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/archestra-ai/archestra/blob/HEAD/.claude/skills/archestra-dev-migrations/SKILL.md
- Repository: archestra-ai/archestra (3,971 GitHub stars when collected)

## SKILL.md

# Archestra Database Migrations

Use this skill for migration work.

Run commands from `platform/` unless specifically instructed otherwise.

## 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

```bash
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:

1. Update the Drizzle schema files with the schema changes.
2. Run `pnpm db:generate`.
3. Add the data migration SQL to the generated file.
4. 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:

```bash
pnpm --dir backend exec drizzle-kit generate --custom --name=<descriptive-name>
```

Then add the SQL to the generated file and run:

```bash
pnpm --dir backend exec drizzle-kit check
```

## Database connection

PostgreSQL runs in Kubernetes when managed by Tilt.

```bash
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;`.

---

Source: https://www.openparable.com/skill/development/archestra-dev-migrations (OpenParable). Cite the canonical URL above.
