# DB Migrate

> Step 0 — Load configuration

- Skill: `weorbitant/db-migrate` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add weorbitant/db-migrate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/weorbitant/db-migrate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: weorbitant (https://skillmd.com/u/weorbitant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/weorbitant/db-migrate

---


## Step 0 — Load configuration

Check if `/tmp/ops-suite-session/config.json` exists:
- If yes, read it (pre-parsed by session-start hook).
- If no, read `${XDG_CONFIG_HOME:-$HOME/.config}/ops-suite/config.yaml` (preferred) or the plugin's `config.yaml` (legacy), parse it, and write to `/tmp/ops-suite-session/config.json` for other skills to reuse.
If neither exists, tell the user to run `/ops-suite:configure` (or copy `config.example.yaml` to `~/.config/ops-suite/config.yaml` and fill in their values). Stop here.

Extract:
- `deploy.migration_tool` — determines which adapter to load
- `deploy.migration_command` — the command to run migrations
- `deploy.local_ports` — local ports for port-forwarding to databases
- `orchestrator` — for port-forward commands
- `environments` — connection details for each environment

Also read the reference at `references/commands.md` (in this skill's directory).

## Step 1 — Load adapter

Read the adapter file at `adapters/{deploy.migration_tool}.md` (in this skill's directory).
If the adapter does not exist, tell the user that the migration tool `{deploy.migration_tool}` is not yet supported and stop.

## Step 2 — Determine target environment

If `$ARGUMENTS` contains an environment name, use it. Otherwise ask the user.

**IMPORTANT: Always recommend running migrations on dev first before prod.**

## Step 3 — Identify pending migrations

Use the adapter's "list pending" command to check what migrations need to run.
If there are no pending migrations, inform the user and stop.

Show the user:
- Migration file names
- What each migration does (read the migration files if accessible)

## Step 4 — Establish database connection

The migration tool needs a database connection. This typically requires:

1. **Port-forward** to the database using the orchestrator:
   ```
   kubectl --context={env.context} port-forward svc/{env.services.database.name} {deploy.local_ports.{env_name}}:{env.services.database.port} -n {env.services.database.namespace || env.namespaces.infra} &
   ```
   Note: Use `env.services.database.namespace` if defined — the database/pgbouncer may live in a
   different namespace than `env.namespaces.infra`.

2. **Credentials**: First check if `env.services.database.credentials_from` is defined in config:
   - If `pod_env:<VAR_NAME>`: retrieve from a running app pod:
     ```
     kubectl --context={env.context} exec {any_app_pod} -n {env.namespaces.apps} -- printenv <VAR_NAME>
     ```
   - Otherwise, use the adapter's "retrieve secret" command or ask the user.
   Never hardcode or display credentials in plain text.

3. **Set environment variables** as required by the migration tool (from adapter).

4. **Determine database name**: If `service_databases` is defined in config, use it to resolve
   the correct database name for the target service and environment. Otherwise fall back to
   `env.services.database.default_db`.

## Step 5 — Confirm migration

**ALWAYS ask for explicit confirmation before running migrations.**

Display:
```
Ready to migrate:
  Environment: {env_name}
  Database:    {env.services.database.default_db}
  Pending:     {count} migration(s)
  Files:       {migration_file_list}

This will modify the database schema. Proceed? (yes/no)
```

## Step 6 — Run migrations

Execute the migration command from `deploy.migration_command` or the adapter's default command.
Capture both stdout and stderr.

## Step 7 — Verify

After migration completes:
1. Use the adapter's "check status" command to verify all migrations are applied
2. Run a quick sanity query to confirm the database is accessible
3. Check for any error output

## Step 8 — Cleanup

1. Kill any port-forward processes
2. Unset any temporary environment variables
3. Report the result

## Output format

```
Migration Summary:
  Environment: {env_name}
  Database:    {database}
  Migrations:  {count} applied
  Status:      {success/failed}

Applied:
  - {migration_name_1}
  - {migration_name_2}

Cleanup:
  - Port-forward killed (PID {pid})
```