db-cutover 0.2.0__tar.gz

db_cutover-0.2.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+
+# Run state (schema dumps, cutover reports) when a config lives in this repo, e.g. while testing
+.db_cutover/
+
+# Local operational inputs and outputs; committed examples use synthetic values.
+/cutover.toml
+*.local.toml
+.env
+.env.*
+*.tfstate
+*.tfstate.*
+*.tfplan
+*.log
+*.pem
+*.key

db_cutover-0.2.0/AGENTS.md

@@ -0,0 +1,49 @@
+# db-cutover
+
+`db-cutover`: a Python CLI for zero-downtime blue/green PostgreSQL cutovers on RDS (logical replication plus a
+PgBouncer switch). `README.md` covers use, `docs/procedure.md` the steps of a cutover, `docs/design.md` the
+reasoning. Read `SECURITY.md` before handling operational configuration or logs.
+
+## Layout
+
+- `src/db_cutover/cli.py`: argument parsing; one subcommand per step.
+- `config.py`: the TOML config (`examples/config.toml` documents every key; keep it in sync).
+- `db.py`: connections and catalog queries. `pgbouncer.py`: the admin console of every pod through
+  `kubectl port-forward`. `shell.py`: aws, kubectl, pg_dump, psql. `output.py`: log lines, checks, JSON.
+- `commands/`: `inspect.py` (read-only and long-running), `blue.py`, `replication.py`, `switch.py` (cutover,
+  finish), `terraform.py` (green-tf, promote-tf).
+- `skills/db-cutover/`: the [Agent Skill](https://agentskills.io/specification) for agents that operate the tool
+  (`SKILL.md` plus `references/`). The wheel includes it as `db_cutover/skills/db-cutover`, and `db-cutover skill`
+  prints or installs it. It is written for an agent running a cutover; this file is for an agent changing the code.
+
+## Rules
+
+- Every command that changes anything is a dry run unless `--execute` is passed. Keep it that way for new commands.
+- Never print a secret or a connection string that holds one. Secrets go to subprocesses through the environment
+  (`PGPASSWORD`), never the command line.
+- The switch (`commands/switch.py`) must resume on BLUE for any failure before RELOAD, including Ctrl-C. Don't add
+  steps between PAUSE and RESUME without measuring the pause on a staging run.
+- After RELOAD starts, never resume mixed or unknown targets. Report failed resumes as failures. A sequence gap
+  and one-way replication cannot make concurrent writers on BLUE and GREEN safe.
+- Probe writes, replication markers and manual RESUME require `--execute`, including retry paths.
+- Inspect all client roles when draining BLUE. A failed deployment lookup must not be interpreted as zero replicas.
+- Never print query text, server row diagnostics or a secret helper's stderr. Keep fixtures synthetic and review
+  all history before public release; removing a value from the current tree does not remove it from history.
+- Logic that can be pure (sequence planning, HCL edits, ini parsing) stays pure and has tests in `tests/`.
+- Long-running commands print one line per change, not per poll, so they work as background monitors.
+- Before committing: `uv run pytest`, `uv run ruff check .`, `uv run ruff format --check .` (CI runs the same).
+- When behaviour changes, update `README.md`, `docs/procedure.md`, `docs/design.md` and the skill in the same
+  commit. A new command needs a line in `skills/db-cutover/references/commands.md` (a test checks).
+- The skill's frontmatter has only `name`, `description`, `license` and `metadata`. Keep `SKILL.md` under 500
+  lines with the rules first, and write standing instructions for "you" (the agent) and "the operator".
+
+## Releasing
+
+1. Set the version in `pyproject.toml`, `src/db_cutover/__init__.py`, the skill's `metadata.version` and the
+   README's install command, run `uv lock`, and give `CHANGELOG.md` a `## <version> (<date>)` section. A test
+   checks that they agree.
+2. Merge to `main`, then tag that commit `v<version>` and push the tag.
+3. The `Release` workflow builds the package, checks the tag against the version, publishes to PyPI with trusted
+   publishing (no token: PyPI trusts this repository's `release.yml` in the `pypi` environment) and creates the
+   GitHub release from the changelog section. PyPI never accepts the same version twice, so a mistake needs a new
+   version.

db_cutover-0.2.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.2.0 (2026-11-16)
+
+The first release on PyPI.
+
+- Install with `uv tool install db-cutover` or `pipx install db-cutover`. `db-cutover --version` prints the version.
+- Add an agent skill (`skills/db-cutover`) for planning, rehearsing and running a cutover with an operator: each
+  command and its dry run, the stop points, the rehearsal checklist and recovery. It ships inside the package:
+  `db-cutover skill` prints its directory and `db-cutover skill --install DIR` copies it into an agent's skills
+  directory.
+- README: who the tool is for, a rehearsal walkthrough, and its guarantees and limits.
+- Stop and require recovery after a partial or unknown PgBouncer reload. Never resume mixed BLUE/GREEN targets.
+  Report failed resumes and post-switch verification failures with unsuccessful exit status.
+- Require `--execute` for `probe`, `wait-sync`, and `pgbouncer resume`. `verify` is read-only by default;
+  `verify --execute` adds a replication marker. Cutover and finish dry runs no longer write markers.
+- Remove `cutover --allow-direct`: every client role must drain before switching. Failed deployment lookups block
+  the operation. Reboot's separate `--allow-direct` option still explicitly permits direct-client errors.
+- Default to text replication. Validate publication coverage, subscription identity, sequence limits and marker
+  tokens. Reject unsupported data objects before switching.
+- Withhold PostgreSQL/subprocess/secret-helper diagnostics that may expose credentials or row values. Remove query
+  text and health response bodies from inspection output; keep state files in a private directory.
+- Bound port-forward startup and settle pending admin commands before confirming recovery from a late PAUSE.
+- Add synthetic fault tests, PostgreSQL 16-to-17 integration tests, an MIT license, standalone examples and an
+  expanded operator/agent runbook. Infrastructure and application rehearsals remain required before live use.

db_cutover-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DocSpring
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

db_cutover-0.2.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: db-cutover
+Version: 0.2.0
+Summary: Agent-friendly tools for zero-downtime blue/green PostgreSQL cutovers on RDS with logical replication and a PgBouncer switch
+Project-URL: Repository, https://github.com/DocSpring/db-cutover
+Project-URL: Changelog, https://github.com/DocSpring/db-cutover/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/DocSpring/db-cutover/issues
+Project-URL: Documentation, https://github.com/DocSpring/db-cutover/blob/main/docs/procedure.md
+Author-email: "DocSpring, Inc." <support@docspring.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: blue-green,logical-replication,pgbouncer,postgresql,rds,upgrade,zero-downtime
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: psycopg[binary]<4,>=3.2
+Description-Content-Type: text/markdown
+
+# db-cutover
+
+Upgrade a PostgreSQL database by copying it to a new instance, keeping that copy current with logical replication,
+and switching application traffic through PgBouncer. The application keeps using the old database during the copy.
+At the switch, PgBouncer holds new queries while in-flight transactions finish, then sends queued work to the new
+instance.
+
+`db-cutover` is the Python CLI that runs each step. It comes with an [example configuration](examples/config.toml),
+a [step-by-step procedure](docs/procedure.md), [design notes](docs/design.md) and an
+[agent skill](skills/db-cutover/SKILL.md). It is made for a human operator working with a coding agent: each command
+has a narrow purpose, and every command that changes database, infrastructure or PgBouncer state is a dry run until
+it gets `--execute`.
+
+**Release candidate:** failure-path tests and PostgreSQL replication tests do not replace a rehearsal on your
+application's RDS and PgBouncer deployment. Read the requirements below before planning a cutover.
+
+## Who it's for
+
+Teams that run PostgreSQL on RDS behind PgBouncer in Kubernetes and need a major version upgrade (or a move to a new
+instance) without a maintenance window. It suits you if:
+
+- you want to choose the moment of the switch and see every check before it, instead of handing the upgrade to a
+  managed service;
+- your application already connects through PgBouncer with transaction pooling, or can be made to;
+- someone on the team can provision an RDS instance and change a Kubernetes ConfigMap.
+
+It is not for databases older than PostgreSQL 16, setups without PgBouncer, or schemas that rely on large objects,
+materialized views, unlogged tables or foreign tables. For those, look at
+[RDS Blue/Green Deployments](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/blue-green-deployments.html) or
+`pg_upgrade` with a maintenance window.
+
+## Requirements
+
+- PostgreSQL **16 or newer**, running on RDS. BLUE is the existing primary; GREEN is a separate instance at the
+  target version. One database is migrated at a time. Test the specific source/target versions and extensions.
+- PgBouncer in Kubernetes, with transaction pooling. Every foreground database client must use the selected pods.
+  These commands pause/resume **all databases on those pods**, and RELOAD applies the entire configuration.
+  Use dedicated pods for this workflow.
+- A directory-mounted ConfigMap containing `pgbouncer.ini`, with no automatic reload. `subPath` mounts do not receive
+  ConfigMap updates. Prevent rollouts, scaling and automatic restarts during the prepared-config window; see the
+  [procedure](docs/procedure.md#7-prepare-and-switch).
+- All connections bypassing PgBouncer must be stopped and prevented from reconnecting during the switch. Inventory
+  consoles, schedulers, maintenance jobs, migrations and every application role, not just your web process.
+- A schema freeze from `copy-schema` through `finish`. Roles, grants, extensions, settings and other databases need
+  separate preparation. Large objects, unlogged tables, materialized views and foreign tables are blocked.
+- Sequences with `INCREMENT BY 1`, no cycling, sufficient capacity, and application code that tolerates gaps in IDs.
+- Request, proxy, job and PgBouncer timeouts longer than the measured pause. Queries wait during the switch;
+  **zero failed requests depends on those timeouts and successful recovery**. An RDS reboot can take much longer.
+
+## Install
+
+`db-cutover` needs Python 3.11 or newer. Install it as a standalone tool with [uv](https://docs.astral.sh/uv/) or
+[pipx](https://pipx.pypa.io/):
+
+```sh
+uv tool install db-cutover==0.2.0     # or: pipx install db-cutover==0.2.0
+db-cutover --version
+db-cutover --help
+```
+
+Pin the version and keep it fixed from the first rehearsal to the end of the migration. To run from source instead,
+clone the repository at a release tag and use its locked dependencies (`uv sync --frozen`, then `uv run db-cutover`).
+
+The machine running the tool also needs `aws`, `kubectl`, and matching, current `pg_dump`/`psql` clients at least as
+new as **both** database servers. `op` is optional for 1Password references; Terraform is optional for the two HCL
+helpers. It needs network access to both databases and the Kubernetes API. GREEN must reach BLUE for replication.
+
+Copy the [example](examples/config.toml) to a private working directory, fill in your identifiers and contexts,
+and supply credentials through environment variables or a secret manager. Never commit the operational config,
+schema dumps, reports, Terraform state or logs. `cmd:` secret references execute shell commands: treat configs as
+trusted executable input.
+
+## Working with an agent
+
+The package includes an [Agent Skill](https://agentskills.io/specification) that teaches a coding agent (Claude
+Code, Codex, Cursor and others) to plan, rehearse and run a cutover with you: what each command does, which ones
+need `--execute`, the rehearsal checklist, the points where it must stop for your decision, and recovery.
+
+```sh
+db-cutover skill --install .claude/skills    # or .agents/skills, or your agent's skills directory
+npx skills add DocSpring/db-cutover          # the same skill, straight from this repository
+```
+
+Give the agent the config path, the approved versions, the traffic controls and the limits of what it may execute.
+Have it run each changing command without `--execute` first, explain the output, and follow your agreed execution
+policy. A failed gate is a stop condition.
+
+Exit status 0 means the command completed its requested mode, 1 means failure, 2 means an argument/config error,
+and 130 means interruption. A dry-run success is not a completed migration. Long-running monitors continue until
+stopped; quiet output alone is not proof that a monitor is still alive.
+
+## Workflow
+
+Read [the procedure](docs/procedure.md) for the provisioning, permissions, traffic controls and recovery steps
+between these commands. In the examples below, `C` is a private config path and `TARGET_VERSION` is the RDS engine
+version you have selected and tested. Prefix commands with `uv run` if you run from a source checkout.
+
+```sh
+db-cutover "$C" preflight
+# Enable logical replication; reboot-blue --execute only if the static parameter needs it.
+db-cutover "$C" prepare-blue --execute
+db-cutover "$C" green-tf --engine-version "$TARGET_VERSION" --execute
+# Review and provision GREEN, including version-compatible parameters and network access.
+db-cutover "$C" copy-schema --execute
+# Create application roles, grants and required extensions on GREEN.
+db-cutover "$C" start-replication --execute
+db-cutover "$C" wait-sync --execute
+db-cutover "$C" verify --execute
+db-cutover "$C" sequences --execute
+# Stop and fence direct writers before the rehearsal.
+db-cutover "$C" cutover --execute --rehearse
+# Prepare PgBouncer's config as described in the procedure, without reloading it.
+db-cutover "$C" cutover
+db-cutover "$C" cutover --execute
+# Move direct writers to GREEN and prevent any application writes to BLUE.
+db-cutover "$C" finish --execute
+db-cutover "$C" promote-tf --execute
+# Review and run the printed state moves, then verify the Terraform plan.
+```
+
+If health endpoints require authentication, set `[secrets] health_check_token`; `watch` sends it as
+`X-Health-Check-Token` to every configured health URL. Only configure trusted HTTPS endpoints. Redirects are reported
+as failures rather than followed, so the header cannot be forwarded to a different endpoint.
+
+Use `watch` to monitor health/replication and `probe --execute` to write synthetic probe rows through PgBouncer.
+Start the probe after `prepare-blue`; stop it before `finish` drops its table. `verify` without `--execute` is
+read-only; `--execute` adds a marker write to test replication. Dry runs can connect, read data, create local state
+files, and consume database resources. They do not pause clients or modify remote state.
+
+## Rehearse first
+
+Rehearse twice: the whole procedure on staging, then the pause on production.
+
+1. **Build a staging setup that matches production** where it matters: the same PgBouncer image, pool mode and
+   ConfigMap mount, the same PostgreSQL source and target versions and extensions, and the application with its
+   real timeouts. Put traffic on it.
+2. **Run every step there, including a real switch**, with `watch` and `probe --execute` running. Write down how
+   long the copy took, how much WAL BLUE kept, and the pause the switch reports.
+3. **Cause the failures on purpose.** Leave a direct writer connected, hold a transaction open on BLUE, press
+   Ctrl-C during a rehearsal's pause, restart a PgBouncer pod after the ConfigMap names GREEN. Each one should stop
+   the switch and leave traffic on BLUE. Practise the [recovery steps](docs/procedure.md#recovery) for the last one.
+4. **On production, rehearse the pause** once replication has caught up and the direct writers are stopped:
+
+   ```sh
+   db-cutover "$C" cutover --execute --rehearse
+   ```
+
+   This pauses live traffic, runs every check the real switch runs, and resumes on BLUE. Its report gives the pause
+   in milliseconds. Compare it with every timeout in the request path before you go on.
+
+`--rehearse` never reloads PgBouncer, so only the staging switch tests RELOAD, GREEN under the application and
+recovery from a partial switch. The skill's
+[rehearsal checklist](skills/db-cutover/references/rehearsal.md) lists each thing to check and record.
+
+## Guarantees and limits
+
+What the tool does:
+
+- **Nothing changes without `--execute`.** A dry run reads, checks and reports. It can connect, read data, create
+  local state files and use database resources, but it never pauses clients or changes remote state.
+- **No switch without proof that GREEN is current.** With every PgBouncer pod paused, the tool checks that no
+  client session is left on BLUE, writes a marker on BLUE and waits for it on GREEN, and compares the highest ID of
+  every table before any pod reloads.
+- **A failure before RELOAD leaves BLUE as primary.** The tool resumes traffic on BLUE, including on Ctrl-C, and
+  reports a resume it could not confirm.
+- **It never resumes pods that point at different databases.** After RELOAD starts, mixed or unknown targets
+  **remain paused** and the command fails. An operator aligns every pod to GREEN before resuming.
+- **It keeps secrets and row data out of its output.** PostgreSQL diagnostics, query text and health response
+  bodies are withheld. State files go in a private directory.
+
+What it can't do:
+
+- **Promise zero failed requests.** Queries wait during the pause. Requests succeed only if every timeout in their
+  path is longer than the pause and recovery works. An RDS reboot can take much longer than a switch.
+- **Fence clients it doesn't know about.** Anything that connects without PgBouncer has to be stopped and kept
+  away by you. The tool checks for sessions; it can't prevent new ones.
+- **Close the window between the ConfigMap change and the switch.** A PgBouncer pod restarted in that window
+  serves GREEN early. The tool detects it before switching but can't stop it.
+- **Go back to BLUE once GREEN has taken writes.** Replication runs one way. Never read replication or a sequence
+  gap as permission to write to both databases. After the switch, fix forward on GREEN.
+- **Survive its own process being killed.** After SIGKILL or a lost connection during a switch, an operator has to
+  read the state from the pods.
+- **Prove the data is identical.** `verify` compares schemas, counts and sampled rows. It is not a full comparison.
+- **Copy everything.** Roles, grants, extensions, database settings and other databases need separate preparation.
+  Sequence values are advanced, not replicated.
+
+The [design notes](docs/design.md) give the reasoning, and [SECURITY.md](SECURITY.md) the limits of the tests.
+
+## Development
+
+```sh
+uv sync --frozen --group dev
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+The default suite uses no cloud credentials. [Integration tests](tests/integration/README.md) use disposable
+PostgreSQL 16 and 17 containers with synthetic data. CI runs both suites. See [SECURITY.md](SECURITY.md) for data
+handling and release checks, and [AGENTS.md](AGENTS.md) for the code's rules and how to release.
+
+Built by [DocSpring](https://docspring.com). Licensed under [MIT](LICENSE).

db_cutover-0.2.0/README.md

@@ -0,0 +1,203 @@
+# db-cutover
+
+Upgrade a PostgreSQL database by copying it to a new instance, keeping that copy current with logical replication,
+and switching application traffic through PgBouncer. The application keeps using the old database during the copy.
+At the switch, PgBouncer holds new queries while in-flight transactions finish, then sends queued work to the new
+instance.
+
+`db-cutover` is the Python CLI that runs each step. It comes with an [example configuration](examples/config.toml),
+a [step-by-step procedure](docs/procedure.md), [design notes](docs/design.md) and an
+[agent skill](skills/db-cutover/SKILL.md). It is made for a human operator working with a coding agent: each command
+has a narrow purpose, and every command that changes database, infrastructure or PgBouncer state is a dry run until
+it gets `--execute`.
+
+**Release candidate:** failure-path tests and PostgreSQL replication tests do not replace a rehearsal on your
+application's RDS and PgBouncer deployment. Read the requirements below before planning a cutover.
+
+## Who it's for
+
+Teams that run PostgreSQL on RDS behind PgBouncer in Kubernetes and need a major version upgrade (or a move to a new
+instance) without a maintenance window. It suits you if:
+
+- you want to choose the moment of the switch and see every check before it, instead of handing the upgrade to a
+  managed service;
+- your application already connects through PgBouncer with transaction pooling, or can be made to;
+- someone on the team can provision an RDS instance and change a Kubernetes ConfigMap.
+
+It is not for databases older than PostgreSQL 16, setups without PgBouncer, or schemas that rely on large objects,
+materialized views, unlogged tables or foreign tables. For those, look at
+[RDS Blue/Green Deployments](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/blue-green-deployments.html) or
+`pg_upgrade` with a maintenance window.
+
+## Requirements
+
+- PostgreSQL **16 or newer**, running on RDS. BLUE is the existing primary; GREEN is a separate instance at the
+  target version. One database is migrated at a time. Test the specific source/target versions and extensions.
+- PgBouncer in Kubernetes, with transaction pooling. Every foreground database client must use the selected pods.
+  These commands pause/resume **all databases on those pods**, and RELOAD applies the entire configuration.
+  Use dedicated pods for this workflow.
+- A directory-mounted ConfigMap containing `pgbouncer.ini`, with no automatic reload. `subPath` mounts do not receive
+  ConfigMap updates. Prevent rollouts, scaling and automatic restarts during the prepared-config window; see the
+  [procedure](docs/procedure.md#7-prepare-and-switch).
+- All connections bypassing PgBouncer must be stopped and prevented from reconnecting during the switch. Inventory
+  consoles, schedulers, maintenance jobs, migrations and every application role, not just your web process.
+- A schema freeze from `copy-schema` through `finish`. Roles, grants, extensions, settings and other databases need
+  separate preparation. Large objects, unlogged tables, materialized views and foreign tables are blocked.
+- Sequences with `INCREMENT BY 1`, no cycling, sufficient capacity, and application code that tolerates gaps in IDs.
+- Request, proxy, job and PgBouncer timeouts longer than the measured pause. Queries wait during the switch;
+  **zero failed requests depends on those timeouts and successful recovery**. An RDS reboot can take much longer.
+
+## Install
+
+`db-cutover` needs Python 3.11 or newer. Install it as a standalone tool with [uv](https://docs.astral.sh/uv/) or
+[pipx](https://pipx.pypa.io/):
+
+```sh
+uv tool install db-cutover==0.2.0     # or: pipx install db-cutover==0.2.0
+db-cutover --version
+db-cutover --help
+```
+
+Pin the version and keep it fixed from the first rehearsal to the end of the migration. To run from source instead,
+clone the repository at a release tag and use its locked dependencies (`uv sync --frozen`, then `uv run db-cutover`).
+
+The machine running the tool also needs `aws`, `kubectl`, and matching, current `pg_dump`/`psql` clients at least as
+new as **both** database servers. `op` is optional for 1Password references; Terraform is optional for the two HCL
+helpers. It needs network access to both databases and the Kubernetes API. GREEN must reach BLUE for replication.
+
+Copy the [example](examples/config.toml) to a private working directory, fill in your identifiers and contexts,
+and supply credentials through environment variables or a secret manager. Never commit the operational config,
+schema dumps, reports, Terraform state or logs. `cmd:` secret references execute shell commands: treat configs as
+trusted executable input.
+
+## Working with an agent
+
+The package includes an [Agent Skill](https://agentskills.io/specification) that teaches a coding agent (Claude
+Code, Codex, Cursor and others) to plan, rehearse and run a cutover with you: what each command does, which ones
+need `--execute`, the rehearsal checklist, the points where it must stop for your decision, and recovery.
+
+```sh
+db-cutover skill --install .claude/skills    # or .agents/skills, or your agent's skills directory
+npx skills add DocSpring/db-cutover          # the same skill, straight from this repository
+```
+
+Give the agent the config path, the approved versions, the traffic controls and the limits of what it may execute.
+Have it run each changing command without `--execute` first, explain the output, and follow your agreed execution
+policy. A failed gate is a stop condition.
+
+Exit status 0 means the command completed its requested mode, 1 means failure, 2 means an argument/config error,
+and 130 means interruption. A dry-run success is not a completed migration. Long-running monitors continue until
+stopped; quiet output alone is not proof that a monitor is still alive.
+
+## Workflow
+
+Read [the procedure](docs/procedure.md) for the provisioning, permissions, traffic controls and recovery steps
+between these commands. In the examples below, `C` is a private config path and `TARGET_VERSION` is the RDS engine
+version you have selected and tested. Prefix commands with `uv run` if you run from a source checkout.
+
+```sh
+db-cutover "$C" preflight
+# Enable logical replication; reboot-blue --execute only if the static parameter needs it.
+db-cutover "$C" prepare-blue --execute
+db-cutover "$C" green-tf --engine-version "$TARGET_VERSION" --execute
+# Review and provision GREEN, including version-compatible parameters and network access.
+db-cutover "$C" copy-schema --execute
+# Create application roles, grants and required extensions on GREEN.
+db-cutover "$C" start-replication --execute
+db-cutover "$C" wait-sync --execute
+db-cutover "$C" verify --execute
+db-cutover "$C" sequences --execute
+# Stop and fence direct writers before the rehearsal.
+db-cutover "$C" cutover --execute --rehearse
+# Prepare PgBouncer's config as described in the procedure, without reloading it.
+db-cutover "$C" cutover
+db-cutover "$C" cutover --execute
+# Move direct writers to GREEN and prevent any application writes to BLUE.
+db-cutover "$C" finish --execute
+db-cutover "$C" promote-tf --execute
+# Review and run the printed state moves, then verify the Terraform plan.
+```
+
+If health endpoints require authentication, set `[secrets] health_check_token`; `watch` sends it as
+`X-Health-Check-Token` to every configured health URL. Only configure trusted HTTPS endpoints. Redirects are reported
+as failures rather than followed, so the header cannot be forwarded to a different endpoint.
+
+Use `watch` to monitor health/replication and `probe --execute` to write synthetic probe rows through PgBouncer.
+Start the probe after `prepare-blue`; stop it before `finish` drops its table. `verify` without `--execute` is
+read-only; `--execute` adds a marker write to test replication. Dry runs can connect, read data, create local state
+files, and consume database resources. They do not pause clients or modify remote state.
+
+## Rehearse first
+
+Rehearse twice: the whole procedure on staging, then the pause on production.
+
+1. **Build a staging setup that matches production** where it matters: the same PgBouncer image, pool mode and
+   ConfigMap mount, the same PostgreSQL source and target versions and extensions, and the application with its
+   real timeouts. Put traffic on it.
+2. **Run every step there, including a real switch**, with `watch` and `probe --execute` running. Write down how
+   long the copy took, how much WAL BLUE kept, and the pause the switch reports.
+3. **Cause the failures on purpose.** Leave a direct writer connected, hold a transaction open on BLUE, press
+   Ctrl-C during a rehearsal's pause, restart a PgBouncer pod after the ConfigMap names GREEN. Each one should stop
+   the switch and leave traffic on BLUE. Practise the [recovery steps](docs/procedure.md#recovery) for the last one.
+4. **On production, rehearse the pause** once replication has caught up and the direct writers are stopped:
+
+   ```sh
+   db-cutover "$C" cutover --execute --rehearse
+   ```
+
+   This pauses live traffic, runs every check the real switch runs, and resumes on BLUE. Its report gives the pause
+   in milliseconds. Compare it with every timeout in the request path before you go on.
+
+`--rehearse` never reloads PgBouncer, so only the staging switch tests RELOAD, GREEN under the application and
+recovery from a partial switch. The skill's
+[rehearsal checklist](skills/db-cutover/references/rehearsal.md) lists each thing to check and record.
+
+## Guarantees and limits
+
+What the tool does:
+
+- **Nothing changes without `--execute`.** A dry run reads, checks and reports. It can connect, read data, create
+  local state files and use database resources, but it never pauses clients or changes remote state.
+- **No switch without proof that GREEN is current.** With every PgBouncer pod paused, the tool checks that no
+  client session is left on BLUE, writes a marker on BLUE and waits for it on GREEN, and compares the highest ID of
+  every table before any pod reloads.
+- **A failure before RELOAD leaves BLUE as primary.** The tool resumes traffic on BLUE, including on Ctrl-C, and
+  reports a resume it could not confirm.
+- **It never resumes pods that point at different databases.** After RELOAD starts, mixed or unknown targets
+  **remain paused** and the command fails. An operator aligns every pod to GREEN before resuming.
+- **It keeps secrets and row data out of its output.** PostgreSQL diagnostics, query text and health response
+  bodies are withheld. State files go in a private directory.
+
+What it can't do:
+
+- **Promise zero failed requests.** Queries wait during the pause. Requests succeed only if every timeout in their
+  path is longer than the pause and recovery works. An RDS reboot can take much longer than a switch.
+- **Fence clients it doesn't know about.** Anything that connects without PgBouncer has to be stopped and kept
+  away by you. The tool checks for sessions; it can't prevent new ones.
+- **Close the window between the ConfigMap change and the switch.** A PgBouncer pod restarted in that window
+  serves GREEN early. The tool detects it before switching but can't stop it.
+- **Go back to BLUE once GREEN has taken writes.** Replication runs one way. Never read replication or a sequence
+  gap as permission to write to both databases. After the switch, fix forward on GREEN.
+- **Survive its own process being killed.** After SIGKILL or a lost connection during a switch, an operator has to
+  read the state from the pods.
+- **Prove the data is identical.** `verify` compares schemas, counts and sampled rows. It is not a full comparison.
+- **Copy everything.** Roles, grants, extensions, database settings and other databases need separate preparation.
+  Sequence values are advanced, not replicated.
+
+The [design notes](docs/design.md) give the reasoning, and [SECURITY.md](SECURITY.md) the limits of the tests.
+
+## Development
+
+```sh
+uv sync --frozen --group dev
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+The default suite uses no cloud credentials. [Integration tests](tests/integration/README.md) use disposable
+PostgreSQL 16 and 17 containers with synthetic data. CI runs both suites. See [SECURITY.md](SECURITY.md) for data
+handling and release checks, and [AGENTS.md](AGENTS.md) for the code's rules and how to release.
+
+Built by [DocSpring](https://docspring.com). Licensed under [MIT](LICENSE).

db_cutover-0.2.0/SECURITY.md

@@ -0,0 +1,41 @@
+# Security and operational data
+
+This tool operates with administrative database and infrastructure access. Follow your organization's change
+authorization policy. A successful dry run is not authorization to execute a production change.
+
+## Private inputs and output
+
+- Keep operational TOML files outside the source repository. Use environment variables or a secret manager,
+  never literal credentials in config or on a command line. `cmd:` references execute shell commands; configs,
+  Terraform settings and schema dumps are trusted executable inputs, not safe inputs from strangers.
+- Keep schema dumps, reports, Terraform state/plans and logs private. Schema functions and comments can contain
+  secrets even without table rows. The state directory uses mode 0700.
+- PostgreSQL diagnostics and subprocess error output are withheld because they can contain SQL, credentials and
+  row values. Inspect failures privately. Session inspection excludes query text; health monitoring omits response
+  bodies. Identifiers, URLs, Terraform dry-run output and reports may still contain operator-supplied private data.
+- PostgreSQL stores the subscription's connection information. Administrators and some server logging settings can
+  expose it. Review logging before creating a subscription with a password.
+- Database connections use `sslmode=require`, which encrypts without verifying hostname identity. Restrict access
+  and use trusted networks. PgBouncer admin connections use local Kubernetes port-forwards and `sslmode=prefer`.
+  Certificate verification is not configured by this CLI.
+
+Never attach live config, Terraform state, schema dumps, connection strings, customer rows, filled documents or raw
+logs to public issues. Use synthetic fixtures and error categories. Revoke committed credentials first: deleting
+their current file does not remove Git history, cached artifacts or copies.
+
+## Source release review
+
+Review every published ref and its history. Run a redacted secret scan, then inspect for internal endpoints,
+account identifiers, infrastructure names, private incident notes and copied data that a credential detector will
+not recognize. Check GitHub metadata, release archives and build artifacts separately.
+
+Package only tracked source and synthetic tests. Exclude operational configs, `.db_cutover`, `.env`, credentials,
+Terraform state, logs, virtual environments and Git history from source archives. A clean scan records the checks
+run; it does not prove that every possible secret is absent.
+
+## Validation scope
+
+Unit tests cover cutover failures, interrupts, resume failures, dry runs, output handling and pure logic. Disposable
+PostgreSQL tests cover 16-to-17 text replication, publication coverage, markers and sequences. These do not validate
+RDS restart timing, Kubernetes pod churn, real PgBouncer network failures or application timeout budgets. Rehearse
+those in staging and keep an operator available during a live switch.