Migration

Before you start

• Read docs/PROVENANCE.md for the compatibility map.
• Read docs/BRAND_GOVERNANCE.md for the naming policy.
• Back up your existing PostgreSQL database before running any migration.

Step 1 · Export a snapshot from the source system

The self-service migration tool is opskeeper-migrate (cmd/opskeeper-migrate). It supports 9 entity types with idempotent writes, rollback, rate limiting, and tenant isolation.

go build -o opskeeper-migrate ./cmd/opskeeper-migrate

opskeeper-migrate export \
  --source "$OPSKEEPER_OLD_URL" \
  --output ./snapshot.json

Step 2 · Import into OpsKeeper

opskeeper-migrate import \
  --source ./snapshot.json \
  --target "$OPSKEEPER_NEW_URL" \
  --tenant-mapping "$TENANT_MAP"

Step 3 · Verify source vs target

The verify subcommand diffs the exported snapshot against the target per entity and reports drift (optionally as an HTML report). Expect zero mismatches before cutover.

opskeeper-migrate verify \
  --source ./snapshot.json \
  --target "$OPSKEEPER_NEW_URL" \
  --tenant-mapping "$TENANT_MAP" \
  --report ./verify-report.html

Rollback

Every import is recorded. Undo a migration with the rollback snapshot the import wrote:

opskeeper-migrate rollback \
  --rollback-snapshot ./rollback-20260911.json \
  --target "$OPSKEEPER_NEW_URL"

List the supported entity types any time with opskeeper-migrate list-entities.

Help

File an issue at github.com/vincent-wuhan/opskeeper/issues with the migration label and the output of opskeeper-migrate --help.