Applying the same change to a fleet is more than looping over connection strings. You need an exact target set, ordered steps, action tracking, locking, and an honest answer when the network fails after the server may have committed. pg-converter organizes that work as reviewed database operations. A SQL-only operation is a SQL change packet; Python steps, hooks, and exports extend the operation beyond SQL. The CLI retains packet in paths and option names for compatibility.

The payoff

A repeatable execution plan and durable pgc_* tracker replace hand-run scripts. Successful transactional actions are not repeated after reconnect, and ambiguous non-transactional outcomes stop for operator review instead of being guessed.

Real tasks it helps with

Fleet-wide schema change

Select explicit aliases, masks, or exclusions and apply the same versioned SQL change packet sequentially or asynchronously.

Repeatable DBA operation

Package index maintenance, object generation, grants, or inspection SQL with steps, placeholders, and per-action status.

Data and audit export

Run read-only queries or export operations and produce tab-separated files, ZIP, or optional AES ZIP artifacts.

Interrupted rollout recovery

Inspect run, step, action, and lock state before deciding whether a failed or disconnected operation is safe to continue.

Execution model

From reviewed operation source to tracked actions
packets/release_42/  # operation source; selected with --packet-name
  meta_data.json
  run_once.sql
  01_step.sql
  02_gen_obj.sql --> 02_step.sql
  03_step.py
        |
        v
resolve aliases + placeholders + checksums
        |
        +------ db_a ------> pgc_packets / steps / actions
        +------ db_b ------> pgc_packets / steps / actions
        `------ db_c ------> pgc_packets / steps / actions

confirmed transactional action + tracker row commit atomically

Execution modes

Mode Use it for Important behavior
default Normal tracked transactional changes Action and tracker state commit together
read_only Inspection and audit queries Transaction is constrained to read-only work
no_commit Exercise SQL while rolling the transaction back Useful for validation, not a universal dry-run
maintenance Commands that cannot run in a normal transaction Unknown outcomes require operator inspection
export_data Tracked query-to-file workflows CSV/ZIP/AES ZIP output options
Parallel / --seq Independent fleet speed or conservative ordering The same reviewed operation contract and per-database tracker

Resolve targets before execution

# Review the exact SQL change packet and target selection without connecting:
pg-converter \
  --config-file /etc/pg_converter/pg_converter.conf \
  --packet-name release_42 \
  --db-name 'prod_*,exclude:prod_old' \
  --plan > release_42.plan.json

# Execute the reviewed selection conservatively:
pg-converter \
  --config-file /etc/pg_converter/pg_converter.conf \
  --packet-name release_42 \
  --db-name 'prod_*,exclude:prod_old' \
  --seq

Know the boundary

pg-converter is an operations runner, not yet a complete migration-lifecycle system: it does not provide a project-wide migration ledger, target version, automatic rollback, baseline/repair workflow, or proof that arbitrary SQL is reversible. SQL change packets and operations containing Python steps, placeholders, hooks, or exports are trusted inputs and separate security boundaries.

GitHub repository ↗ PyPI package ↗