pgbrake 0.1.0__tar.gz

pgbrake-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

pgbrake-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Zhang Lixiang
+
+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.

pgbrake-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: pgbrake
+Version: 0.1.0
+Summary: A local safety brake between AI coding agents and your Postgres: approval for risky SQL, row limits, one-command undo, audit log.
+Project-URL: Homepage, https://github.com/lexang/pgbrake
+Project-URL: Issues, https://github.com/lexang/pgbrake/issues
+Author: Zhang Lixiang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,claude-code,codex,mcp,postgres,safety,undo
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.10
+Requires-Dist: pglast>=6
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pgbrake
+
+**An undo button for your database when an AI agent is driving.**
+
+pgbrake is a local MCP server that sits between Claude Code / Codex / Cursor and your Postgres.
+Every write the agent makes gets a change id you can reverse with one command. Risky SQL waits
+for a human. Everything is logged. Nothing leaves your machine.
+
+```
+agent> DELETE FROM users WHERE created_at < '2025-01-01'
+pgbrake> held: DELETE would touch 4,812 rows (limit 100) — approval apv_3f9c21aa
+
+agent> DELETE FROM users WHERE id = 42
+pgbrake> 1 row affected; undo with change id chg_8e01b7d2
+
+you$ pgbrake undo chg_8e01b7d2
+undid delete on "users": 1 row(s) restored
+```
+
+## Why
+
+Claude Code checkpoints rewind files, not databases. Client-side permission prompts and hooks
+can be skipped or misfire for MCP calls, and a tool's own "destructive" label is just a hint.
+pgbrake enforces its rules **inside the server**, so they hold no matter which agent or client calls it.
+
+## What it does (free, MIT)
+
+- **Real SQL parsing** (the Postgres parser via pglast), not regex.
+- **Held for approval:** DDL (`DROP`, `ALTER`, `TRUNCATE`...), `UPDATE`/`DELETE` without `WHERE`,
+  any write over the row limit (default 100), upserts and `MERGE`.
+- **Never allowed:** `ALTER SYSTEM`, role/database creation and drops, `COPY ... PROGRAM`, `DO` blocks.
+- **One-command undo:** before each `UPDATE`/`DELETE`, the affected rows are saved locally; inserts are
+  tracked by primary key. Undo refuses if the rows changed since, unless you `--force`.
+- **Approval only by a human:** in the client's own prompt (MCP elicitation) or `pgbrake approve <id>`
+  in an interactive terminal. Approvals are one-shot, expire in 15 minutes, and are bound to the exact SQL.
+- **Audit log** of every statement, decision and row count, in `~/.pgbrake/journal.db`.
+- Multi-statement calls run in one transaction: all or nothing.
+
+## Install
+
+```bash
+pip install pgbrake      # or: uvx pgbrake serve
+# before the PyPI release: pip install git+https://github.com/lexang/pgbrake
+```
+
+Claude Code:
+
+```bash
+claude mcp add pgbrake --env PGBRAKE_DSN="postgresql://me@localhost/app" -- uvx pgbrake serve
+```
+
+Codex (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.pgbrake]
+command = "uvx"
+args = ["pgbrake", "serve"]
+env = { PGBRAKE_DSN = "postgresql://me@localhost/app" }
+```
+
+Then remove any other database MCP / `psql` access from the agent, so pgbrake is the only way in.
+In Claude Code, add `"Bash(psql:*)"` and `"Bash(pgbrake approve:*)"` to `permissions.deny`.
+
+## Commands
+
+```
+pgbrake pending            # SQL waiting for you
+pgbrake approve <id>       # approve (interactive terminal only)
+pgbrake deny <id>
+pgbrake changes            # undoable changes
+pgbrake undo <change-id>   # reverse one
+pgbrake log                # audit log
+```
+
+## Settings (env)
+
+| Variable | Default | |
+|---|---|---|
+| `PGBRAKE_DSN` | — | connection string (falls back to `DATABASE_URL`) |
+| `PGBRAKE_MAX_ROWS` | 100 | writes touching more rows need approval |
+| `PGBRAKE_ALLOW_DDL` | 0 | set 1 to let schema changes through (still logged) |
+| `PGBRAKE_READ_ONLY` | 0 | set 1 to refuse every write |
+| `PGBRAKE_STATEMENT_TIMEOUT_MS` | 15000 | |
+| `PGBRAKE_JOURNAL` | `~/.pgbrake/journal.db` | |
+
+## Limits
+
+- Undo covers rows changed through pgbrake. It is not a backup: keep real backups.
+- `TRUNCATE`, DDL, upserts and `MERGE` are held for approval but cannot be undone.
+- Updating a table with no primary key needs approval and cannot be undone.
+- The free version keeps the last 20 undoable changes.
+
+## Pro (coming)
+
+Unlimited undo history, a migration guard for agent terminal commands
+(`prisma migrate reset --force`, `drizzle-kit push --force`, `alembic downgrade base`...: snapshot first,
+then ask), per-project policy files, and audit export. One-time license.

pgbrake-0.1.0/README.md

@@ -0,0 +1,97 @@
+# pgbrake
+
+**An undo button for your database when an AI agent is driving.**
+
+pgbrake is a local MCP server that sits between Claude Code / Codex / Cursor and your Postgres.
+Every write the agent makes gets a change id you can reverse with one command. Risky SQL waits
+for a human. Everything is logged. Nothing leaves your machine.
+
+```
+agent> DELETE FROM users WHERE created_at < '2025-01-01'
+pgbrake> held: DELETE would touch 4,812 rows (limit 100) — approval apv_3f9c21aa
+
+agent> DELETE FROM users WHERE id = 42
+pgbrake> 1 row affected; undo with change id chg_8e01b7d2
+
+you$ pgbrake undo chg_8e01b7d2
+undid delete on "users": 1 row(s) restored
+```
+
+## Why
+
+Claude Code checkpoints rewind files, not databases. Client-side permission prompts and hooks
+can be skipped or misfire for MCP calls, and a tool's own "destructive" label is just a hint.
+pgbrake enforces its rules **inside the server**, so they hold no matter which agent or client calls it.
+
+## What it does (free, MIT)
+
+- **Real SQL parsing** (the Postgres parser via pglast), not regex.
+- **Held for approval:** DDL (`DROP`, `ALTER`, `TRUNCATE`...), `UPDATE`/`DELETE` without `WHERE`,
+  any write over the row limit (default 100), upserts and `MERGE`.
+- **Never allowed:** `ALTER SYSTEM`, role/database creation and drops, `COPY ... PROGRAM`, `DO` blocks.
+- **One-command undo:** before each `UPDATE`/`DELETE`, the affected rows are saved locally; inserts are
+  tracked by primary key. Undo refuses if the rows changed since, unless you `--force`.
+- **Approval only by a human:** in the client's own prompt (MCP elicitation) or `pgbrake approve <id>`
+  in an interactive terminal. Approvals are one-shot, expire in 15 minutes, and are bound to the exact SQL.
+- **Audit log** of every statement, decision and row count, in `~/.pgbrake/journal.db`.
+- Multi-statement calls run in one transaction: all or nothing.
+
+## Install
+
+```bash
+pip install pgbrake      # or: uvx pgbrake serve
+# before the PyPI release: pip install git+https://github.com/lexang/pgbrake
+```
+
+Claude Code:
+
+```bash
+claude mcp add pgbrake --env PGBRAKE_DSN="postgresql://me@localhost/app" -- uvx pgbrake serve
+```
+
+Codex (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.pgbrake]
+command = "uvx"
+args = ["pgbrake", "serve"]
+env = { PGBRAKE_DSN = "postgresql://me@localhost/app" }
+```
+
+Then remove any other database MCP / `psql` access from the agent, so pgbrake is the only way in.
+In Claude Code, add `"Bash(psql:*)"` and `"Bash(pgbrake approve:*)"` to `permissions.deny`.
+
+## Commands
+
+```
+pgbrake pending            # SQL waiting for you
+pgbrake approve <id>       # approve (interactive terminal only)
+pgbrake deny <id>
+pgbrake changes            # undoable changes
+pgbrake undo <change-id>   # reverse one
+pgbrake log                # audit log
+```
+
+## Settings (env)
+
+| Variable | Default | |
+|---|---|---|
+| `PGBRAKE_DSN` | — | connection string (falls back to `DATABASE_URL`) |
+| `PGBRAKE_MAX_ROWS` | 100 | writes touching more rows need approval |
+| `PGBRAKE_ALLOW_DDL` | 0 | set 1 to let schema changes through (still logged) |
+| `PGBRAKE_READ_ONLY` | 0 | set 1 to refuse every write |
+| `PGBRAKE_STATEMENT_TIMEOUT_MS` | 15000 | |
+| `PGBRAKE_JOURNAL` | `~/.pgbrake/journal.db` | |
+
+## Limits
+
+- Undo covers rows changed through pgbrake. It is not a backup: keep real backups.
+- `TRUNCATE`, DDL, upserts and `MERGE` are held for approval but cannot be undone.
+- Updating a table with no primary key needs approval and cannot be undone.
+- The free version keeps the last 20 undoable changes.
+
+## Pro (coming)
+
+Unlimited undo history, a migration guard for agent terminal commands
+(`prisma migrate reset --force`, `drizzle-kit push --force`, `alembic downgrade base`...: snapshot first,
+then ask), per-project policy files, and audit export. One-time license.

pgbrake-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pgbrake"
+version = "0.1.0"
+description = "A local safety brake between AI coding agents and your Postgres: approval for risky SQL, row limits, one-command undo, audit log."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Zhang Lixiang" }]
+keywords = ["mcp", "postgres", "claude-code", "codex", "ai-agent", "safety", "undo"]
+dependencies = [
+  "mcp>=1.10",
+  "psycopg[binary]>=3.1",
+  "pglast>=6",
+  "pydantic>=2",
+]
+
+[project.urls]
+Homepage = "https://github.com/lexang/pgbrake"
+Issues = "https://github.com/lexang/pgbrake/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+pgbrake = "pgbrake.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pgbrake"]

pgbrake-0.1.0/src/pgbrake/__init__.py

@@ -0,0 +1,3 @@
+"""pgbrake: a local safety brake between AI coding agents and your Postgres."""
+__version__ = "0.1.0"
+from .engine import Brake, Policy, Result  # noqa: F401

pgbrake-0.1.0/src/pgbrake/classify.py

@@ -0,0 +1,132 @@
+"""Classify SQL statements by risk using the real Postgres parser (pglast)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from pglast import parse_sql
+from pglast.stream import RawStream
+
+
+class Kind(str, Enum):
+    READ = "read"          # SELECT / SHOW / EXPLAIN without ANALYZE
+    WRITE = "write"        # INSERT / UPDATE / DELETE with a WHERE clause
+    BULK_WRITE = "bulk"    # UPDATE / DELETE without WHERE, TRUNCATE
+    DDL = "ddl"            # CREATE / ALTER / DROP / GRANT ...
+    BLOCKED = "blocked"    # things we never pass through (COPY TO PROGRAM, ALTER SYSTEM...)
+    OTHER = "other"        # SET, BEGIN, unknown -> treated as needing approval
+
+
+READ_NODES = {"SelectStmt", "VariableShowStmt", "ExplainStmt"}
+WRITE_NODES = {"InsertStmt", "UpdateStmt", "DeleteStmt", "MergeStmt"}
+BLOCKED_NODES = {"AlterSystemStmt", "CreateRoleStmt", "AlterRoleStmt", "DropRoleStmt",
+                 "DropdbStmt", "CreatedbStmt", "LoadStmt", "DoStmt"}
+DDL_PREFIXES = ("Create", "Alter", "Drop", "Grant", "Rename", "Comment", "Truncate",
+                "Reindex", "Cluster", "Vacuum", "Refresh", "Lock")
+
+
+@dataclass
+class Statement:
+    sql: str
+    node: str
+    kind: Kind
+    table: str | None = None
+    schema: str | None = None
+    where_sql: str | None = None
+    has_returning: bool = False
+    alias: str | None = None
+    from_sql: str | None = None      # extra FROM/USING items for join-based writes
+    undo_supported: bool = True
+    reasons: list[str] = field(default_factory=list)
+
+    @property
+    def qualified_table(self) -> str | None:
+        if not self.table:
+            return None
+        return f'"{self.schema}"."{self.table}"' if self.schema else f'"{self.table}"'
+
+
+def _rangevar(rv):
+    if rv is None:
+        return None, None
+    return rv.relname, rv.schemaname
+
+
+def _select_writes(stmt) -> bool:
+    """SELECT ... INTO, or data-modifying CTEs inside a SELECT."""
+    if getattr(stmt, "intoClause", None) is not None:
+        return True
+    wc = getattr(stmt, "withClause", None)
+    if wc and wc.ctes:
+        for cte in wc.ctes:
+            if type(cte.ctequery).__name__ in WRITE_NODES:
+                return True
+    return False
+
+
+def classify(sql: str) -> list[Statement]:
+    out: list[Statement] = []
+    for raw in parse_sql(sql):
+        node = raw.stmt
+        name = type(node).__name__
+        text = RawStream()(node)
+        st = Statement(sql=text, node=name, kind=Kind.OTHER)
+
+        if name in READ_NODES:
+            st.kind = Kind.READ
+            if name == "SelectStmt" and _select_writes(node):
+                st.kind = Kind.WRITE
+                st.reasons.append("SELECT with data-modifying CTE / INTO")
+            if name == "ExplainStmt":
+                opts = [o.defname.lower() for o in (node.options or [])]
+                if "analyze" in opts:
+                    inner = classify(RawStream()(node.query))[0]
+                    st.kind = inner.kind if inner.kind != Kind.READ else Kind.READ
+                    st.reasons.append("EXPLAIN ANALYZE executes the statement")
+        elif name in WRITE_NODES:
+            st.table, st.schema = _rangevar(node.relation)
+            if node.relation is not None and node.relation.alias is not None:
+                st.alias = node.relation.alias.aliasname
+            st.has_returning = bool(getattr(node, "returningList", None))
+            if name in ("UpdateStmt", "DeleteStmt"):
+                where = node.whereClause
+                if where is None:
+                    st.kind = Kind.BULK_WRITE
+                    st.reasons.append(f"{name[:-4].upper()} without WHERE affects every row")
+                else:
+                    st.kind = Kind.WRITE
+                    st.where_sql = RawStream()(where)
+                    extra = getattr(node, "fromClause", None) or getattr(node, "usingClause", None)
+                    if extra:
+                        st.from_sql = ", ".join(RawStream()(x) for x in extra)
+            elif name == "MergeStmt":
+                st.kind = Kind.BULK_WRITE
+                st.undo_supported = False
+                st.reasons.append("MERGE can touch many rows and is not undoable")
+            else:
+                st.kind = Kind.WRITE
+                occ = getattr(node, "onConflictClause", None)
+                if occ is not None and int(occ.action) == 2:
+                    st.undo_supported = False
+                    st.reasons.append("upsert (ON CONFLICT DO UPDATE) is not undoable")
+        elif name == "CopyStmt":
+            if getattr(node, "is_program", False) or (not node.is_from and node.filename):
+                st.kind = Kind.BLOCKED
+                st.reasons.append("COPY to/from server file or program")
+            else:
+                st.kind = Kind.BULK_WRITE if node.is_from else Kind.READ
+        elif name in BLOCKED_NODES:
+            st.kind = Kind.BLOCKED
+            st.reasons.append(f"{name} is never allowed through pgbrake")
+        elif name == "TruncateStmt":
+            st.kind = Kind.BULK_WRITE
+            st.undo_supported = False
+            st.reasons.append("TRUNCATE removes every row and cannot be undone by pgbrake")
+        elif name.startswith(DDL_PREFIXES):
+            st.kind = Kind.DDL
+            st.reasons.append(f"schema change ({name})")
+        elif name == "TransactionStmt":
+            st.kind = Kind.BLOCKED
+            st.reasons.append("pgbrake manages transactions itself; send one statement group per call")
+        out.append(st)
+    return out

pgbrake-0.1.0/src/pgbrake/cli.py

@@ -0,0 +1,85 @@
+"""pgbrake command line: serve the MCP server, approve held SQL, inspect and undo changes."""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import sys
+
+from .journal import Journal
+
+
+def _ts(t):
+    return dt.datetime.fromtimestamp(t).strftime("%Y-%m-%d %H:%M:%S") if t else "-"
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="pgbrake", description="Safety brake for AI agents on Postgres")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("serve", help="run the MCP server (stdio)")
+    s.add_argument("--dsn")
+    sub.add_parser("pending", help="list SQL waiting for approval")
+    a = sub.add_parser("approve", help="approve held SQL")
+    a.add_argument("id")
+    d = sub.add_parser("deny", help="deny held SQL")
+    d.add_argument("id")
+    c = sub.add_parser("changes", help="list undoable changes")
+    c.add_argument("-n", type=int, default=20)
+    u = sub.add_parser("undo", help="undo a change")
+    u.add_argument("id")
+    u.add_argument("--dsn")
+    u.add_argument("--force", action="store_true")
+    lg = sub.add_parser("log", help="show the audit log")
+    lg.add_argument("-n", type=int, default=30)
+    lg.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    if args.cmd == "serve":
+        from .server import main as serve
+        return serve(args.dsn)
+
+    j = Journal()
+    if args.cmd == "pending":
+        rows = j.list_pending()
+        if not rows:
+            print("nothing waiting")
+        for p in rows:
+            print(f"{p['id']}  {_ts(p['ts'])}  {', '.join(json.loads(p['reasons']))}\n    {p['sql']}\n")
+    elif args.cmd in ("approve", "deny"):
+        p = j.get_pending(args.id)
+        if not p:
+            sys.exit(f"unknown approval id {args.id}")
+        print(f"SQL:\n  {p['sql']}\nReasons: {', '.join(json.loads(p['reasons']))}")
+        if args.cmd == "approve":
+            # Agents run shell commands without a TTY. Requiring one keeps an agent
+            # from approving its own SQL via `pgbrake approve`.
+            if not (sys.stdin.isatty() and sys.stdout.isatty()):
+                sys.exit("pgbrake approve must be run by a human in an interactive terminal")
+            if input("Approve? [y/N] ").strip().lower() != "y":
+                sys.exit("not approved")
+        ok = j.decide(args.id, "approved" if args.cmd == "approve" else "denied")
+        print(("approved" if args.cmd == "approve" else "denied") if ok else "already decided")
+    elif args.cmd == "changes":
+        for ch in j.changes(args.n):
+            state = f"undone {_ts(ch['undone_at'])}" if ch["undone_at"] else "undoable"
+            print(f"{ch['id']}  {_ts(ch['ts'])}  {ch['op']:6} {ch['tbl']}  {ch['rows']} row(s)  [{state}]\n    {ch['sql']}")
+    elif args.cmd == "undo":
+        from .engine import Brake
+        dsn = args.dsn or os.environ.get("PGBRAKE_DSN") or os.environ.get("DATABASE_URL")
+        if not dsn:
+            sys.exit("set PGBRAKE_DSN or pass --dsn")
+        r = Brake(dsn, journal=j, client="cli").undo(args.id, force=args.force)
+        print(r.message)
+        sys.exit(0 if r.status == "ok" else 1)
+    elif args.cmd == "log":
+        rows = j.audit(args.n)
+        if args.json:
+            print(json.dumps(rows, indent=1, default=str))
+        else:
+            for r in reversed(rows):
+                print(f"{_ts(r['ts'])}  {r['decision']:14} {r['kind'] or '':6} {r['rowcount'] if r['rowcount'] is not None else '':>5}  {r['sql'][:120]}")
+
+
+if __name__ == "__main__":
+    main()

pgbrake-0.1.0/src/pgbrake/engine.py

@@ -0,0 +1,273 @@
+"""The brake: decide, capture before-images, execute, undo.
+
+All enforcement lives here (server side), so it holds even when the MCP
+client's own permission prompts or hooks are skipped.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+import psycopg
+from psycopg import sql as S
+from psycopg.rows import dict_row
+from psycopg.types.json import Jsonb
+
+from .classify import Kind, Statement, classify
+from .journal import Journal, sql_hash
+
+
+@dataclass
+class Policy:
+    max_rows: int = int(os.environ.get("PGBRAKE_MAX_ROWS", "100"))
+    allow_ddl: bool = os.environ.get("PGBRAKE_ALLOW_DDL", "0") == "1"
+    read_only: bool = os.environ.get("PGBRAKE_READ_ONLY", "0") == "1"
+    statement_timeout_ms: int = int(os.environ.get("PGBRAKE_STATEMENT_TIMEOUT_MS", "15000"))
+    max_result_rows: int = 500
+
+
+@dataclass
+class Result:
+    status: str                      # ok | needs_approval | denied | error
+    message: str = ""
+    rows: list[dict] = field(default_factory=list)
+    rowcount: int | None = None
+    change_ids: list[str] = field(default_factory=list)
+    pending_id: str | None = None
+    reasons: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = {k: v for k, v in self.__dict__.items() if v not in (None, [], "")}
+        return json.loads(json.dumps(d, default=str))
+
+
+class NeedsApproval(Exception):
+    def __init__(self, reasons):
+        self.reasons = reasons
+
+
+class Brake:
+    def __init__(self, dsn: str, journal: Journal | None = None, policy: Policy | None = None,
+                 client: str | None = None):
+        self.dsn = dsn
+        self.journal = journal or Journal()
+        self.policy = policy or Policy()
+        self.client = client
+        self.db_label = psycopg.conninfo.conninfo_to_dict(dsn).get("dbname") if "=" in dsn or "://" in dsn else dsn
+
+    def _connect(self):
+        return psycopg.connect(self.dsn, row_factory=dict_row, autocommit=False,
+                               options=f"-c statement_timeout={self.policy.statement_timeout_ms}")
+
+    # ---- decision ----------------------------------------------------
+    def _static_reasons(self, stmts: list[Statement]) -> tuple[list[str], list[str]]:
+        deny, approve = [], []
+        for st in stmts:
+            if st.kind == Kind.BLOCKED:
+                deny += st.reasons or [f"{st.node} blocked"]
+            elif self.policy.read_only and st.kind != Kind.READ:
+                deny.append(f"read-only mode: {st.node} refused")
+            elif st.kind == Kind.DDL and not self.policy.allow_ddl:
+                approve += st.reasons
+            elif st.kind in (Kind.BULK_WRITE, Kind.OTHER):
+                approve += st.reasons or [f"{st.node} needs approval"]
+            elif st.kind == Kind.WRITE and not st.undo_supported:
+                approve += st.reasons
+        return deny, approve
+
+    def run(self, sql: str, approval_id: str | None = None) -> Result:
+        try:
+            stmts = classify(sql)
+        except Exception as e:  # parse error: refuse rather than guess
+            r = Result("denied", f"could not parse SQL: {e}")
+            self.journal.log(sql=sql, decision="denied", message=r.message, client=self.client, db=self.db_label)
+            return r
+        if not stmts:
+            return Result("error", "empty statement")
+        kind = max((s.kind.value for s in stmts), key=lambda k: list(Kind._value2member_map_).index(k))
+
+        deny, approve = self._static_reasons(stmts)
+        if deny:
+            r = Result("denied", "refused by pgbrake policy", reasons=deny)
+            self.journal.log(sql=sql, kind=kind, decision="denied", message="; ".join(deny),
+                             client=self.client, db=self.db_label)
+            return r
+
+        approved = False
+        if approval_id:
+            p = self.journal.get_pending(approval_id)
+            if not p or p["sql_hash"] != sql_hash(sql):
+                return Result("denied", "approval id does not match this exact SQL")
+            if p["status"] != "approved":
+                return Result("needs_approval", f"approval {approval_id} is {p['status']}; a human must approve it",
+                              pending_id=approval_id)
+            if p["expires"] < time.time():
+                return Result("denied", "approval expired; request a new one")
+            approved = True
+        elif approve:
+            return self._pend(sql, kind, approve)
+
+        try:
+            return self._execute(sql, stmts, kind, approved, approval_id)
+        except NeedsApproval as na:
+            return self._pend(sql, kind, na.reasons)
+        except psycopg.Error as e:
+            msg = str(e).strip()
+            self.journal.log(sql=sql, kind=kind, decision="error", message=msg, client=self.client, db=self.db_label)
+            return Result("error", msg)
+
+    def _pend(self, sql, kind, reasons) -> Result:
+        pid = self.journal.add_pending(db=self.db_label, sql=sql, reasons=reasons)
+        self.journal.log(sql=sql, kind=kind, decision="needs_approval", pending_id=pid,
+                         message="; ".join(reasons), client=self.client, db=self.db_label)
+        return Result("needs_approval",
+                      f"Held for human approval. A person must run `pgbrake approve {pid}` "
+                      f"(or accept the prompt in their client), then call execute again with approval_id.",
+                      pending_id=pid, reasons=reasons)
+
+    # ---- execution ---------------------------------------------------
+    def _pk(self, conn, st: Statement) -> list[str]:
+        rows = conn.execute(
+            """SELECT a.attname FROM pg_index i
+               JOIN pg_attribute a ON a.attrelid=i.indrelid AND a.attnum = ANY(i.indkey)
+               WHERE i.indrelid = %s::regclass AND i.indisprimary ORDER BY a.attnum""",
+            (st.qualified_table,)).fetchall()
+        return [r["attname"] for r in rows]
+
+    def _capture(self, conn, st: Statement) -> list[dict]:
+        target = S.SQL(st.qualified_table)
+        ref = S.Identifier(st.alias) if st.alias else target
+        from_ = S.SQL("{} AS {}").format(target, S.Identifier(st.alias)) if st.alias else target
+        if st.from_sql:
+            from_ = S.SQL("{}, {}").format(from_, S.SQL(st.from_sql))
+        q = S.SQL("SELECT to_jsonb({ref}) AS r FROM {from_} WHERE {where} FOR UPDATE OF {lock}").format(
+            ref=ref, from_=from_, where=S.SQL(st.where_sql),
+            lock=S.Identifier(st.alias) if st.alias else S.Identifier(st.table))
+        seen, out = set(), []
+        for r in conn.execute(q).fetchall():  # join-based writes can repeat target rows
+            key = json.dumps(r["r"], sort_keys=True, default=str)
+            if key not in seen:
+                seen.add(key)
+                out.append(r["r"])
+        return out
+
+    def _refetch(self, conn, st: Statement, pk: list[str], rows: list[dict]) -> list[dict]:
+        if not rows or not pk:
+            return []
+        q = S.SQL("SELECT to_jsonb(t) AS r FROM {tbl} t JOIN jsonb_populate_recordset(NULL::{tbl}, %s) k "
+                  "USING ({pk})").format(tbl=S.SQL(st.qualified_table), pk=S.SQL(", ").join(map(S.Identifier, pk)))
+        return [r["r"] for r in conn.execute(q, (Jsonb(rows),)).fetchall()]
+
+    def _execute(self, sql, stmts, kind, approved, approval_id) -> Result:
+        change_ids: list[str] = []
+        total = 0
+        out_rows: list[dict] = []
+        with self._connect() as conn:
+            if kind == Kind.READ.value:
+                conn.read_only = True
+            pending_changes = []
+            for st in stmts:
+                before, pk = [], []
+                if st.kind in (Kind.WRITE, Kind.BULK_WRITE) and st.table and st.undo_supported:
+                    pk = self._pk(conn, st)
+                    if st.node in ("UpdateStmt", "DeleteStmt"):
+                        if st.where_sql is None:  # bulk, approved: capture whole table
+                            st.where_sql = "true"
+                        before = self._capture(conn, st)
+                        if len(before) > self.policy.max_rows and not approved:
+                            conn.rollback()
+                            raise NeedsApproval([f"{st.node[:-4].upper()} would touch {len(before)} rows "
+                                                 f"(limit {self.policy.max_rows})"])
+                        if st.node == "UpdateStmt" and not pk:
+                            if not approved:
+                                conn.rollback()
+                                raise NeedsApproval([f"{st.table} has no primary key; UPDATE cannot be undone"])
+                exec_sql = st.sql
+                if st.node == "InsertStmt" and st.undo_supported and st.table:
+                    exec_sql = f"WITH _pgbrake AS ({st.sql}{'' if st.has_returning else ' RETURNING *'}) " \
+                               f"SELECT to_jsonb(_pgbrake) AS r FROM _pgbrake"
+                cur = conn.execute(exec_sql)
+                rc = cur.rowcount
+                rows = cur.fetchall() if cur.description else []
+                if st.node == "InsertStmt" and st.undo_supported and st.table:
+                    inserted = [r["r"] for r in rows]
+                    rows = inserted if st.has_returning else []
+                    rc = len(inserted)
+                    if rc > self.policy.max_rows and not approved:
+                        conn.rollback()
+                        raise NeedsApproval([f"INSERT of {rc} rows (limit {self.policy.max_rows})"])
+                    if pk and inserted and all(k in inserted[0] for k in pk):
+                        pending_changes.append(dict(tbl=st.qualified_table, op="insert", pk_cols=pk,
+                                                    before=[], after=[{k: r[k] for k in pk} for r in inserted],
+                                                    sql=st.sql))
+                elif st.node == "UpdateStmt" and before:
+                    after = self._refetch(conn, st, pk, [{k: r[k] for k in pk} for r in before])
+                    pending_changes.append(dict(tbl=st.qualified_table, op="update", pk_cols=pk,
+                                                before=before, after=after, sql=st.sql))
+                elif st.node == "DeleteStmt" and before:
+                    pending_changes.append(dict(tbl=st.qualified_table, op="delete", pk_cols=pk,
+                                                before=before, after=[], sql=st.sql))
+                if st.kind in (Kind.WRITE, Kind.BULK_WRITE) and rc and rc > self.policy.max_rows and not approved:
+                    conn.rollback()
+                    raise NeedsApproval([f"{st.node} affected {rc} rows (limit {self.policy.max_rows})"])
+                total += max(rc, 0) if rc is not None else 0
+                out_rows = rows[: self.policy.max_result_rows]
+            conn.commit()
+        for ch in pending_changes:
+            change_ids.append(self.journal.add_change(db=self.db_label, **ch))
+        if approval_id:
+            self.journal.decide(approval_id, "used")
+        self.journal.log(sql=sql, kind=kind, decision="approved" if approved else "allowed",
+                         rowcount=total, change_ids=change_ids, client=self.client, db=self.db_label)
+        msg = f"{total} row(s) affected" if kind != Kind.READ.value else f"{len(out_rows)} row(s)"
+        if change_ids:
+            msg += f"; undo with change id {', '.join(change_ids)}"
+        return Result("ok", msg, rows=out_rows, rowcount=total, change_ids=change_ids)
+
+    # ---- undo ----------------------------------------------------------
+    def undo(self, change_id: str, force: bool = False) -> Result:
+        ch = self.journal.get_change(change_id)
+        if not ch:
+            return Result("error", f"unknown change {change_id} (free tier keeps the last 20 changes)")
+        if ch["undone_at"]:
+            return Result("error", f"{change_id} was already undone")
+        tbl, pk = S.SQL(ch["tbl"]), ch["pk_cols"]
+        pkl = S.SQL(", ").join(map(S.Identifier, pk))
+        with self._connect() as conn:
+            if ch["op"] in ("update", "insert") and not force and ch["after"]:
+                # conflict check: rows must still look the way pgbrake left them
+                cur = conn.execute(S.SQL(
+                    "SELECT count(*) AS n FROM {t} t JOIN jsonb_populate_recordset(NULL::{t}, %s) k USING ({pk})"
+                ).format(t=tbl, pk=pkl), (Jsonb(ch["after"]),)).fetchone()["n"]
+                if cur != len(ch["after"]):
+                    return Result("error", f"{len(ch['after']) - cur} row(s) changed or vanished since; "
+                                           f"re-run with force=true to undo anyway")
+            cols = [r["attname"] for r in conn.execute(
+                "SELECT attname FROM pg_attribute WHERE attrelid=%s::regclass AND attnum>0 AND NOT attisdropped "
+                "AND attgenerated='' ORDER BY attnum", (ch["tbl"],)).fetchall()]
+            cl = S.SQL(", ").join(map(S.Identifier, cols))
+            if ch["op"] == "delete":
+                q = S.SQL("INSERT INTO {t} ({c}) OVERRIDING SYSTEM VALUE SELECT {c} FROM "
+                          "jsonb_populate_recordset(NULL::{t}, %s)").format(t=tbl, c=cl)
+                n = conn.execute(q, (Jsonb(ch["before"]),)).rowcount
+            elif ch["op"] == "update":
+                setcols = [c for c in cols if c not in pk]
+                q = S.SQL("UPDATE {t} AS t SET ({c}) = ({rc}) FROM jsonb_populate_recordset(NULL::{t}, %s) AS r "
+                          "WHERE {on}").format(
+                    t=tbl, c=S.SQL(", ").join(map(S.Identifier, setcols)),
+                    rc=S.SQL(", ").join(S.SQL("r.{}").format(S.Identifier(c)) for c in setcols),
+                    on=S.SQL(" AND ").join(S.SQL("t.{0} = r.{0}").format(S.Identifier(k)) for k in pk))
+                n = conn.execute(q, (Jsonb(ch["before"]),)).rowcount
+            else:  # insert
+                q = S.SQL("DELETE FROM {t} AS t USING jsonb_populate_recordset(NULL::{t}, %s) AS r WHERE {on}").format(
+                    t=tbl, on=S.SQL(" AND ").join(S.SQL("t.{0} = r.{0}").format(S.Identifier(k)) for k in pk))
+                n = conn.execute(q, (Jsonb(ch["after"]),)).rowcount
+            conn.commit()
+        self.journal.mark_undone(change_id)
+        self.journal.log(sql=f"-- undo {change_id}", kind="undo", decision="allowed", rowcount=n,
+                         change_ids=[change_id], client=self.client, db=self.db_label)
+        return Result("ok", f"undid {ch['op']} on {ch['tbl']}: {n} row(s) restored", rowcount=n,
+                      change_ids=[change_id])

pgbrake-0.1.0/src/pgbrake/journal.py

@@ -0,0 +1,125 @@
+"""Local SQLite journal: audit log, undoable changes, pending approvals.
+
+Everything stays on the developer's machine (default ~/.pgbrake/journal.db).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import secrets
+import sqlite3
+import time
+from pathlib import Path
+
+FREE_UNDO_HISTORY = 20          # free tier keeps the last N undoable changes
+APPROVAL_TTL_SECONDS = 15 * 60
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS audit (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts REAL NOT NULL, client TEXT, db TEXT, sql TEXT NOT NULL, kind TEXT,
+  decision TEXT NOT NULL, rowcount INTEGER, change_ids TEXT, pending_id TEXT, message TEXT
+);
+CREATE TABLE IF NOT EXISTS changes (
+  id TEXT PRIMARY KEY, ts REAL NOT NULL, db TEXT, tbl TEXT NOT NULL, op TEXT NOT NULL,
+  pk_cols TEXT NOT NULL, before TEXT, after TEXT, sql TEXT, undone_at REAL
+);
+CREATE TABLE IF NOT EXISTS pending (
+  id TEXT PRIMARY KEY, ts REAL NOT NULL, db TEXT, sql TEXT NOT NULL, sql_hash TEXT NOT NULL,
+  reasons TEXT, status TEXT NOT NULL DEFAULT 'pending', decided_at REAL, expires REAL NOT NULL
+);
+"""
+
+
+def default_path() -> Path:
+    return Path(os.environ.get("PGBRAKE_JOURNAL", Path.home() / ".pgbrake" / "journal.db"))
+
+
+def sql_hash(sql: str) -> str:
+    return hashlib.sha256(sql.strip().encode()).hexdigest()
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{secrets.token_hex(4)}"
+
+
+class Journal:
+    def __init__(self, path: str | Path | None = None, undo_history: int | None = FREE_UNDO_HISTORY):
+        self.path = Path(path) if path else default_path()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.undo_history = undo_history
+        self.db = sqlite3.connect(self.path, isolation_level=None, check_same_thread=False)
+        self.db.row_factory = sqlite3.Row
+        self.db.executescript(SCHEMA)
+
+    # ---- audit -------------------------------------------------------
+    def log(self, *, sql, decision, kind=None, rowcount=None, change_ids=None,
+            pending_id=None, message=None, client=None, db=None):
+        self.db.execute(
+            "INSERT INTO audit(ts,client,db,sql,kind,decision,rowcount,change_ids,pending_id,message)"
+            " VALUES (?,?,?,?,?,?,?,?,?,?)",
+            (time.time(), client, db, sql, kind, decision, rowcount,
+             json.dumps(change_ids or []), pending_id, message))
+
+    def audit(self, limit=50):
+        return [dict(r) for r in self.db.execute(
+            "SELECT * FROM audit ORDER BY id DESC LIMIT ?", (limit,))]
+
+    # ---- changes -----------------------------------------------------
+    def add_change(self, *, db, tbl, op, pk_cols, before, after, sql) -> str:
+        cid = new_id("chg")
+        self.db.execute(
+            "INSERT INTO changes(id,ts,db,tbl,op,pk_cols,before,after,sql) VALUES (?,?,?,?,?,?,?,?,?)",
+            (cid, time.time(), db, tbl, op, json.dumps(pk_cols),
+             json.dumps(before, default=str), json.dumps(after, default=str), sql))
+        self._prune()
+        return cid
+
+    def _prune(self):
+        if self.undo_history is None:
+            return
+        self.db.execute(
+            "DELETE FROM changes WHERE id NOT IN (SELECT id FROM changes ORDER BY ts DESC LIMIT ?)",
+            (self.undo_history,))
+
+    def get_change(self, cid):
+        r = self.db.execute("SELECT * FROM changes WHERE id=?", (cid,)).fetchone()
+        if not r:
+            return None
+        d = dict(r)
+        for k in ("pk_cols", "before", "after"):
+            d[k] = json.loads(d[k]) if d[k] else None
+        return d
+
+    def changes(self, limit=20):
+        return [{k: r[k] for k in ("id", "ts", "tbl", "op", "sql", "undone_at")} |
+                {"rows": len(json.loads(r["before"] or "[]") or json.loads(r["after"] or "[]"))}
+                for r in self.db.execute("SELECT * FROM changes ORDER BY ts DESC LIMIT ?", (limit,))]
+
+    def mark_undone(self, cid):
+        self.db.execute("UPDATE changes SET undone_at=? WHERE id=?", (time.time(), cid))
+
+    # ---- approvals ---------------------------------------------------
+    def add_pending(self, *, db, sql, reasons) -> str:
+        pid = new_id("apv")
+        now = time.time()
+        self.db.execute(
+            "INSERT INTO pending(id,ts,db,sql,sql_hash,reasons,expires) VALUES (?,?,?,?,?,?,?)",
+            (pid, now, db, sql, sql_hash(sql), json.dumps(reasons), now + APPROVAL_TTL_SECONDS))
+        return pid
+
+    def get_pending(self, pid):
+        r = self.db.execute("SELECT * FROM pending WHERE id=?", (pid,)).fetchone()
+        return dict(r) if r else None
+
+    def list_pending(self):
+        return [dict(r) for r in self.db.execute(
+            "SELECT * FROM pending WHERE status='pending' AND expires>? ORDER BY ts", (time.time(),))]
+
+    def decide(self, pid, status):
+        assert status in ("approved", "denied", "used")
+        cur = self.db.execute(
+            "UPDATE pending SET status=?, decided_at=? WHERE id=? AND status IN ('pending','approved')",
+            (status, time.time(), pid))
+        return cur.rowcount == 1

pgbrake-0.1.0/src/pgbrake/server.py

@@ -0,0 +1,79 @@
+"""MCP server exposing pgbrake tools over stdio."""
+from __future__ import annotations
+
+import json
+import os
+
+from pydantic import BaseModel, Field
+
+try:  # mcp >= 2
+    from mcp.server.mcpserver import Context, MCPServer as _Server
+except ImportError:  # mcp 1.x
+    from mcp.server.fastmcp import Context, FastMCP as _Server
+
+from .engine import Brake
+
+INSTRUCTIONS = """pgbrake guards a Postgres database. Use `query` for reads and `execute` for writes.
+Writes return a change id that `undo` can reverse. Risky SQL (DDL, writes without WHERE,
+writes over the row limit) is held for HUMAN approval: tell the user the approval id and
+wait; never try to approve it yourself or work around the brake with other tools."""
+
+
+class Approve(BaseModel):
+    approve: bool = Field(description="Run this SQL against the database?")
+
+
+def build(dsn: str | None = None) -> _Server:
+    dsn = dsn or os.environ.get("PGBRAKE_DSN") or os.environ.get("DATABASE_URL")
+    if not dsn:
+        raise SystemExit("pgbrake: set PGBRAKE_DSN (or DATABASE_URL) or pass --dsn")
+    brake = Brake(dsn, client=os.environ.get("PGBRAKE_CLIENT", "mcp"))
+    mcp = _Server("pgbrake", instructions=INSTRUCTIONS)
+
+    def dump(r):
+        return json.dumps(r.to_dict(), ensure_ascii=False, indent=1)
+
+    @mcp.tool(description="Run a read-only SQL query (SELECT/EXPLAIN). Writes are rejected here.")
+    def query(sql: str) -> str:
+        brake.policy.read_only, prev = True, brake.policy.read_only
+        try:
+            return dump(brake.run(sql))
+        finally:
+            brake.policy.read_only = prev
+
+    @mcp.tool(description="Run SQL that may modify data. Returns rows, a change id for undo, or an "
+                          "approval id when a human must approve first.")
+    async def execute(sql: str, ctx: Context, approval_id: str | None = None) -> str:
+        r = brake.run(sql, approval_id=approval_id)
+        if r.status == "needs_approval" and r.pending_id and not approval_id:
+            try:  # ask the human directly if the client supports elicitation
+                ans = await ctx.elicit(
+                    message=f"pgbrake is holding this SQL ({'; '.join(r.reasons)}):\n\n{sql}", schema=Approve)
+                if getattr(ans, "action", None) == "accept" and ans.data and ans.data.approve:
+                    brake.journal.decide(r.pending_id, "approved")
+                    return dump(brake.run(sql, approval_id=r.pending_id))
+                if getattr(ans, "action", None) in ("decline", "accept"):
+                    brake.journal.decide(r.pending_id, "denied")
+                    return dump(r.__class__("denied", "the user declined this SQL", pending_id=r.pending_id))
+            except Exception:
+                pass  # client has no elicitation: fall back to `pgbrake approve <id>` in a terminal
+        return dump(r)
+
+    @mcp.tool(description="Reverse a change made through pgbrake, by change id.")
+    def undo(change_id: str, force: bool = False) -> str:
+        return dump(brake.undo(change_id, force=force))
+
+    @mcp.tool(description="List recent changes that can be undone.")
+    def list_changes(limit: int = 20) -> str:
+        return json.dumps(brake.journal.changes(limit), default=str, indent=1)
+
+    @mcp.tool(description="Check whether an approval id has been approved by a human yet.")
+    def approval_status(approval_id: str) -> str:
+        p = brake.journal.get_pending(approval_id)
+        return json.dumps({"approval_id": approval_id, "status": p["status"] if p else "unknown"})
+
+    return mcp
+
+
+def main(dsn: str | None = None):
+    build(dsn).run()

pgbrake-0.1.0/tests/test_brake.py

@@ -0,0 +1,109 @@
+import os
+
+import psycopg
+import pytest
+
+from pgbrake.classify import Kind, classify
+from pgbrake.engine import Brake, Policy
+from pgbrake.journal import Journal
+
+DSN = os.environ.get("PGBRAKE_TEST_DSN", "host=/tmp port=5544 user=postgres dbname=demo")
+
+
+def test_classify():
+    k = lambda s: [x.kind for x in classify(s)]
+    assert k("select 1") == [Kind.READ]
+    assert k("delete from t where id=1") == [Kind.WRITE]
+    assert k("delete from t") == [Kind.BULK_WRITE]
+    assert k("update t set a=1") == [Kind.BULK_WRITE]
+    assert k("drop table t") == [Kind.DDL]
+    assert k("truncate t") == [Kind.BULK_WRITE]
+    assert k("alter system set x=1") == [Kind.BLOCKED]
+    assert k("copy t to program 'rm -rf /'") == [Kind.BLOCKED]
+    assert k("with d as (delete from t returning *) select * from d") == [Kind.WRITE]
+    assert k("begin") == [Kind.BLOCKED]
+
+
+@pytest.fixture
+def brake(tmp_path):
+    with psycopg.connect(DSN, autocommit=True) as c:
+        c.execute("drop table if exists users; create table users(id serial primary key, email text, plan text)")
+        c.execute("insert into users(email, plan) select 'u'||g||'@x.com', 'free' from generate_series(1,300) g")
+    return Brake(DSN, journal=Journal(tmp_path / "j.db"), policy=Policy(max_rows=100))
+
+
+def count(where="true"):
+    with psycopg.connect(DSN) as c:
+        return c.execute(f"select count(*) from users where {where}").fetchone()[0]
+
+
+def test_read(brake):
+    r = brake.run("select count(*) as n from users")
+    assert r.status == "ok" and r.rows[0]["n"] == 300
+
+
+def test_delete_and_undo(brake):
+    r = brake.run("delete from users where id <= 10")
+    assert r.status == "ok" and r.rowcount == 10 and count() == 290
+    u = brake.undo(r.change_ids[0])
+    assert u.status == "ok" and count() == 300
+
+
+def test_update_and_undo_with_alias(brake):
+    r = brake.run("update users as x set plan='pro' where x.id between 1 and 5")
+    assert r.status == "ok" and count("plan='pro'") == 5
+    assert brake.undo(r.change_ids[0]).status == "ok"
+    assert count("plan='pro'") == 0
+
+
+def test_insert_and_undo(brake):
+    r = brake.run("insert into users(email, plan) values ('a@b.c','free'), ('d@e.f','free')")
+    assert r.status == "ok" and count() == 302
+    assert brake.undo(r.change_ids[0]).status == "ok" and count() == 300
+
+
+def test_row_limit_holds_then_human_approves(brake):
+    r = brake.run("delete from users where id <= 200")
+    assert r.status == "needs_approval" and count() == 300
+    again = brake.run("delete from users where id <= 200", approval_id=r.pending_id)
+    assert again.status == "needs_approval"           # agent cannot self-approve
+    brake.journal.decide(r.pending_id, "approved")     # human: `pgbrake approve <id>`
+    ok = brake.run("delete from users where id <= 200", approval_id=r.pending_id)
+    assert ok.status == "ok" and count() == 100
+    assert brake.run("delete from users where id <= 200", approval_id=r.pending_id).status != "ok"  # one-shot
+    assert brake.undo(ok.change_ids[0]).status == "ok" and count() == 300
+
+
+def test_approval_bound_to_exact_sql(brake):
+    r = brake.run("drop table users")
+    brake.journal.decide(r.pending_id, "approved")
+    assert brake.run("drop table users cascade", approval_id=r.pending_id).status == "denied"
+
+
+def test_bulk_and_ddl_held(brake):
+    assert brake.run("delete from users").status == "needs_approval"
+    assert brake.run("drop table users").status == "needs_approval"
+    assert count() == 300
+
+
+def test_blocked(brake):
+    assert brake.run("alter system set work_mem='1GB'").status == "denied"
+
+
+def test_undo_conflict_detection(brake):
+    r = brake.run("update users set plan='pro' where id=1")
+    with psycopg.connect(DSN, autocommit=True) as c:
+        c.execute("delete from users where id=1")
+    assert brake.undo(r.change_ids[0]).status == "error"
+
+
+def test_multi_statement_atomic(brake):
+    r = brake.run("delete from users where id=1; delete from nope where id=1")
+    assert r.status == "error" and count() == 300
+
+
+def test_audit_log(brake):
+    brake.run("select 1")
+    brake.run("delete from users")
+    decisions = [a["decision"] for a in brake.journal.audit()]
+    assert "needs_approval" in decisions and "allowed" in decisions