From 6f1b68238f7d097e5ff784a1a410fd3e9df15bc8 Mon Sep 17 00:00:00 2001 From: Kiran Muddukrishna Date: Thu, 6 Aug 2026 11:04:30 +1000 Subject: [PATCH 1/2] vision: standalone CLI use is a supported front door MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pg-sprite is GitOps-ready, not GitOps-required. The properties that make it drivable by SchemaBot (deterministic plans, typed verdicts, bounded locks, crash-resume) also make it a safe direct CLI for an engineer with nothing but a DSN — including the urgent mid-incident change where the alternative is hand-typed DDL in psql. Add this to the tagline, pillar 2, and the "go-to" success criteria. --- docs/vision.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/vision.md b/docs/vision.md index be413c2..fbe5fb3 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -5,7 +5,8 @@ > online with provable safety, and invisible to the applications it serves. It is the > reliable PostgreSQL execution layer for a GitOps front-end like > [SchemaBot](https://github.com/block/schemabot) — what -> [Spirit](https://github.com/block/spirit) is for MySQL.** +> [Spirit](https://github.com/block/spirit) is for MySQL — and a standalone CLI any +> engineer can pick up today, no GitOps layer required.** One tool, one mental model, for *all* PostgreSQL schema migrations. Today teams assemble a toolchain: one tool to diff and plan the easy DDL, another to copy-and-swap the genuine @@ -52,6 +53,16 @@ SchemaBot handles GitOps orchestration, pull requests, and approvals; pg-sprite classifies, routes, and executes ([schemabot-integration.md](schemabot-integration.md)). +**GitOps-ready, not GitOps-required.** The same properties that make pg-sprite drivable by +an orchestrator — deterministic plans, typed verdicts, bounded locks, idempotent +crash-resume, no mid-flight operator judgment — make it a safe *direct* tool: an engineer +with a DSN and the CLI gets the full engine (`lint`, `diff`, execution) without adopting +SchemaBot first. That matters most at the worst moment: when a schema change has to happen +*right now* and the alternative is hand-typed DDL in a `psql` session — unbounded locks, no +verdict, no resume — the safe path should also be the path of least resistance. Meeting +users where they are is part of the point: standalone CLI use is a supported front door, +not a demo mode. + ### 3. Developer-friendly, application-invisible Zero migration-mechanism app-coupling: no `search_path` opt-ins, no deploy-ordering @@ -87,6 +98,10 @@ pg-sprite has succeeded when: - a team's *entire* schema-change workflow — through SchemaBot, with pg-sprite executing — is "edit SQL, merge PR": for every change type, on every table size, with no per-migration operator judgment; +- an engineer with nothing but a DSN reaches for the pg-sprite CLI *instead of* a raw + `psql` session — for day-to-day changes on teams that haven't adopted a GitOps layer, and + for the urgent mid-incident change where bounded locks, a verdict, and crash-resume + matter most — and gets the same engine and the same guarantees as the fleet; - the SchemaBot fleet drives PostgreSQL changes through pg-sprite the way it drives MySQL changes through [Spirit](https://github.com/block/spirit) — same declarative front-end, same orchestration, same safety posture; From dac3ed6c6f0b041bbbbdef6f6fb3de07f9a29f1d Mon Sep 17 00:00:00 2001 From: Kiran Muddukrishna Date: Tue, 11 Aug 2026 13:13:06 +1000 Subject: [PATCH 2/2] vision: claim only what standalone use enforces today Review feedback on the standalone-CLI pillar: drop present-tense claims for phased capabilities (full engine, crash-resume), lead with the enforced refusal discipline, reorder the incident case as earned trust, and name the one-design-rule contract both front doors share. --- docs/vision.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/vision.md b/docs/vision.md index 98fd760..f7e6f90 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -54,14 +54,17 @@ classifies, routes, and executes ([schemabot-integration.md](schemabot-integration.md)). **GitOps-ready, not GitOps-required.** The same properties that make pg-sprite drivable by -an orchestrator — deterministic plans, typed verdicts, bounded locks, idempotent -crash-resume, no mid-flight operator judgment — make it a safe *direct* tool: an engineer -with a DSN and the CLI gets the full engine (`lint`, `diff`, execution) without adopting -SchemaBot first. That matters most at the worst moment: when a schema change has to happen -*right now* and the alternative is hand-typed DDL in a `psql` session — unbounded locks, no -verdict, no resume — the safe path should also be the path of least resistance. Meeting -users where they are is part of the point: standalone CLI use is a supported front door, -not a demo mode. +an orchestrator — deterministic plans, typed verdicts, bounded locks — make it a safe +*direct* tool: an engineer with a DSN and the CLI gets the same engine, without adopting +SchemaBot first. What that buys today is the refusal discipline: every session runs under +a bounded `lock_timeout`, and a change the engine cannot prove safe ends in seconds with a +typed verdict — not a hand-typed `ALTER` in a bare `psql` session holding an +`ACCESS EXCLUSIVE` lock on a hot table. Each capability the phased plan lands +(copy-and-swap, the checksum gate, durable crash-resume) reaches the direct user the +moment it ships, because both front doors are held to one design rule: every capability is +reachable from the CLI, and the CLI consumes the same plan, verdict, and lint contracts an +orchestrator would. Meeting users where they are is part of the point: standalone CLI use +is a supported front door, not a demo mode. ### 3. Developer-friendly, application-invisible @@ -118,9 +121,10 @@ pg-sprite has succeeded when: is "edit SQL, merge PR": for every change type, on every table size, with no per-change operator judgment; - an engineer with nothing but a DSN reaches for the pg-sprite CLI *instead of* a raw - `psql` session — for day-to-day changes on teams that haven't adopted a GitOps layer, and - for the urgent mid-incident change where bounded locks, a verdict, and crash-resume - matter most — and gets the same engine and the same guarantees as the fleet; + `psql` session — first for day-to-day changes on teams that haven't adopted a GitOps + layer, and, once the tool has earned that trust, for the urgent mid-incident change + where bounded locks, a typed verdict, and crash-resume matter most — and gets the same + engine and the same guarantees as the fleet; - the SchemaBot fleet drives PostgreSQL changes through pg-sprite the way it drives MySQL changes through [Spirit](https://github.com/block/spirit) — same declarative front-end, same orchestration, same safety posture;