Back to docs
Operations

DynamoDB Migrations

Dagy ships a lightweight, versioned DynamoDB migration/backfill framework (`src/dagy_api/persistence/migrations/`) so schema/data changes are applied safely and repeatably — including from CD — instead of by hand.

Model

  • Each migration is a Migration subclass in a migration_XXXX_*.py module.
  • Applied migrations are recorded in a ledger table named by DAGY_MIGRATIONS_TABLE (default dagy-schema-migrations), so re-running is idempotent — already-applied versions are skipped.
  • Table names are read from the same environment variables used by the API.

CLI

Run via the module entrypoint (safe to run from CD):

# See what's pending / applied
python -m dagy_api.persistence.migrations status --env prod

# Dry-run: report actions without writing
python -m dagy_api.persistence.migrations run --env prod --dry-run

# Apply all pending migrations
python -m dagy_api.persistence.migrations run --env prod

# Apply up to (and including) a specific version
python -m dagy_api.persistence.migrations run --env prod --target <version>

# Machine-readable output for CI
python -m dagy_api.persistence.migrations status --env prod --json

Flags: --env (deployment label), --region, --dry-run, --target, --json.

Operational guidance

  • Always run status then run --dry-run before a real run in production.
  • The migration runner is the sanctioned tool for larger data reshapes — e.g. an org-scoped repartition, or the secrets re-encryption in the secrets-key rotation runbook.
  • All app tables have point-in-time recovery enabled, so a bad migration is recoverable via PITR (coordinate before restoring — it creates a new table).