The Complete Production SOP: How to Deploy and Run Migra PostgreSQL Schema Diff & Declarative Migrations in Autonomous AI Agents

To make the skill discoverable across Cursor, Windsurf, Codex, and Claude Code, initialize the skills configuration directory within your repository or user agent root. Claude Code discovers nested skills in .claude/skills/ or ~/.agents/skills/, while Cursor and Windsurf ingest skills configured within .cursor/rules/ or the unified .agents/skills/ registry.

---
name: "postgres-schema-diff-migra"
description: "Generate safe, automated DDL migration scripts by diffing PostgreSQL database states."
metadata:
  author: "djrobstep"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "diff postgres schemas"
  - "generate ddl migration migra"
  - "declarative postgres migrations"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: true
  net_access: true
---

Migra requires two PostgreSQL connection strings: the target state (desired schema, e.g., local dev or migrations container) and the source state (current baseline, e.g., staging shadow database). Export these via standardized environment variables or inject them into an uncommitted .env.local file. Agents must read these variables from the environment rather than emitting raw password strings in chat traces.

#!/usr/bin/env bash
set -euo pipefail

if [ -f .env.local ]; then
  export $(grep -v '^#' .env.local | xargs)
fi

migra --unsafe "${SOURCE_DB_URL}" "${TARGET_DB_URL}" > migrations/pending_diff.sql

if [ ! -s migrations/pending_diff.sql ]; then
  echo "Schemas are in sync. No DDL generated."
  exit 0
fi

echo "Generated DDL migration in migrations/pending_diff.sql"

When working in Claude Code CLI, Cursor Composer, or Codex Desktop, use the specific trigger phrases defined in the SKILL.md frontmatter. Phrasing queries with 'diff postgres schemas' or 'generate ddl migration migra' guarantees the agent loads this specific SOP and bypasses hallucinated schema alteration strategies.

diff postgres schemas between local dev and the staging baseline database using migra. Store the output in migrations/20260330_add_user_preferences.sql and inspect for lock-inducing column defaults.

The skill mandates that the agent wrap all output DDL in a safe transaction block (BEGIN...COMMIT), validate syntax with sqlfluff, and dry-run the execution against an ephemeral PostgreSQL shadow container before reporting completion.

BEGIN;

-- Automated diff generated via migra
ALTER TABLE "public"."users" ADD COLUMN "preferences" jsonb DEFAULT '{}'::jsonb NOT NULL;
CREATE INDEX CONCURRENTLY IF NOT EXISTS "idx_users_preferences" ON "public"."users" USING gin ("preferences");

COMMIT;