postgresledger 0.0.1__py3-none-any.whl

postgresledger/config.py

@@ -0,0 +1,82 @@
+"""Settings: postgresledger.toml (the project, the same for every database) and
+the one database this run works on, from DATABASE_* variables (.env or the environment)."""
+
+from __future__ import annotations
+
+import os
+import sys
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+CONFIG_NAME = "postgresledger.toml"
+DEFAULT_META_SCHEMA = "postgresledger"
+
+
+@dataclass(frozen=True)
+class Connection:
+    """How to reach one database. Another database on the same server:
+    dataclasses.replace(connection, database="other")."""
+
+    host: str
+    port: int
+    user: str
+    password: str
+    database: str
+    sslmode: str = "prefer"
+
+    def environment(self) -> dict[str, str]:
+        """The PG* variables psql and pgschema read to connect to this database.
+
+        All of them are always set, so a value left in the shell never applies to this database.
+        """
+        return {
+            "PGHOST": self.host,
+            "PGPORT": str(self.port),
+            "PGUSER": self.user,
+            "PGPASSWORD": self.password,
+            "PGDATABASE": self.database,
+            "PGSSLMODE": self.sslmode,
+        }
+
+    @property
+    def label(self) -> str:
+        return f"{self.database}@{self.host}:{self.port}"
+
+
+class Config:
+    def __init__(self, path: Path = Path(CONFIG_NAME), env_file: Path | None = None):
+        if not path.is_file():
+            sys.exit(f"no {path} here - run `pgl init` first")
+        self.path = path.resolve()
+        self.root = self.path.parent  # paths in the config file are relative to it
+        project = tomllib.loads(self.path.read_text()).get("project", {})
+        self.schema = project.get("schema", "public")  # the schema pgschema manages
+        self.schema_file = self.root / project.get("schema_file", "database/schema/schema.sql")
+        self.migrations_dir = self.root / project.get("migrations_dir", "database/migrations")
+        self.snapshots_dir = self.root / project.get("snapshots_dir", "database/snapshots")
+        self.meta_schema = project.get("meta_schema", DEFAULT_META_SCHEMA)
+        self.meta_table = f"{self.meta_schema}.schema_migrations"
+        self.env_file = env_file or Path(os.environ.get("PGL_ENV_FILE") or self.root / ".env")
+
+        # the one database this run works on; None when DATABASE_NAME is not set.
+        # Each DATABASE_* variable comes from the environment if set there, else from .env
+        # (load_dotenv never overrides a variable that is already set).
+        load_dotenv(self.env_file)
+        self.target: Connection | None = None
+        if database := os.environ.get("DATABASE_NAME"):
+            self.target = Connection(
+                host=os.environ.get("DATABASE_HOST", "localhost"),
+                port=int(os.environ.get("DATABASE_PORT", "5432")),
+                user=os.environ.get("DATABASE_USER", "postgres"),
+                password=os.environ.get("DATABASE_PASSWORD", ""),
+                database=database,
+                sslmode=os.environ.get("DATABASE_SSLMODE", "prefer"),
+            )
+
+
+def relative(path: Path) -> str:
+    """The path as the user would type it from the current folder."""
+    return os.path.relpath(path, Path.cwd())

postgresledger/core.py

@@ -0,0 +1,288 @@
+"""psql / pgschema calls, migration files, the scratch databases and the tracking table."""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from . import pgschema
+from .config import Config, Connection, relative
+
+MIGRATION_RE = re.compile(r"^(\d{4})_([a-z0-9_]+)\.sql$")
+ADVISORY_LOCK_KEY = 727274  # same key everywhere -> two applies on one database never run in parallel
+# databases on the scratch server only
+SHADOW_DB = "shadow"
+PLAN_DB = "plan"
+
+
+def run(command: list[str], connection: Connection, *, stdin: str | None = None) -> subprocess.CompletedProcess:
+    """Run psql or pgschema against `connection`; if it fails, show its output and stop pgl."""
+    # the shell environment (PATH, HOME, ...) plus the PG* variables of this connection
+    environment = {**os.environ, **connection.environment()}
+    program = Path(command[0]).name
+    try:
+        return subprocess.run(command, input=stdin, env=environment, text=True, capture_output=True, check=True)
+    except subprocess.CalledProcessError as error:
+        # the program ran and failed: its own output says why
+        program_output = (error.stdout + error.stderr).strip()
+        sys.exit(f"{program} failed on {connection.label}:\n{program_output}")
+    except OSError as error:
+        # the program could not run at all, e.g. psql is not installed
+        sys.exit(f"could not run {program}: {error}")
+
+
+def psql(connection: Connection, sql: str) -> str:
+    """Run SQL (one statement or a whole script) on `connection` and return psql's output."""
+    command = [
+        "psql",
+        "--no-psqlrc",  # ignore the user's ~/.psqlrc
+        "--quiet",
+        "--set", "ON_ERROR_STOP=1",  # stop at the first error, exit code != 0
+        "--no-align",  # plain values, separated by |
+        "--tuples-only",  # no headers, no row count
+    ]
+    return run(command, connection, stdin=sql).stdout.strip()
+
+
+@dataclass
+class Migration:
+    version: str
+    name: str
+    path: Path
+
+    @property
+    def id(self) -> str:
+        return f"{self.version}_{self.name}"
+
+
+def list_migrations(cfg: Config) -> list[Migration]:
+    cfg.migrations_dir.mkdir(parents=True, exist_ok=True)
+    out = []
+    for p in sorted(cfg.migrations_dir.iterdir()):
+        if m := MIGRATION_RE.match(p.name):
+            out.append(Migration(m.group(1), m.group(2), p))
+    versions = [m.version for m in out]
+    if len(versions) != len(set(versions)):
+        sys.exit("two migrations share the same version number")
+    return out
+
+
+# Tracking table (on the target database)
+
+
+def ensure_meta(cfg: Config, connection: Connection) -> None:
+    psql(connection, f"""
+        CREATE SCHEMA IF NOT EXISTS {cfg.meta_schema};
+        CREATE TABLE IF NOT EXISTS {cfg.meta_table} (
+            version     text PRIMARY KEY,
+            name        text NOT NULL,
+            checksum    text NOT NULL,
+            mode        text NOT NULL CHECK (mode IN ('applied', 'baseline', 'captured')),
+            applied_at  timestamptz NOT NULL DEFAULT now(),
+            applied_by  text NOT NULL DEFAULT current_user
+        );""")
+
+
+@dataclass(frozen=True)
+class AppliedMigration:
+    """One row of the tracking table: a migration this database has."""
+
+    version: str
+    name: str
+    checksum: str
+    mode: str  # applied, baseline or captured
+    applied_at: str
+    applied_by: str  # the database user that ran it
+
+
+def applied(cfg: Config, connection: Connection) -> dict[str, AppliedMigration]:
+    """The migrations this database has, by version."""
+    ensure_meta(cfg, connection)
+    # Postgres returns the rows as one JSON array of objects, so every value is read by its column name
+    rows_as_json = psql(connection, f"""
+        SELECT coalesce(json_agg(json_build_object(
+                   'version', version,
+                   'name', name,
+                   'checksum', checksum,
+                   'mode', mode,
+                   'applied_at', to_char(applied_at, 'YYYY-MM-DD HH24:MI:SS'),
+                   'applied_by', applied_by
+               ) ORDER BY version), '[]')
+        FROM {cfg.meta_table}""")
+    applied_by_version = {}
+    for row in json.loads(rows_as_json):
+        applied_by_version[row["version"]] = AppliedMigration(**row)
+    return applied_by_version
+
+
+def record_migration_sql(cfg: Config, migration: Migration, mode: str) -> str:
+    """The INSERT that records `migration` in the tracking table, as text.
+
+    Returned instead of run, so it can go into the same transaction as the migration itself.
+    applied_at and applied_by are filled in by the table's defaults.
+    """
+    checksum = hashlib.sha256(migration.path.read_bytes()).hexdigest()
+    # none of the values can contain a quote: version is digits, name is [a-z0-9_],
+    # checksum is hex and mode is one of applied / baseline / captured
+    return (f"INSERT INTO {cfg.meta_table} (version, name, checksum, mode) VALUES "
+            f"('{migration.version}', '{migration.name}', '{checksum}', '{mode}');")
+
+
+def apply_file(cfg: Config, connection: Connection, migration: Migration, mode: str = "applied") -> None:
+    """Apply one migration and record it in the tracking table - atomically whenever possible."""
+    migration_sql = migration.path.read_text()
+    record_sql = record_migration_sql(cfg, migration, mode)
+    # CREATE INDEX CONCURRENTLY and the like cannot run inside a transaction
+    runs_in_transaction = "CONCURRENTLY" not in migration_sql.upper()
+    if runs_in_transaction:
+        script = (f"BEGIN;\nSELECT pg_advisory_xact_lock({ADVISORY_LOCK_KEY});\n"
+                  f"\\i {migration.path}\n{record_sql}\nCOMMIT;\n")
+    else:
+        script = f"\\i {migration.path}\n{record_sql}\n"
+    psql(connection, script)
+
+
+def check_checksums(connection: Connection, migrations: list[Migration],
+                    applied_by_version: dict[str, AppliedMigration]) -> None:
+    """Stop when an applied migration file was edited since; warn about applied migrations missing here."""
+    for migration in migrations:
+        applied_migration = applied_by_version.get(migration.version)
+        if applied_migration is None:
+            continue
+        checksum = hashlib.sha256(migration.path.read_bytes()).hexdigest()
+        if applied_migration.checksum != checksum:
+            sys.exit(f"{migration.path.name} was edited after it was applied to {connection.label} (checksum mismatch)")
+    known_versions = {migration.version for migration in migrations}
+    for applied_migration in applied_by_version.values():
+        if applied_migration.version not in known_versions:
+            print(f"! {connection.label} has migration {applied_migration.version}_{applied_migration.name} "
+                  "that is not in the repository")
+
+
+def require_up_to_date(cfg: Config, connection: Connection) -> None:
+    applied_by_version = applied(cfg, connection)
+    pending = [migration.id for migration in list_migrations(cfg) if migration.version not in applied_by_version]
+    if pending:
+        sys.exit(f"{connection.label} is not up to date (pending: {', '.join(pending)}) - run `pgl apply` first")
+
+
+# pgschema and the scratch server
+
+
+def reset_database(scratch: Connection, database: str) -> Connection:
+    """Drop and recreate `database` on the scratch server and return a connection to it."""
+    psql(scratch, f'DROP DATABASE IF EXISTS "{database}" WITH (FORCE)')
+    psql(scratch, f'CREATE DATABASE "{database}"')
+    return replace(scratch, database=database)
+
+
+def build_shadow(cfg: Config, scratch: Connection, migrations: list[Migration]) -> Connection:
+    """Scratch database = empty database + `migrations`: the state those migrations describe."""
+    shadow = reset_database(scratch, SHADOW_DB)
+    ensure_meta(cfg, shadow)
+    for migration in migrations:
+        apply_file(cfg, shadow, migration)
+    return shadow
+
+
+def plan_arguments(scratch: Connection) -> list[str]:
+    """pgschema validates the desired state in a database on the scratch server (not its own embedded one)."""
+    if not psql(scratch, f"SELECT 1 FROM pg_database WHERE datname = '{PLAN_DB}'"):
+        psql(scratch, f'CREATE DATABASE "{PLAN_DB}"')
+    return [
+        "--plan-host", scratch.host,
+        "--plan-port", str(scratch.port),
+        "--plan-user", scratch.user,
+        "--plan-db", PLAN_DB,
+        "--plan-sslmode", "disable",
+    ]
+
+
+def pgschema_dump(cfg: Config, connection: Connection, output_file: Path) -> None:
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    dump = run([pgschema.locate(), "dump", "--schema", cfg.schema], connection).stdout
+    output_file.write_text(dump)
+
+
+@dataclass(frozen=True)
+class Plan:
+    """What pgschema would change, in two forms. Both are empty when there is nothing to change."""
+
+    sql: str  # the statements, e.g. for a migration file
+    human: str  # the same changes as a readable list for the terminal
+
+
+def pgschema_plan(cfg: Config, connection: Connection, desired: Path, scratch: Connection) -> Plan:
+    """The plan that turns `connection` into the state from `desired`."""
+    with tempfile.TemporaryDirectory() as temporary_dir:
+        sql_file = Path(temporary_dir) / "plan.sql"
+        human_file = Path(temporary_dir) / "plan.txt"
+        command = [
+            pgschema.locate(), "plan",
+            "--schema", cfg.schema,
+            "--file", str(desired),
+            "--output-sql", str(sql_file),
+            "--output-human", str(human_file),
+            "--no-color",
+            *plan_arguments(scratch),
+        ]
+        run(command, connection)
+        # pgschema writes no file when there is nothing to change
+        sql = sql_file.read_text() if sql_file.exists() else ""
+        human = human_file.read_text() if human_file.exists() else ""
+    return Plan(sql=sql.strip(), human=human.strip())
+
+
+# Generating migrations
+
+
+def is_valid_migration_name(name: str) -> bool:
+    """Lowercase letters, digits and _ only, so the name is safe in a file name and in SQL."""
+    allowed_characters = set("abcdefghijklmnopqrstuvwxyz0123456789_")
+    return name != "" and set(name) <= allowed_characters
+
+
+def write_migration(cfg: Config, name: str, sql: str, note: str) -> Migration:
+    if not is_valid_migration_name(name):
+        sys.exit("migration name: lowercase letters, digits and _ only")
+    existing = list_migrations(cfg)
+    next_number = int(existing[-1].version) + 1 if existing else 1
+    version = f"{next_number:04d}"
+    path = cfg.migrations_dir / f"{version}_{name}.sql"
+    generated_at = dt.datetime.now().isoformat(timespec="seconds")
+    header = (f"-- migration: {version}_{name}\n"
+              f"-- generated: {generated_at} by postgresledger/pgschema\n"
+              f"-- {note}\n\n")
+    path.write_text(header + sql + "\n")
+    return Migration(version, name, path)
+
+
+def generate_migration(cfg: Config, scratch: Connection, name: str, note: str) -> Migration | None:
+    """schema.sql vs (every migration applied) -> new migration, then check that it reproduces schema.sql."""
+    existing = list_migrations(cfg)
+    print(f"- building the state of {len(existing)} existing migrations (scratch Postgres)")
+    shadow = build_shadow(cfg, scratch, existing)
+    plan = pgschema_plan(cfg, shadow, cfg.schema_file, scratch)
+    if not plan.sql:
+        print("no changes compared to the existing migrations")
+        return None
+    migration = write_migration(cfg, name, plan.sql, note)
+    print(plan.human)
+    print(f"- verifying {migration.path.name}")
+    apply_file(cfg, shadow, migration)
+    # with the new migration applied, nothing should be left to change
+    leftover = pgschema_plan(cfg, shadow, cfg.schema_file, scratch)
+    if leftover.sql:
+        print(leftover.human)
+        migration.path.unlink()
+        sys.exit("after applying the migration the result still differs from schema.sql - migration deleted")
+    print(f"✔ created {relative(migration.path)}")
+    return migration

postgresledger/pgschema.py

@@ -0,0 +1,112 @@
+"""The pgschema binary: pinned version, downloaded once per machine and SHA256-checked;
+`setup` also installs the scratch Postgres (scratch.py).
+
+It lives in ~/.cache/postgresledger/ ($XDG_CACHE_HOME respected), so every project
+on the machine shares one copy. PGL_PGSCHEMA points to another binary.
+pgschema has no Windows build; on Windows run postgresledger inside WSL2.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+
+VERSION = "1.13.1"
+# sha256 of the release assets, per <os>-<arch>
+SHA256 = {
+    "linux-amd64": "f726513e19d12f7667ba0b6a24e7a3a568e576708de030ef88f4ba3790e85946",
+    "linux-arm64": "8202d3e2cba000872627472549dbfb4618d2b256b22e7144b4ff6ecd476f36c1",
+    "darwin-amd64": "72d26778679407cec0816d1ec26fb123d2fd80120817977051c53e86b6afced5",
+    "darwin-arm64": "15af7abf0b7e545a98452f2eed62650a7dc8aa6abcc7f54dd4f0f6e234238a43",
+}
+ARCH = {"x86_64": "amd64", "amd64": "amd64", "aarch64": "arm64", "arm64": "arm64"}
+
+
+def cache_dir() -> Path:
+    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "postgresledger"
+
+
+def binary_path() -> Path:
+    return cache_dir() / f"pgschema-{VERSION}"
+
+
+def target() -> str:
+    """This machine as pgschema names its builds, e.g. linux-amd64."""
+    os_name = platform.system().lower()
+    if os_name == "windows":
+        sys.exit("pgschema has no Windows build - run postgresledger inside WSL2")
+    architecture = ARCH.get(platform.machine().lower())
+    build = f"{os_name}-{architecture}"
+    if build not in SHA256:
+        sys.exit(f"no pgschema build for {platform.system()} {platform.machine()}")
+    return build
+
+
+def sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def install() -> Path:
+    """Download the pinned pgschema unless the right one is already there."""
+    build = target()
+    binary = binary_path()
+    expected_checksum = SHA256[build]
+    if binary.exists() and sha256(binary) == expected_checksum:
+        print(f"ok       pgschema {VERSION} ({build}) already in {binary}")
+        return binary
+    url = f"https://github.com/pgplex/pgschema/releases/download/v{VERSION}/pgschema-{VERSION}-{build}"
+    print(f"download {url}")
+    binary.parent.mkdir(parents=True, exist_ok=True)
+    # downloaded next to the binary and renamed only when complete and checked
+    partial_binary = binary.with_suffix(".part")
+    with urllib.request.urlopen(url) as response:
+        partial_binary.write_bytes(response.read())
+    actual_checksum = sha256(partial_binary)
+    if actual_checksum != expected_checksum:
+        partial_binary.unlink()
+        sys.exit(f"pgschema checksum mismatch: expected {expected_checksum}, got {actual_checksum}")
+    partial_binary.chmod(0o755)
+    partial_binary.replace(binary)
+    print(f"ok       pgschema {VERSION} ({build}) -> {binary}")
+    return binary
+
+
+def locate() -> str:
+    """PGL_PGSCHEMA, then the downloaded binary, then pgschema in PATH."""
+    if configured_binary := os.environ.get("PGL_PGSCHEMA"):
+        return configured_binary
+    if binary_path().exists():
+        return str(binary_path())
+    if binary_in_path := shutil.which("pgschema"):
+        return binary_in_path
+    sys.exit("pgschema not found - run `pgl setup` to download it")
+
+
+def check_tool(name: str, version_arguments: list[str], hint: str, required: bool = True) -> bool:
+    """Print whether the tool is installed (with its version); False only when a required tool is missing."""
+    if not shutil.which(name):
+        status = "MISSING" if required else "missing"
+        print(f"{status}  {name} - {hint}")
+        return not required
+    result = subprocess.run([name, *version_arguments], capture_output=True, text=True, check=False)
+    output_lines = result.stdout.strip().splitlines()
+    version = output_lines[0] if output_lines else name
+    print(f"ok       {version}")
+    return True
+
+
+def setup() -> int:
+    """Download pgschema and the scratch Postgres, check the other tools postgresledger needs."""
+    from . import scratch
+
+    print(f"ok       Python {platform.python_version()}")
+    install()
+    scratch.install()
+    psql_found = check_tool("psql", ["--version"], "install the PostgreSQL client (postgresql-client / libpq)")
+    return 0 if psql_found else 1

postgresledger/scratch.py

@@ -0,0 +1,156 @@
+"""A throwaway Postgres on this machine, for the work that needs a scratch database.
+
+Building "every migration applied", generating a migration, checking drift,
+and capture need a database postgresledger may drop and recreate. That never
+happens on a real server: each command starts its own Postgres in a temporary
+folder on a free local port, and deletes it when the command ends.
+
+The server binaries are a pinned build from Maven Central (io.zonky.test.postgres,
+relocatable), downloaded once per machine into ~/.cache/postgresledger/ and SHA256-checked.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import platform
+import shutil
+import socket
+import subprocess
+import sys
+import tarfile
+import tempfile
+import urllib.request
+import zipfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from .config import Connection
+from .pgschema import cache_dir, sha256
+
+VERSION = "17.11.0"
+# sha256 of the jars, per platform (cross-checked with Maven Central's .sha1)
+SHA256 = {
+    "linux-amd64": "0dd7b72b6f335b8ecfb355fa24c5781e8a93edd09880bb77eb52ebbf29b3e96d",
+    "linux-arm64v8": "8b042e0ea418b1927d95399207950da0734d27fe01e29503ade3bdc464ad4c2b",
+    "darwin-amd64": "d464ff178e9860ba204662ac23fa547504b7fd392392ff2fb92e3fd73b5bdb64",
+    "darwin-arm64v8": "a1c2786acb0c398f9b2d76806fc52f5dc8b222cbc8e9383a9b9702084daaf3a5",
+}
+# <os>-<arch> -> the name of the Maven Central build
+BUILD = {
+    "linux-amd64": "linux-amd64",
+    "linux-arm64": "linux-arm64v8",
+    "darwin-amd64": "darwin-amd64",
+    "darwin-arm64": "darwin-arm64v8",
+}
+ARCH = {"x86_64": "amd64", "amd64": "amd64", "aarch64": "arm64", "arm64": "arm64"}
+
+
+def install_dir() -> Path:
+    return cache_dir() / f"postgres-{VERSION}"
+
+
+def target() -> str:
+    """This machine as Maven Central names the Postgres builds, e.g. linux-arm64v8."""
+    os_name = platform.system().lower()
+    architecture = ARCH.get(platform.machine().lower())
+    platform_name = f"{os_name}-{architecture}"
+    if platform_name not in BUILD:
+        sys.exit(f"no Postgres build for {platform.system()} {platform.machine()} (Windows: use WSL2)")
+    return BUILD[platform_name]
+
+
+def install() -> Path:
+    """Download and unpack the pinned Postgres server unless it is already there."""
+    destination = install_dir()
+    if (destination / "bin" / "pg_ctl").exists():
+        print(f"ok       Postgres {VERSION} (scratch server) already in {destination}")
+        return destination
+    build = target()
+    url = (f"https://repo1.maven.org/maven2/io/zonky/test/postgres/embedded-postgres-binaries-{build}/{VERSION}/"
+           f"embedded-postgres-binaries-{build}-{VERSION}.jar")
+    print(f"download {url}")
+    with urllib.request.urlopen(url) as response:
+        jar = response.read()
+    with tempfile.NamedTemporaryFile() as jar_file:
+        jar_file.write(jar)
+        jar_file.flush()
+        actual_checksum = sha256(Path(jar_file.name))
+    expected_checksum = SHA256[build]
+    if actual_checksum != expected_checksum:
+        sys.exit(f"Postgres checksum mismatch: expected {expected_checksum}, got {actual_checksum}")
+
+    # the jar holds one .txz archive with the server; unpacked next to the destination,
+    # renamed only when complete
+    partial_destination = destination.with_name(destination.name + ".part")
+    shutil.rmtree(partial_destination, ignore_errors=True)
+    with zipfile.ZipFile(io.BytesIO(jar)) as jar_archive:
+        archive_names = [name for name in jar_archive.namelist() if name.endswith(".txz")]
+        server_archive = jar_archive.read(archive_names[0])
+    with tarfile.open(fileobj=io.BytesIO(server_archive), mode="r:xz") as tar:
+        # Python versions with extraction filters: keep permissions, block paths outside the folder
+        if hasattr(tarfile, "tar_filter"):
+            tar.extractall(partial_destination, filter="tar")
+        else:
+            tar.extractall(partial_destination)
+    partial_destination.replace(destination)
+    print(f"ok       Postgres {VERSION} (scratch server) -> {destination}")
+    return destination
+
+
+def free_port() -> int:
+    """A local port nothing listens on: the operating system picks it when binding to port 0."""
+    with socket.socket() as probe:
+        probe.bind(("127.0.0.1", 0))
+        return probe.getsockname()[1]
+
+
+def run_server_program(command: list[str]) -> None:
+    """Run initdb or pg_ctl; if it fails, show its output and stop pgl."""
+    program = Path(command[0]).name
+    try:
+        subprocess.run(command, text=True, capture_output=True, check=True)
+    except subprocess.CalledProcessError as error:
+        # the program ran and failed: its own output says why
+        program_output = (error.stdout + error.stderr).strip()
+        sys.exit(f"scratch Postgres: {program} failed:\n{program_output}")
+    except OSError as error:
+        # the program could not run at all, e.g. the binary is missing
+        sys.exit(f"scratch Postgres: could not run {program}: {error}")
+
+
+@contextmanager
+def server() -> Iterator[Connection]:
+    """Start a throwaway Postgres, yield a connection to its `postgres` database, delete it afterwards."""
+    bin_dir = install_dir() / "bin"
+    if not (bin_dir / "pg_ctl").exists():
+        sys.exit("the scratch Postgres is not installed - run `pgl setup`")
+    if hasattr(os, "geteuid") and os.geteuid() == 0:
+        sys.exit("the scratch Postgres cannot run as root - run pgl as a normal user")
+    with tempfile.TemporaryDirectory(prefix="postgresledger-") as temporary_dir:
+        data_dir = Path(temporary_dir) / "data"
+        log_file = Path(temporary_dir) / "server.log"
+        port = free_port()
+        run_server_program([
+            str(bin_dir / "initdb"),
+            "-D", str(data_dir),
+            "-U", "postgres",
+            "-A", "trust",  # no passwords: only this machine can reach it
+            "-E", "UTF8",
+            "--locale=C",
+            "--no-sync",  # a throwaway database does not need to survive a crash
+        ])
+        server_options = f"-p {port} -c listen_addresses=127.0.0.1 -c unix_socket_directories='' -c fsync=off"
+        run_server_program([
+            str(bin_dir / "pg_ctl"),
+            "-D", str(data_dir),
+            "-l", str(log_file),
+            "-w", "start",
+            "-o", server_options,
+        ])
+        try:
+            yield Connection("127.0.0.1", port, "postgres", "", "postgres", "disable")
+        finally:
+            stop_command = [str(bin_dir / "pg_ctl"), "-D", str(data_dir), "-m", "immediate", "-w", "stop"]
+            subprocess.run(stop_command, capture_output=True, check=False)