apply-migrations - SKILL.md Agent Skill

name: apply-migrations description: Apply pending database migrations (rockhopper up) disable-model-invocation: true argument-hint: [config_file]

Apply pending migrations using rockhopper.

Steps

If $ARGUMENTS is provided, use it as the config file path. Otherwise, find all rockhopper_*.yaml config files and ask the user which one to use.
Run:
```
rockhopper --config <config_file> up
```
Report the result.

Handling out-of-order migrations

If up fails with an "out-of-order migrations detected" error, it means a pending migration has a lower version than one that is already applied (common after merging parallel branches). Do not blindly re-run with --allow-out-of-order. Instead:

Show the user the offending migration(s) from the error.
Explain the two options:
- Renumber the new migration above the latest applied version (safe default — keeps history linear).
- Apply in place with rockhopper --config <config_file> up --allow-out-of-order, only if the older migration is independent of the newer ones.
Ask the user which they prefer before proceeding.

Environment variable overrides

If the user needs to override the DSN or driver, remind them they can set:

ROCKHOPPER_DRIVER - database driver name
ROCKHOPPER_DIALECT - SQL dialect name; one of postgres, mysql, sqlite3, tidb, redshift, clickhouse
ROCKHOPPER_DSN - data source name connection string

Dialect notes

All listed dialects support schema migrations (up/down/status). Data migrations (the lease-based backfill API) require conditional UPDATE ... RETURNING RowsAffected==1 semantics and are therefore not supported on ClickHouse, which is capability-gated and returns ErrDataMigrationUnsupported.