Getting Started

Getting Started

Requirements

• .NET 10 SDK
• PostgreSQL client tools: pg_dump and pg_restore installed and on PATH
• Access to source and target PostgreSQL databases

Installation

Clone the repository and build:

git clone <repo-url>
cd database-migrator-and-sanitizer
dotnet build src/DbMigrator

Configuration

Copy the example config and fill in your database details:

cp config.example.yaml config.yaml

Minimum required fields:

migration:
  source:
    host: "source-db.example.com"
    port: 5432
    database: "production"
    user: "postgres"
    password: "${SOURCE_DB_PASSWORD}"
  target:
    host: "target-db.example.com"
    port: 5432
    database: "staging"
    user: "postgres"
    password: "${TARGET_DB_PASSWORD}"

sanitize: []

Passwords can be injected via environment variables using ${VAR_NAME} syntax.

Database Permissions

db-migrator runs as a dedicated database user. Before the first migration, grant the minimum required privileges on both databases (connect as a superuser, e.g. postgres).

Source DB — read-only (for pg_dump)

GRANT CONNECT ON DATABASE "your-source-db" TO "db-migrator";
GRANT pg_read_all_data TO "db-migrator";

pg_read_all_data (PostgreSQL 14+) covers SELECT on all tables, views, sequences and foreign tables — present and future. It is the only grant needed for pg_dump to read every object in the schema.

Target DB — read-write (for pg_restore and sanitize)

GRANT CONNECT ON DATABASE "your-target-db" TO "db-migrator";
GRANT pg_write_all_data TO "db-migrator";
GRANT CREATE ON DATABASE "your-target-db" TO "db-migrator";
GRANT ALL ON SCHEMA public TO "db-migrator";

CREATE ON DATABASE and ALL ON SCHEMA public are required because pg_restore --clean drops and recreates tables, indexes, sequences and constraints from scratch.

Run these grants as a superuser via psql or your cloud provider's console (e.g. Cloud SQL Studio / RDS Query Editor).

---

First Run

# Validate config and schema against source DB
SOURCE_DB_PASSWORD=... TARGET_DB_PASSWORD=... \
  dotnet run --project src/DbMigrator -- validate --config config.yaml

# Preview the migration and sanitization SQL (no changes made)
SOURCE_DB_PASSWORD=... TARGET_DB_PASSWORD=... \
  dotnet run --project src/DbMigrator -- run --config config.yaml --dry-run

# Run the full pipeline
SOURCE_DB_PASSWORD=... TARGET_DB_PASSWORD=... \
  dotnet run --project src/DbMigrator -- run --config config.yaml

Or publish a self-contained binary and run it directly:

dotnet publish src/DbMigrator -c Release -o out/
./out/DbMigrator run --config config.yaml

Recommended Workflow

1. Write config.yaml with sanitization rules
2. Run validate — fix any schema mismatches
3. Run run --preflight-only — confirm connectivity and DB privileges
4. Run run --dry-run — review the generated SQL
5. Run run — execute

See CLI Commands for all options and Configuration for the full config reference.