localtools-postgres-migration-checker 1.0.0__py3-none-any.whl

localtools_postgres_migration_checker/engine.py

@@ -0,0 +1,1429 @@
+"""Check PostgreSQL migrations: parse with postgast (libpg_query, the real PostgreSQL 18 parser), then for every statement
+report the locks it takes, what they block, whether it rewrites or scans the table, the transaction it runs in, and a
+safe rewrite for risky patterns. Behaviour that changed between versions follows the target version (11-18)."""
+import json
+import re
+from bisect import bisect_right
+
+import postgast
+from postgast import nodes as ast, pg_query_pb2 as pb
+from .parser import parse_sql, ParseError, split, sql
+AT, CT, OT, RO, TK, VK = (getattr(pb, n) for n in
+    ("AlterTableType", "ConstrType", "ObjectType", "ReindexObjectType", "TransactionStmtKind", "VariableSetKind"))
+
+from .locks import AE, AS, EX, MODES, RE, RS, SH, SRE, SUE, blocks, blocks_writes, rank, strongest
+
+PG_MIN, PG_MAX, PG_DEFAULT = 11, 18, 18
+SEVERITIES = ("info", "low", "medium", "high")
+MAX_BYTES = 4 << 20  # aggregate UTF-8 SQL bytes, CLI and API
+MAX_STATEMENTS = 5000
+MAX_FILES = 100
+PREVIEW = 600  # characters of each statement echoed back
+SLOW = ("scan", "rewrite", "index", "rows")
+WORK = {
+    "none": "no modelled work; consult findings for unknown operations",
+    "catalog": "catalog change; normally brief once the lock is granted",
+    "scan": "scans the whole table while holding the lock",
+    "rewrite": "rewrites the whole table and rebuilds its indexes while holding the lock",
+    "index": "reads the whole table to build an index while holding the lock",
+    "rows": "time grows with the number of rows it touches",
+}
+TXN_MODES = ("auto", "always", "never")
+
+RULES = {  # id: short title (SARIF rule names, README table)
+    "parse-error": "Statement does not parse",
+    "version": "Not supported by the target PostgreSQL version",
+    "add-column-rewrite": "ADD COLUMN rewrites the table",
+    "add-column-not-null": "ADD COLUMN NOT NULL without a default fails on a non-empty table",
+    "add-column-default-volatility": "ADD COLUMN default may be volatile",
+    "alter-column-type": "ALTER COLUMN TYPE rewrites the table",
+    "set-not-null": "SET NOT NULL scans the table under ACCESS EXCLUSIVE",
+    "add-check": "CHECK constraint is validated under ACCESS EXCLUSIVE",
+    "add-not-null-constraint": "NOT NULL constraint is validated under ACCESS EXCLUSIVE",
+    "add-foreign-key": "FOREIGN KEY is validated while writes to both tables are blocked",
+    "add-unique": "UNIQUE / PRIMARY KEY builds an index under ACCESS EXCLUSIVE",
+    "add-exclusion": "EXCLUDE constraint builds an index under ACCESS EXCLUSIVE",
+    "create-index": "CREATE INDEX blocks writes while it builds",
+    "drop-index": "DROP INDEX takes ACCESS EXCLUSIVE on the table",
+    "reindex": "REINDEX blocks writes (and reads that use the index)",
+    "table-rewrite": "Statement rewrites the whole table under ACCESS EXCLUSIVE",
+    "long-lock": "Long operation under a lock that blocks traffic",
+    "attach-partition": "ATTACH PARTITION scans the new partition",
+    "detach-partition": "DETACH PARTITION takes ACCESS EXCLUSIVE on the parent",
+    "partition-of": "CREATE TABLE ... PARTITION OF takes ACCESS EXCLUSIVE on the parent",
+    "refresh-matview": "REFRESH MATERIALIZED VIEW blocks reads while it runs",
+    "rename": "Rename breaks queries of the running application",
+    "drop-column": "DROP COLUMN loses data and breaks code that still uses it",
+    "drop-table": "DROP / TRUNCATE loses data",
+    "update-all-rows": "UPDATE / DELETE without WHERE touches every row in one transaction",
+    "domain-constraint": "Domain constraint is validated against every column that uses it",
+    "enum-add-value": "ALTER TYPE ... ADD VALUE inside a transaction",
+    "no-transaction": "Statement cannot run inside a transaction block",
+    "lock-outside-transaction": "LOCK TABLE outside a transaction block",
+    "missing-lock-timeout": "No lock_timeout before a lock that blocks traffic",
+    "missing-statement-timeout": "No statement_timeout before a long-running statement",
+    "locks-accumulate": "Locks from earlier statements are held until COMMIT",
+    "not-analysed": "Statement contents are not analysed",
+}
+
+
+class St:
+    """Analysis of one statement."""
+
+    def __init__(self, kind):
+        self.kind, self.locks, self.work, self.findings, self.notx = kind, [], "none", [], ""
+
+    def lock(self, target, mode, new=False):
+        self.locks.append({"target": target, "mode": mode, "new": bool(new)})
+
+    def find(self, rule, sev, msg, fix=""):
+        self.findings.append({"rule": rule, "severity": sev, "message": msg, "fix": fix.strip("\n")})
+
+    def slow(self, work):
+        order = ("none", "catalog", "rows", "scan", "index", "rewrite")
+        if order.index(work) > order.index(self.work):
+            self.work = work
+
+
+class SQLError(ValueError):
+    pass
+
+
+# ---------- names and deparsing ----------
+def qi(name):
+    return '"' + name.replace('"', '""') + '"'
+
+
+def rv(r):
+    """RangeVar -> display/key name ("public." dropped, so public.users and users are the same table)."""
+    parts = [p for p in (r.catalogname, r.schemaname) if p] + [r.relname]
+    return ".".join(qi(p) for p in parts)
+
+
+def dotted(strings):
+    parts = [s.sval for s in strings or () if isinstance(s, ast.String)]
+    return ".".join(qi(p) for p in parts)
+
+
+def ident(*parts, suffix):
+    """PostgreSQL-style generated constraint/index name, truncated to 63 bytes like the server does."""
+    base = "_".join(p.replace('"', "") for p in parts if p)
+    return qi((base[:63 - len(suffix) - 1] + "_" + suffix).lower())
+
+
+def walk(node):
+    stack = [node]
+    while stack:
+        n = stack.pop()
+        if isinstance(n, (tuple, list)):
+            stack.extend(n)
+        elif isinstance(n, ast.AstNode):
+            yield n
+            for a in n.__match_args__:
+                v = getattr(n, a, None)
+                if isinstance(v, (ast.AstNode, tuple, list)):
+                    stack.append(v)
+
+
+VOLATILE = {"random", "random_normal", "clock_timestamp", "timeofday", "nextval", "setval", "currval", "lastval",
+            "gen_random_uuid", "uuid_generate_v1", "uuid_generate_v1mc", "uuid_generate_v4", "uuidv4", "uuidv7",
+            "gen_random_bytes", "txid_current", "pg_current_xact_id", "setseed", "pg_sleep", "dblink"}
+NONVOLATILE = {"now", "transaction_timestamp", "statement_timestamp", "current_setting", "lower", "upper", "length",
+               "concat", "concat_ws", "md5", "abs", "round", "trunc", "floor", "ceil", "date_trunc", "make_interval",
+               "make_date", "make_timestamp", "make_timestamptz", "to_timestamp", "to_date", "to_char", "to_json",
+               "to_jsonb", "json_build_object", "jsonb_build_object", "json_build_array", "jsonb_build_array",
+               "array_fill", "replace", "substring", "btrim", "ltrim", "rtrim", "greatest", "least", "timezone",
+               "date_part", "extract", "current_date", "current_timestamp", "localtimestamp", "jsonb_object",
+               "inet", "int4range", "int8range", "tstzrange", "tsrange", "daterange", "numrange", "point"}
+SERIAL = {"serial", "serial4", "bigserial", "serial8", "smallserial", "serial2"}
+
+
+def volatility(expr):
+    """'volatile', 'unknown' (a function we do not know) or 'stable' (constants, casts, now(), ...)."""
+    seen = "stable"
+    for n in walk(expr):
+        if isinstance(n, ast.FuncCall):
+            f = n.funcname[-1].sval.lower()
+            if len(n.funcname) > 1 and n.funcname[-2].sval != 'pg_catalog':
+                seen = 'unknown'
+                continue
+            if f in VOLATILE:
+                return "volatile"
+            if f not in NONVOLATILE:
+                seen = "unknown"
+        elif isinstance(n, ast.SubLink):
+            seen = "unknown"
+    return seen
+
+
+def type_name(tn):
+    return sql(tn) if tn is not None else "?"
+
+
+def is_serial(tn):
+    return tn is not None and len(tn.names or ()) == 1 and tn.names[0].sval.lower() in SERIAL
+
+
+# ---------- preprocessing: framework markers, psql meta-commands, COPY data, Flyway placeholders ----------
+TOKEN = re.compile(r"--|/\*|['\";\n$]")
+DOLLAR = re.compile(r"\$([A-Za-z_\u0080-\uffff][A-Za-z0-9_\u0080-\uffff]*)?\$")
+COPY_STDIN = re.compile(r"^\s*COPY\b.*\bFROM\s+STDIN\b", re.I | re.S)
+
+
+def _blank(chars, a, b):
+    for i in range(a, b):
+        if chars[i] != "\n":
+            chars[i] = " "
+
+
+def scrub(text):
+    """Blank (same length, newlines kept) psql meta-command lines and COPY ... FROM stdin data blocks, which are not SQL.
+    Returns (text, notes). Quotes, comments and dollar quotes are respected so their contents are never touched."""
+    spans, notes = [], []
+    i, n, stmt, line_start = 0, len(text), 0, True
+    while i < n:
+        if line_start:
+            j = i
+            while j < n and text[j] in " \t":
+                j += 1
+            if j < n and text[j] == "\\":
+                e = text.find("\n", j)
+                e = n if e < 0 else e
+                spans.append((i, e))
+                notes.append((j, f"psql meta-command skipped: {text[j:e].strip()[:60]}"))
+                i, stmt = e, e
+                continue
+            line_start = False
+        m = TOKEN.search(text, i)
+        if not m:
+            break
+        t, i = m.group(), m.end()
+        if t == "\n":
+            line_start = True
+        elif t == "--":
+            e = text.find("\n", i)
+            i = n if e < 0 else e
+        elif t == "/*":
+            depth = 1
+            while depth and i < n:
+                m2 = re.compile(r"/\*|\*/").search(text, i)
+                if not m2:
+                    i = n
+                    break
+                depth += 1 if m2.group() == "/*" else -1
+                i = m2.end()
+        elif t == "'":
+            esc = m.start() > 0 and text[m.start() - 1] in "eE" and (m.start() < 2 or not (text[m.start() - 2].isalnum() or text[m.start() - 2] == "_"))
+            while i < n:
+                c = text[i]
+                if esc and c == "\\":
+                    i += 2
+                    continue
+                i += 1
+                if c == "'":
+                    if i < n and text[i] == "'":
+                        i += 1
+                        continue
+                    break
+        elif t == '"':
+            while i < n:
+                c = text[i]
+                i += 1
+                if c == '"':
+                    if i < n and text[i] == '"':
+                        i += 1
+                        continue
+                    break
+        elif t == "$":
+            s = m.start()
+            if s and (text[s - 1].isalnum() or text[s - 1] in "_$"):
+                continue  # $ inside an identifier
+            d = DOLLAR.match(text, s)
+            if d:
+                e = text.find(d.group(), d.end())
+                i = n if e < 0 else e + len(d.group())
+        elif t == ";":
+            if COPY_STDIN.match(text[stmt:m.start()]):
+                a = text.find("\n", i)
+                if a >= 0:
+                    e = re.compile(r"^\\\.[ \t]*$", re.M).search(text, a + 1)
+                    b = e.end() if e else n
+                    spans.append((a + 1, b))
+                    notes.append((a + 1, "COPY data block skipped"))
+                    i = b
+            stmt = i
+    if not spans:
+        return text, notes
+    chars = list(text)
+    for a, b in spans:
+        _blank(chars, a, b)
+    return "".join(chars), notes
+
+
+MARK = re.compile(r"^[ \t]*--[ \t]*(\+goose[ \t]+(up|down|no[ \t]+transaction)|migrate:(up|down)([^\n]*)"
+                  r"|liquibase[ \t]+formatted[ \t]+sql|changeset[ \t]+[^\n]*)", re.I | re.M)
+FLYWAY = re.compile(r"(^|[\\/])[VRU]\d*[^\\/]*__[^\\/]*\.sql$|(^|[\\/])R__[^\\/]*\.sql$", re.I)
+
+
+def prepare(text, name, txn_mode="auto"):
+    """Returns (sql, units, framework, notes). units = [(start, end, how)]: regions that the runner wraps in one
+    transaction. Down sections (goose, dbmate) are blanked so only the up migration is checked."""
+    try:
+        comments = {t.start for t in postgast.scan(text).tokens if t.token == pb.SQL_COMMENT}
+        marks, last, byte = [], 0, 0
+        for m in MARK.finditer(text):
+            start = m.start() + len(m.group()) - len(m.group().lstrip())
+            byte += len(text[last:start].encode('utf-8'))
+            last = start
+            if byte in comments:
+                marks.append(m)
+    except postgast.PgQueryError:
+        marks = []
+    framework, units, chars, notes = "plain SQL", [], None, []
+    lower = [m.group(1).lower() for m in marks]
+    if any(l.startswith("+goose") for l in lower):
+        framework = "goose"
+        notx = any(re.match(r"\+goose\s+no\s+transaction", l) for l in lower)
+        chars = list(text)
+        up = None
+        for m, l in zip(marks, lower):
+            if l.startswith("+goose") and l.split()[1] in ("up", "down"):
+                if up is not None:
+                    units.append((up, m.start(), "goose"))
+                up = m.end() if l.split()[1] == "up" else None
+                if l.split()[1] == "down":
+                    nxt = next((x.start() for x, y in zip(marks, lower) if x.start() > m.start() and y.split()[:2] == ["+goose", "up"]), len(text))
+                    _blank(chars, m.end(), nxt)
+        if up is not None:
+            units.append((up, len(text), "goose"))
+        if notx:
+            units = []
+    elif any(l.startswith("migrate:") for l in lower):
+        framework = "dbmate"
+        chars = list(text)
+        for m, l in zip(marks, lower):
+            if l.startswith("migrate:down"):
+                nxt = next((x.start() for x, y in zip(marks, lower) if x.start() > m.start() and y.startswith("migrate:up")), len(text))
+                _blank(chars, m.end(), nxt)
+            elif l.startswith("migrate:up") and not re.search(r"transaction:\s*false", l):
+                nxt = next((x.start() for x, y in zip(marks, lower) if x.start() > m.start() and y.startswith("migrate:")), len(text))
+                units.append((m.end(), nxt, "dbmate"))
+    elif any(l.startswith("liquibase") for l in lower):
+        framework = "Liquibase"
+        sets = [(m, l) for m, l in zip(marks, lower) if l.startswith("changeset")]
+        for k, (m, l) in enumerate(sets):
+            end = sets[k + 1][0].start() if k + 1 < len(sets) else len(text)
+            if not re.search(r"runintransaction:\s*false", l):
+                units.append((m.end(), end, "Liquibase changeset"))
+    elif FLYWAY.search(name.replace("\\", "/")):
+        framework = "Flyway"
+        units = [(0, len(text), "Flyway")]
+    if chars is not None:
+        text = "".join(chars)
+    if txn_mode == "always":
+        units = [(0, len(text), "runner")]
+    elif txn_mode == "never":
+        units = []
+    text, more = scrub(text)
+    return text, units, framework, notes + more
+
+
+# ---------- parsing ----------
+def _err_at(text, e):
+    """The parser boundary already converts native UTF-8 byte offsets."""
+    msg, pos = e.args[0], e.args[1] if len(e.args) > 1 else None
+    return msg, len(text.rstrip()) if pos is None else min(pos, len(text))
+
+
+def parse(text):
+    """[(start, end, stmt | None, error | None)] with character offsets. One bad statement does not hide the others."""
+    try:
+        return [(r.stmt_location, r.stmt_location + r.stmt_len if r.stmt_len else len(text), r.stmt, None)
+                for r in parse_sql(text)]
+    except ParseError:
+        pass
+    except RecursionError:
+        raise SQLError("the SQL is nested too deeply to analyse")
+    out, base = [], text
+    try:
+        slices = split(base, with_parser=False, only_slices=True)
+        tail = None
+    except ParseError as e:  # the scanner itself failed (unterminated quote or comment): split up to that point
+        msg, pos = _err_at(base, e)
+        try:
+            slices = split(base[:pos], with_parser=False, only_slices=True)
+        except ParseError:
+            slices = ()
+        last = slices[-1].start if slices else 0
+        slices = slices[:-1] if slices else ()
+        tail = (last + len(base[last:]) - len(base[last:].lstrip()), len(base), None, (msg, pos))
+    for s in slices:
+        piece = base[s]
+        try:
+            for r in parse_sql(piece):
+                out.append((s.start + r.stmt_location, s.start + (r.stmt_location + r.stmt_len if r.stmt_len else len(piece)), r.stmt, None))
+        except ParseError as e:
+            msg, pos = _err_at(piece, e)
+            out.append((s.start, s.stop, None, (msg, s.start + pos)))
+        except RecursionError:
+            out.append((s.start, s.stop, None, ("nested too deeply to analyse", s.start)))
+    if tail:
+        out.append(tail)
+    return out
+
+
+# ---------- per-statement rules ----------
+class Ctx:
+    def __init__(self, pg):
+        self.pg = pg
+        self.tables = {}  # tables created in these migrations: key -> {"cols": {name: type}, "partkey": [cols] | None}
+        self.nn_checks = {}  # (table, constraint) -> column, for CHECK (col IS NOT NULL) [NOT VALID]
+        self.nn_ok = set()  # (table, column) proven NOT NULL by a validated check
+        self.cons = {}  # (table, constraint) -> referenced table for foreign keys
+
+    def new(self, t):
+        return t in self.tables
+
+
+def need(st, ctx, ver, what):
+    if ctx.pg < ver:
+        st.find("version", "high", f"{what} needs PostgreSQL {ver} or later; this statement fails on PostgreSQL {ctx.pg}.")
+
+
+def not_null_fix(t, c, pg):
+    name = ident(t.split(".")[-1], c, suffix="not_null")
+    if pg >= 18:
+        return (f"ALTER TABLE {t} ADD CONSTRAINT {name} NOT NULL {c} NOT VALID;  -- instant\n"
+                f"ALTER TABLE {t} VALIDATE CONSTRAINT {name};  -- scans under SHARE UPDATE EXCLUSIVE: reads and writes continue")
+    fix = (f"ALTER TABLE {t} ADD CONSTRAINT {name} CHECK ({c} IS NOT NULL) NOT VALID;  -- instant\n"
+           f"ALTER TABLE {t} VALIDATE CONSTRAINT {name};  -- scans under SHARE UPDATE EXCLUSIVE: reads and writes continue\n")
+    if pg >= 12:
+        return fix + (f"ALTER TABLE {t} ALTER COLUMN {c} SET NOT NULL;  -- no scan: the validated CHECK proves it (PostgreSQL 12+)\n"
+                      f"ALTER TABLE {t} DROP CONSTRAINT {name};")
+    return fix + "-- PostgreSQL 11 always scans for SET NOT NULL; keep the validated CHECK instead (upgrade to 12+ to convert it)."
+
+
+def backfill(t, c, expr):
+    return (f"-- backfill existing rows in batches, each in its own short transaction; repeat until it updates 0 rows:\n"
+            f"UPDATE {t} SET {c} = {expr} WHERE ctid IN (SELECT ctid FROM {t} WHERE {c} IS NULL LIMIT 5000);")
+
+
+NOTX_FIX = ("-- run it in its own migration without a transaction: goose `-- +goose NO TRANSACTION`, dbmate\n"
+            "-- `-- migrate:up transaction:false`, Rails `disable_ddl_transaction!`, Django `atomic = False`,\n"
+            "-- Flyway `executeInTransaction=false`, Liquibase `runInTransaction:false`; and no BEGIN/COMMIT around it.")
+REPACK = "-- core PostgreSQL has no online variant; pg_repack or pg_squeeze rebuild a table without a long ACCESS EXCLUSIVE lock."
+
+
+def add_column(st, ctx, t, cd):
+    st.slow('catalog')
+    c, tn = qi(cd.colname), cd.type_name
+    cons = list(cd.constraints or ())
+    kinds = {k.contype for k in cons}
+    default = next((k.raw_expr for k in cons if k.contype == CT.CONSTR_DEFAULT), None)
+    gen = next((k for k in cons if k.contype == CT.CONSTR_GENERATED), None)
+    notnull = CT.CONSTR_NOTNULL in kinds or CT.CONSTR_PRIMARY in kinds
+    typ = type_name(tn)
+    new = ctx.new(t)
+    if new:
+        ctx.tables[t]["cols"][cd.colname] = typ
+    rewrite, why = False, ""
+    if gen is not None:
+        virtual = gen.generated_kind != "s"
+        if virtual:
+            need(st, ctx, 18, "A VIRTUAL generated column (the default kind without STORED)")
+        else:
+            rewrite, why = True, "a STORED generated column is computed for every existing row"
+    elif CT.CONSTR_IDENTITY in kinds:
+        rewrite, why = True, "an identity column is filled from its sequence for every existing row"
+    elif is_serial(tn):
+        rewrite, why = True, f"{typ} has a volatile default (nextval) that is evaluated for every existing row"
+    elif default is not None and not (isinstance(default, ast.A_Const) and default.isnull):
+        vol = volatility(default)
+        if vol == "volatile":
+            rewrite, why = True, f"the default {sql(default)} is volatile, so it is evaluated for every existing row"
+        elif ctx.pg < 11:
+            rewrite, why = True, "before PostgreSQL 11 any non-null default rewrites the table"
+        elif vol == "unknown" and not new:
+            st.find("add-column-default-volatility", "medium",
+                    f"The default {sql(default)} calls a function this checker does not know. If it is VOLATILE, adding the "
+                    f"column rewrites {t} under ACCESS EXCLUSIVE; if it is STABLE or IMMUTABLE the change is instant (PostgreSQL 11+).",
+                    f"-- check: SELECT proname, provolatile FROM pg_proc WHERE proname = '...';  ('v' = volatile)\n"
+                    f"ALTER TABLE {t} ADD COLUMN {c} {typ};\nALTER TABLE {t} ALTER COLUMN {c} SET DEFAULT {sql(default)};\n"
+                    + backfill(t, c, sql(default)))
+    if rewrite:
+        st.slow("rewrite")
+        if not new:
+            if gen is not None:
+                fix = ((f"-- PostgreSQL 18+: a VIRTUAL generated column is computed on read; adding it is instant\n"
+                        f"ALTER TABLE {t} ADD COLUMN {c} {typ} GENERATED ALWAYS AS ({sql(gen.raw_expr)}) VIRTUAL;\n" if ctx.pg >= 18 else "")
+                       + f"-- or a plain column kept up to date by a trigger, backfilled in batches:\nALTER TABLE {t} ADD COLUMN {c} {typ};\n"
+                       + backfill(t, c, sql(gen.raw_expr)))
+            elif CT.CONSTR_IDENTITY in kinds or is_serial(tn):
+                base = {"bigserial": "bigint", "serial8": "bigint", "smallserial": "smallint", "serial2": "smallint"}.get(
+                    tn.names[0].sval.lower(), "integer") if is_serial(tn) else typ
+                fix = (f"ALTER TABLE {t} ADD COLUMN {c} {base};  -- instant\n"
+                       f"-- coordinate new writes and backfill unique values in short transactions.\n"
+                       f"-- validate NOT NULL before ADD IDENTITY; then create/align its sequence above every existing value.\n"
+                       f"-- sequence ownership, privileges and concurrent inserts require a schema-specific plan.")
+            else:
+                fix = (f"ALTER TABLE {t} ADD COLUMN {c} {typ};  -- instant\n"
+                       f"ALTER TABLE {t} ALTER COLUMN {c} SET DEFAULT {sql(default)};  -- new rows only, no rewrite\n"
+                       + backfill(t, c, sql(default)))
+            if notnull:
+                fix += "\n" + not_null_fix(t, c, ctx.pg)
+            st.find("add-column-rewrite", "high", f"Adding {c} rewrites {t} while holding ACCESS EXCLUSIVE: {why}. "
+                    "Reads and writes wait for the whole rewrite.", fix)
+    elif notnull and default is None and gen is None and CT.CONSTR_IDENTITY not in kinds and not is_serial(tn) and not new:
+        st.find("add-column-not-null", "medium", f"Adding NOT NULL column {c} without a default fails with "
+                f"\"column contains null values\" if {t} has any rows.",
+                (f"ALTER TABLE {t} ADD COLUMN {c} {typ} NOT NULL DEFAULT <constant>;  -- constant default: no rewrite on PostgreSQL 11+\n"
+                 if ctx.pg >= 11 else "") + f"-- or add it nullable, backfill, then:\n" + not_null_fix(t, c, ctx.pg))
+    for k in cons:
+        if k.contype in (CT.CONSTR_PRIMARY, CT.CONSTR_UNIQUE):
+            st.slow("index")
+            if not new:
+                idx = ident(t.split(".")[-1], cd.colname, suffix="key")
+                st.find("add-unique", "high", f"The inline {'PRIMARY KEY' if k.contype == CT.CONSTR_PRIMARY else 'UNIQUE'} "
+                        f"builds an index on {t} under ACCESS EXCLUSIVE.",
+                        f"ALTER TABLE {t} ADD COLUMN {c} {typ};\nCREATE UNIQUE INDEX CONCURRENTLY {idx} ON {t} ({c});  -- outside a transaction\n"
+                        f"ALTER TABLE {t} ADD CONSTRAINT {idx} {'PRIMARY KEY' if k.contype == CT.CONSTR_PRIMARY else 'UNIQUE'} USING INDEX {idx};")
+        elif k.contype == CT.CONSTR_FOREIGN:
+            ref = rv(k.pktable)
+            st.lock(ref, SRE, ctx.new(ref))
+            if default is not None and not new:
+                st.slow("scan")
+        elif k.contype == CT.CONSTR_CHECK and not new and (default is not None or gen is not None):
+            st.slow("scan")
+
+
+def alter_type(st, ctx, t, cmd):
+    c, cd = qi(cmd.name), cmd.def_
+    typ = type_name(cd.type_name)
+    if ctx.new(t):
+        ctx.tables[t]["cols"][cmd.name] = typ
+        st.slow("rewrite")
+        return
+    st.slow("rewrite")
+    hint = (" unless the change is binary-coercible (varchar(n) to a longer varchar or text, "
+            "numeric(p,s) to a larger precision with the same scale, dropping a length limit, cidr to inet)")
+    tz = " (timestamp to timestamptz skips it on PostgreSQL 12+ only when the session TimeZone is UTC)" if "timestamp with time zone" in typ else ""
+    tmp = qi((cmd.name + "_new")[:63])
+    fix = (f"-- expand/contract instead of one long ACCESS EXCLUSIVE rewrite:\n"
+           f"ALTER TABLE {t} ADD COLUMN {tmp} {typ};\n"
+           f"-- keep new writes in sync with a trigger (SET NEW.{tmp} := NEW.{c}::{typ}), then backfill in batches:\n"
+           f"UPDATE {t} SET {tmp} = {c}::{typ} WHERE ctid IN (SELECT ctid FROM {t} WHERE {tmp} IS NULL AND {c} IS NOT NULL LIMIT 5000);\n"
+           f"-- finally, in one short transaction with lock_timeout set:\n"
+           f"ALTER TABLE {t} RENAME COLUMN {c} TO {qi((cmd.name + '_old')[:63])};\nALTER TABLE {t} RENAME COLUMN {tmp} TO {c};")
+    maybe = re.match(r"(text|varchar|character varying|numeric|varbit|bit varying|inet)\b", typ)
+    st.find("alter-column-type", "medium" if maybe else "high",
+            f"Changing {c} to {typ} rewrites {t} and rebuilds its indexes under ACCESS EXCLUSIVE{hint}{tz}.", fix)
+
+
+def add_constraint(st, ctx, t, con, tname):
+    new, k = ctx.new(t), con.contype
+    name = con.conname
+    if k == CT.CONSTR_FOREIGN:
+        ref = rv(con.pktable)
+        st.lock(t, SRE, new)
+        st.lock(ref, SRE, ctx.new(ref))
+        if name:
+            ctx.cons[(t, name)] = ref
+        if con.skip_validation:
+            st.slow("catalog")
+        else:
+            st.slow("scan")
+            if not new:
+                name = name or ident(tname, *(a.sval for a in con.fk_attrs or ()), suffix="fkey")
+                con2 = sql(con).replace(" NOT VALID", "")
+                if not con.conname:
+                    con2 = f"CONSTRAINT {name} " + con2
+                st.find("add-foreign-key", "high", f"Adding the foreign key scans {t} to validate every row while holding "
+                        f"SHARE ROW EXCLUSIVE on {t} and {ref}: writes to both tables wait.",
+                        f"ALTER TABLE {t} ADD {con2} NOT VALID;  -- instant; new rows are checked from now on\n"
+                        f"ALTER TABLE {t} VALIDATE CONSTRAINT {name};  -- SHARE UPDATE EXCLUSIVE: reads and writes continue")
+        return
+    st.lock(t, AE, new)
+    if k == CT.CONSTR_CHECK:
+        col = None
+        e = con.raw_expr
+        if isinstance(e, ast.NullTest) and e.nulltesttype == pb.IS_NOT_NULL and isinstance(e.arg, ast.ColumnRef) and len(e.arg.fields) == 1:
+            col = e.arg.fields[0].sval
+        if con.skip_validation:
+            st.slow("catalog")
+            if col and name:
+                ctx.nn_checks[(t, name)] = col
+        else:
+            st.slow("scan")
+            if col:
+                ctx.nn_ok.add((t, col))
+            if not new:
+                name = name or ident(tname, col or "", suffix="check")
+                st.find("add-check", "high", f"Adding the CHECK constraint scans all of {t} under ACCESS EXCLUSIVE: reads and writes wait.",
+                        f"ALTER TABLE {t} ADD CONSTRAINT {name} CHECK ({sql(con.raw_expr)}) NOT VALID;  -- instant\n"
+                        f"ALTER TABLE {t} VALIDATE CONSTRAINT {name};  -- SHARE UPDATE EXCLUSIVE: reads and writes continue")
+    elif k == CT.CONSTR_NOTNULL:
+        need(st, ctx, 18, "ADD CONSTRAINT ... NOT NULL")
+        cols = [s.sval for s in con.keys or ()]
+        if con.skip_validation:
+            st.slow("catalog")
+            if name and cols:
+                ctx.nn_checks[(t, name)] = cols[0]
+        else:
+            st.slow("scan")
+            if not new:
+                st.find("add-not-null-constraint", "high", f"Adding the NOT NULL constraint scans all of {t} under ACCESS EXCLUSIVE.",
+                        not_null_fix(t, qi(cols[0]) if cols else "?", ctx.pg))
+    elif k in (CT.CONSTR_PRIMARY, CT.CONSTR_UNIQUE):
+        what = "PRIMARY KEY" if k == CT.CONSTR_PRIMARY else "UNIQUE"
+        if con.nulls_not_distinct:
+            need(st, ctx, 15, "UNIQUE NULLS NOT DISTINCT")
+        if con.indexname:
+            st.slow("catalog" if k == CT.CONSTR_UNIQUE else "scan")
+            if k == CT.CONSTR_PRIMARY and not new:
+                st.find("add-unique", "low", f"PRIMARY KEY USING INDEX is instant only if the key columns are already NOT NULL; "
+                        f"otherwise it scans {t} under ACCESS EXCLUSIVE to set NOT NULL.", "-- make each key column NOT NULL first:\n"
+                        + not_null_fix(t, "<column>", ctx.pg))
+            return
+        st.slow("index")
+        if not new:
+            cols = [qi(s.sval) for s in con.keys or ()]
+            idx = qi(name) if name else ident(tname, *(s.sval for s in con.keys or ()), suffix="pkey" if k == CT.CONSTR_PRIMARY else "key")
+            index_extra = ''
+            if con.including:
+                index_extra += ' INCLUDE (' + ', '.join(qi(c.sval) for c in con.including) + ')'
+            index_extra += ' NULLS NOT DISTINCT' if con.nulls_not_distinct else ''
+            constraint_extra = (' DEFERRABLE' if con.deferrable else '') + (' INITIALLY DEFERRED' if con.initdeferred else '')
+            st.find("add-unique", "high", f"Adding the {what} builds a unique index on {t} while holding ACCESS EXCLUSIVE: reads and writes wait for the build.",
+                    f"CREATE UNIQUE INDEX CONCURRENTLY {idx} ON {t} ({', '.join(cols)}){index_extra};  -- outside a transaction; reads and writes continue\n"
+                    f"ALTER TABLE {t} ADD CONSTRAINT {idx} {what} USING INDEX {idx}{constraint_extra};  -- normally brief"
+                    + ("\n-- the key columns must already be NOT NULL, or this step scans the table" if k == CT.CONSTR_PRIMARY else ""))
+    elif k == CT.CONSTR_EXCLUSION:
+        st.slow("index")
+        if not new:
+            st.find("add-exclusion", "high", f"Adding the EXCLUDE constraint builds an index on {t} under ACCESS EXCLUSIVE; "
+                    "there is no CONCURRENTLY form for exclusion constraints.",
+                    "-- run it when the table is quiet, with lock_timeout set; or enforce the rule in the application first.")
+    else:
+        st.slow("catalog")
+
+
+REL_OPTS_SUE = re.compile(r"^(fillfactor|autovacuum_.*|toast\..*|toast_tuple_target|parallel_workers|vacuum_.*|"
+                          r"log_autovacuum_min_duration|user_catalog_table|n_distinct.*)$")
+TRIGGER_CMDS = {AT.AT_EnableTrig, AT.AT_EnableAlwaysTrig, AT.AT_EnableReplicaTrig, AT.AT_DisableTrig, AT.AT_EnableTrigAll,
+                AT.AT_DisableTrigAll, AT.AT_EnableTrigUser, AT.AT_DisableTrigUser}
+SUE_CMDS = {AT.AT_SetStatistics, AT.AT_SetOptions, AT.AT_ResetOptions, AT.AT_ClusterOn, AT.AT_DropCluster,
+            AT.AT_ValidateConstraint, AT.AT_DetachPartitionFinalize}
+
+
+def h_AlterTableStmt(s, ctx, st):
+    t = rv(s.relation)
+    tname = s.relation.relname
+    new = ctx.new(t)
+    kind = {OT.OBJECT_INDEX: "ALTER INDEX", OT.OBJECT_MATVIEW: "ALTER MATERIALIZED VIEW", OT.OBJECT_VIEW: "ALTER VIEW",
+            OT.OBJECT_SEQUENCE: "ALTER SEQUENCE", OT.OBJECT_FOREIGN_TABLE: "ALTER FOREIGN TABLE"}.get(s.objtype, "ALTER TABLE")
+    subs = []
+    for cmd in s.cmds:
+        sub = cmd.subtype
+        subs.append(AT.Name(sub)[3:])
+        before = len(st.locks)
+        if sub == AT.AT_AddColumn:
+            st.lock(t, AE, new)
+            add_column(st, ctx, t, cmd.def_)
+        elif sub == AT.AT_AlterColumnType:
+            st.lock(t, AE, new)
+            alter_type(st, ctx, t, cmd)
+        elif sub == AT.AT_SetNotNull:
+            st.lock(t, AE, new)
+            col = cmd.name
+            if new or (ctx.pg >= 12 and (t, col) in ctx.nn_ok):
+                st.slow("catalog")
+            else:
+                st.slow("scan")
+                st.find("set-not-null", "high", f"SET NOT NULL scans all of {t} under ACCESS EXCLUSIVE to check {qi(col)}: "
+                        "reads and writes wait for the scan.", not_null_fix(t, qi(col), ctx.pg))
+        elif sub == AT.AT_AddConstraint:
+            add_constraint(st, ctx, t, cmd.def_, tname)
+        elif sub == AT.AT_ValidateConstraint:
+            st.lock(t, SUE, new)
+            st.slow("scan")
+            ref = ctx.cons.get((t, cmd.name))
+            if ref:
+                st.lock(ref, RS, ctx.new(ref))
+            col = ctx.nn_checks.get((t, cmd.name))
+            if col:
+                ctx.nn_ok.add((t, col))
+        elif sub == AT.AT_DropColumn:
+            st.lock(t, AE, new)
+            st.slow("catalog")
+            if not new:
+                st.find("drop-column", "medium", f"Dropping {qi(cmd.name)} is instant but irreversible, and every running query or "
+                        "ORM model that still selects or inserts it fails afterwards.",
+                        "-- 1. stop using the column in the application and deploy (Rails: self.ignored_columns; Django:\n"
+                        "--    SeparateDatabaseAndState), 2. then drop it with lock_timeout set:\n"
+                        f"SET lock_timeout = '5s';\nALTER TABLE {t} DROP COLUMN {qi(cmd.name)};")
+        elif sub in (AT.AT_SetLogged, AT.AT_SetUnLogged, AT.AT_SetTableSpace, AT.AT_SetAccessMethod, AT.AT_SetExpression):
+            st.lock(t, AE, new)
+            if sub == AT.AT_SetAccessMethod:
+                need(st, ctx, 15, "ALTER TABLE ... SET ACCESS METHOD")
+            if sub == AT.AT_SetExpression:
+                need(st, ctx, 17, "ALTER COLUMN ... SET EXPRESSION")
+            st.slow("rewrite")
+            if not new:
+                st.find("table-rewrite", "high", f"{AT.Name(sub)[3:]} rewrites (copies) all of {t} under ACCESS EXCLUSIVE: reads and writes wait.", REPACK)
+        elif sub in (AT.AT_SetRelOptions, AT.AT_ResetRelOptions):
+            names = [d.defname if not d.defnamespace else f"{d.defnamespace}.{d.defname}" for d in (cmd.def_.items if isinstance(cmd.def_, ast.List) else cmd.def_ or ())]
+            st.lock(t, SUE if names and all(REL_OPTS_SUE.match(n) for n in names) else AE, new)
+            st.slow("catalog")
+        elif sub in SUE_CMDS:
+            st.lock(t, SUE, new)
+            st.slow("catalog")
+        elif sub in TRIGGER_CMDS or sub == AT.AT_AlterConstraint:
+            st.lock(t, SRE, new)
+            st.slow("catalog")
+        elif sub == AT.AT_AttachPartition:
+            part = rv(cmd.def_.name)
+            if s.objtype == OT.OBJECT_INDEX:
+                st.lock(t, SUE, new)
+                st.lock(part, SUE, ctx.new(part))
+                st.slow("catalog")
+                continue
+            st.lock(t, SUE if ctx.pg >= 12 else AE, new)
+            st.lock(part, AE, ctx.new(part))
+            st.slow("scan")
+            if not ctx.new(part):
+                bound = sql(cmd.def_.bound) if cmd.def_.bound is not None else "DEFAULT"
+                st.find("attach-partition", "high" if ctx.pg < 12 else "medium",
+                        f"ATTACH PARTITION scans {part} under ACCESS EXCLUSIVE to prove every row fits the bound"
+                        + (f", and takes ACCESS EXCLUSIVE on the parent {t} before PostgreSQL 12." if ctx.pg < 12 else
+                           f" (the parent {t} only gets SHARE UPDATE EXCLUSIVE on PostgreSQL 12+).")
+                        + " A DEFAULT partition, if any, is scanned too.",
+                        f"-- a validated CHECK that matches the bound lets ATTACH skip the scan:\n"
+                        f"ALTER TABLE {part} ADD CONSTRAINT {ident(cmd.def_.name.relname, suffix='bound')} CHECK (<partition key condition for {bound}>) NOT VALID;\n"
+                        f"ALTER TABLE {part} VALIDATE CONSTRAINT {ident(cmd.def_.name.relname, suffix='bound')};  -- reads and writes continue\n"
+                        f"ALTER TABLE {t} ATTACH PARTITION {part} {bound};\n"
+                        f"ALTER TABLE {part} DROP CONSTRAINT {ident(cmd.def_.name.relname, suffix='bound')};")
+        elif sub == AT.AT_DetachPartition:
+            part = rv(cmd.def_.name)
+            if cmd.def_.concurrent:
+                need(st, ctx, 14, "DETACH PARTITION ... CONCURRENTLY")
+                st.lock(t, SUE, new)
+                st.lock(part, SUE, ctx.new(part))
+                st.notx = "DETACH PARTITION ... CONCURRENTLY"
+                st.slow("catalog")
+            else:
+                st.lock(t, AE, new)
+                st.lock(part, AE, ctx.new(part))
+                st.slow("catalog")
+                if not new:
+                    st.find("detach-partition", "medium", f"DETACH PARTITION takes ACCESS EXCLUSIVE on {t}: every query on the "
+                            "partitioned table waits for it, and it waits for every running one.",
+                            f"ALTER TABLE {t} DETACH PARTITION {part} CONCURRENTLY;  -- PostgreSQL 14+, outside a transaction"
+                            if ctx.pg >= 14 else "-- PostgreSQL 14+ has DETACH PARTITION ... CONCURRENTLY; on older versions set lock_timeout and retry.")
+        elif sub == AT.AT_AddIdentity:
+            st.lock(t, AE, new)
+            st.slow("catalog")
+        else:  # defaults, DROP NOT NULL, storage, compression, owner, RLS, rules, inherit, replica identity...: ACCESS EXCLUSIVE, catalog only
+            st.lock(t, AE, new)
+            st.slow("catalog")
+        if len(st.locks) == before:
+            st.lock(t, AE, new)
+    st.kind = kind + " " + ", ".join(dict.fromkeys(x.replace("_", " ") for x in subs))
+
+
+def h_IndexStmt(s, ctx, st):
+    t = rv(s.relation)
+    new = ctx.new(t)
+    st.kind = "CREATE " + ("UNIQUE " if s.unique else "") + "INDEX" + (" CONCURRENTLY" if s.concurrent else "")
+    st.slow("index")
+    if s.nulls_not_distinct:
+        need(st, ctx, 15, "NULLS NOT DISTINCT")
+    if s.concurrent:
+        st.lock(t, SUE, new)
+        st.notx = "CREATE INDEX CONCURRENTLY"
+        if ctx.tables.get(t, {}).get("partkey"):
+            st.find("version", "high", f"{t} is partitioned: CREATE INDEX CONCURRENTLY is not supported on partitioned tables.",
+                    f"-- create the index on each partition CONCURRENTLY, then CREATE INDEX ON ONLY {t} and ALTER INDEX ... ATTACH PARTITION each one.")
+        return
+    st.lock(t, SH, new)
+    if not new:
+        s._pb.concurrent = True
+        fix = sql(s) + ";  -- outside a transaction; reads and writes continue\n"
+        s._pb.concurrent = False
+        fix += "-- if it fails it leaves an INVALID index: DROP INDEX CONCURRENTLY it and retry."
+        st.find("create-index", "high", f"CREATE INDEX holds SHARE on {t} for the whole build: INSERT, UPDATE and DELETE wait until it finishes.", fix)
+
+
+def drop_targets(s):
+    return [dotted(o.items) if isinstance(o, ast.List) else (dotted(o) if isinstance(o, (tuple, list)) else (dotted([o]) if isinstance(o, ast.String) else dotted(getattr(o, 'objname', ())) or type(o).__name__)) for o in s.objects or ()]
+
+
+def h_DropStmt(s, ctx, st):
+    rt = s.remove_type
+    objs = drop_targets(s)
+    st.kind = "DROP " + OT.Name(rt)[7:].replace("_", " ") + (" CONCURRENTLY" if s.concurrent else "")
+    if rt in (OT.OBJECT_TABLE, OT.OBJECT_MATVIEW, OT.OBJECT_VIEW, OT.OBJECT_FOREIGN_TABLE, OT.OBJECT_SEQUENCE):
+        st.slow("catalog")
+        for o in objs:
+            st.lock(o, AE, ctx.new(o))
+            if rt == OT.OBJECT_TABLE and not ctx.new(o):
+                st.find("drop-table", "medium", f"DROP TABLE {o} deletes its data irreversibly, and takes ACCESS EXCLUSIVE on it "
+                        "(and briefly on tables that reference it with foreign keys).",
+                        "-- remove every use of the table from the application and deploy first; take a backup (pg_dump -t) if in doubt.")
+            ctx.tables.pop(o, None)
+    elif rt == OT.OBJECT_INDEX:
+        st.slow("catalog")
+        for o in objs:
+            if s.concurrent:
+                st.lock(f"table of index {o}", SUE)
+                st.notx = "DROP INDEX CONCURRENTLY"
+            else:
+                st.lock(f"table of index {o}", AE)
+        if not s.concurrent:
+            st.find("drop-index", "medium", "DROP INDEX takes ACCESS EXCLUSIVE on the index's table: it waits for every running query "
+                    "on that table, and every new query waits behind it.",
+                    "\n".join(f"DROP INDEX CONCURRENTLY {'IF EXISTS ' if s.missing_ok else ''}{o};" for o in objs)
+                    + "  -- outside a transaction, one index per statement")
+        elif len(objs) > 1:
+            st.find("version", "high", "DROP INDEX CONCURRENTLY drops one index per statement; this statement fails.",
+                    "\n".join(f"DROP INDEX CONCURRENTLY {o};" for o in objs))
+    elif rt in (OT.OBJECT_TRIGGER, OT.OBJECT_POLICY, OT.OBJECT_RULE):
+        st.slow("catalog")
+        for o in s.objects or ():
+            parts = [x.sval for x in (o.items if isinstance(o, ast.List) else o)]
+            tbl = ".".join(qi(p) for p in parts[:-1] if p != "public")
+            st.lock(tbl, AE, ctx.new(tbl))
+    elif rt in (OT.OBJECT_SCHEMA, OT.OBJECT_DATABASE):
+        st.slow("catalog")
+        if rt == OT.OBJECT_DATABASE:
+            st.notx = "DROP DATABASE"
+        st.find("drop-table", "medium", f"DROP {OT.Name(rt)[7:]} {', '.join(objs)} deletes everything in it irreversibly"
+                + (" (CASCADE)." if s.behavior == pb.DROP_CASCADE else "."))
+    else:
+        st.slow("catalog")
+
+
+def h_TruncateStmt(s, ctx, st):
+    st.kind = "TRUNCATE"
+    st.slow("catalog")
+    for r in s.relations:
+        t = rv(r)
+        st.lock(t, AE, ctx.new(t))
+        if not ctx.new(t):
+            st.find("drop-table", "medium", f"TRUNCATE deletes every row of {t} irreversibly and takes ACCESS EXCLUSIVE on it.")
+
+
+def h_CreateStmt(s, ctx, st):
+    t = rv(s.relation)
+    st.kind = "CREATE TABLE" + (" PARTITION OF" if s.partbound is not None else "")
+    cols = {}
+    for e in s.table_elts or ():
+        if isinstance(e, ast.ColumnDef):
+            cols[e.colname] = type_name(e.type_name)
+            for k in e.constraints or ():
+                if k.contype == CT.CONSTR_FOREIGN:
+                    ref = rv(k.pktable)
+                    st.lock(ref, SRE, ctx.new(ref) or ref == t)
+        elif isinstance(e, ast.Constraint) and e.contype == CT.CONSTR_FOREIGN:
+            ref = rv(e.pktable)
+            st.lock(ref, SRE, ctx.new(ref) or ref == t)
+    existed = ctx.new(t)
+    partkey = [p.name for p in s.partspec.part_params if p.name] if s.partspec is not None else None
+    if not existed or not s.if_not_exists:
+        ctx.tables[t] = {"cols": cols, "partkey": partkey}
+    st.lock(t, AE, True)
+    st.slow("catalog")
+    if s.partbound is not None:
+        parent = rv(s.inh_relations[0])
+        st.lock(parent, AE, ctx.new(parent))
+        if not ctx.new(parent):
+            st.find("partition-of", "medium", f"CREATE TABLE ... PARTITION OF takes ACCESS EXCLUSIVE on {parent}: every query on it waits, "
+                    "and it waits for every running query.",
+                    f"CREATE TABLE {t} (LIKE {parent} INCLUDING DEFAULTS INCLUDING CONSTRAINTS);\n"
+                    f"-- add a CHECK matching the bound (NOT VALID, then VALIDATE) so ATTACH does not scan, then:\n"
+                    f"ALTER TABLE {parent} ATTACH PARTITION {t} {sql(s.partbound)};  -- SHARE UPDATE EXCLUSIVE on the parent (PostgreSQL 12+)"
+                    if ctx.pg >= 12 else "-- before PostgreSQL 12 ATTACH PARTITION also takes ACCESS EXCLUSIVE on the parent; set lock_timeout and retry.")
+
+
+def h_CreateTableAsStmt(s, ctx, st):
+    t = rv(s.into.rel)
+    st.kind = "CREATE MATERIALIZED VIEW" if s.objtype == OT.OBJECT_MATVIEW else "CREATE TABLE AS"
+    ctx.tables[t] = {"cols": {}, "partkey": None}
+    st.lock(t, AE, True)
+    st.slow("rows")
+    reads(s.query, ctx, st)
+
+
+def reads(query, ctx, st, mode=AS):
+    for n in walk(query):
+        if isinstance(n, ast.RangeVar):
+            t = rv(n)
+            if not any(l["target"] == t for l in st.locks):
+                st.lock(t, mode, ctx.new(t))
+
+
+def h_RefreshMatViewStmt(s, ctx, st):
+    t = rv(s.relation)
+    st.kind = "REFRESH MATERIALIZED VIEW" + (" CONCURRENTLY" if s.concurrent else "")
+    st.slow("rewrite")
+    if s.concurrent:
+        st.lock(t, EX, ctx.new(t))
+        return
+    st.lock(t, AE, ctx.new(t))
+    if not ctx.new(t):
+        st.find("refresh-matview", "high", f"REFRESH MATERIALIZED VIEW holds ACCESS EXCLUSIVE on {t} while the query reruns: reads of the view wait.",
+                f"REFRESH MATERIALIZED VIEW CONCURRENTLY {t};  -- EXCLUSIVE: reads continue; needs a UNIQUE index on the view")
+
+
+def h_ViewStmt(s, ctx, st):
+    t = rv(s.view)
+    st.kind = "CREATE OR REPLACE VIEW" if s.replace else "CREATE VIEW"
+    st.lock(t, AE, not s.replace or ctx.new(t))
+    st.slow("catalog")
+    reads(s.query, ctx, st)
+
+
+def h_RenameStmt(s, ctx, st):
+    rt = s.rename_type
+    st.kind = f"RENAME {OT.Name(rt)[7:].replace('_', ' ')}"
+    st.slow("catalog")
+    if s.relation is None:
+        return
+    t = rv(s.relation)
+    new = ctx.new(t)
+    if rt == OT.OBJECT_INDEX or (rt == OT.OBJECT_TABLE and s.relation_type == OT.OBJECT_INDEX):
+        st.lock(t, SUE if ctx.pg >= 12 else AE, new)
+        return
+    st.lock(t, AE, new)
+    if rt == OT.OBJECT_COLUMN:
+        if new:
+            ctx.tables[t]["cols"][s.newname] = ctx.tables[t]["cols"].pop(s.subname, "?")
+        else:
+            st.find("rename", "medium", f"Renaming {t}.{qi(s.subname)} to {qi(s.newname)} breaks every query of the running application "
+                    "that still uses the old name, from the moment it commits until the new code is deployed.",
+                    f"-- expand/contract: ADD COLUMN {qi(s.newname)}, keep both in sync with a trigger, backfill, switch the code to\n"
+                    f"-- the new column, then drop {qi(s.subname)}. Or deploy code that tolerates both names before renaming.")
+    elif rt in (OT.OBJECT_TABLE, OT.OBJECT_VIEW, OT.OBJECT_MATVIEW, OT.OBJECT_FOREIGN_TABLE):
+        newt = ".".join(t.split(".")[:-1] + [qi(s.newname)])
+        if new:
+            ctx.tables[newt] = ctx.tables.pop(t)
+        elif rt == OT.OBJECT_TABLE:
+            st.find("rename", "medium", f"Renaming {t} to {qi(s.newname)} breaks every query of the running application that still uses the old name.",
+                    f"ALTER TABLE {t} RENAME TO {qi(s.newname)};\n"
+                    f"CREATE VIEW {t} AS SELECT * FROM {newt};  -- same transaction: old name keeps working (simple views are updatable)\n"
+                    f"-- drop the view once every client uses {qi(s.newname)}")
+
+
+def h_AlterObjectSchemaStmt(s, ctx, st):
+    st.kind = f"ALTER {OT.Name(s.object_type)[7:]} SET SCHEMA"
+    st.slow("catalog")
+    if s.relation is not None:
+        t = rv(s.relation)
+        st.lock(t, AE, ctx.new(t))
+        if not ctx.new(t) and s.object_type == OT.OBJECT_TABLE:
+            st.find("rename", "medium", f"Moving {t} to schema {qi(s.newschema)} breaks queries that use the old qualified name or rely on search_path.")
+
+
+def h_CreateTrigStmt(s, ctx, st):
+    t = rv(s.relation)
+    st.kind = "CREATE OR REPLACE TRIGGER" if s.replace else ("CREATE CONSTRAINT TRIGGER" if s.isconstraint else "CREATE TRIGGER")
+    if s.replace:
+        need(st, ctx, 14, "CREATE OR REPLACE TRIGGER")
+    st.lock(t, SRE, ctx.new(t))
+    st.slow("catalog")
+
+
+def h_CreatePolicyStmt(s, ctx, st, kind="CREATE POLICY"):
+    t = rv(s.table)
+    st.kind = kind
+    st.lock(t, AE, ctx.new(t))
+    st.slow("catalog")
+
+
+def h_AlterPolicyStmt(s, ctx, st):
+    h_CreatePolicyStmt(s, ctx, st, "ALTER POLICY")
+
+
+def h_RuleStmt(s, ctx, st):
+    t = rv(s.relation)
+    st.kind = "CREATE RULE"
+    st.lock(t, AE, ctx.new(t))
+    st.slow("catalog")
+
+
+COMMENT_REL = {OT.OBJECT_TABLE, OT.OBJECT_COLUMN, OT.OBJECT_INDEX, OT.OBJECT_VIEW, OT.OBJECT_MATVIEW, OT.OBJECT_SEQUENCE,
+               OT.OBJECT_FOREIGN_TABLE, OT.OBJECT_TABCONSTRAINT, OT.OBJECT_TRIGGER, OT.OBJECT_POLICY, OT.OBJECT_RULE}
+
+
+def h_CommentStmt(s, ctx, st):
+    st.kind = f"COMMENT ON {OT.Name(s.objtype)[7:].replace('_', ' ')}"
+    st.slow("catalog")
+    if s.objtype in COMMENT_REL and isinstance(s.object, (tuple, list, ast.List)):
+        parts = [x.sval for x in (s.object.items if isinstance(s.object, ast.List) else s.object) if isinstance(x, ast.String)]
+        if s.objtype in (OT.OBJECT_COLUMN, OT.OBJECT_TABCONSTRAINT, OT.OBJECT_TRIGGER, OT.OBJECT_POLICY, OT.OBJECT_RULE):
+            parts = parts[:-1]
+        t = ".".join(qi(p) for p in parts)
+        st.lock(t, SUE, ctx.new(t))
+
+
+def h_CreateStatsStmt(s, ctx, st):
+    st.kind = "CREATE STATISTICS"
+    st.slow("catalog")
+    for r in s.relations or ():
+        if isinstance(r, ast.RangeVar):
+            st.lock(rv(r), SUE, ctx.new(rv(r)))
+
+
+def h_VacuumStmt(s, ctx, st):
+    opts = {d.defname.lower() for d in s.options or ()}
+    full = "full" in opts and s.is_vacuumcmd
+    st.kind = ("VACUUM FULL" if full else "VACUUM") if s.is_vacuumcmd else "ANALYZE"
+    if s.is_vacuumcmd:
+        st.notx = st.kind
+    rels = [rv(v.relation) for v in s.rels or ()] or ["every table in the database"]
+    for t in rels:
+        st.lock(t, AE if full else SUE, ctx.new(t))
+    st.slow("rewrite" if full else "scan")
+    if full and not all(ctx.new(t) for t in rels):
+        st.find("table-rewrite", "high", f"VACUUM FULL rewrites {', '.join(rels)} under ACCESS EXCLUSIVE: reads and writes wait.", REPACK)
+
+
+def h_ClusterStmt(s, ctx, st):
+    st.kind = "CLUSTER"
+    t = rv(s.relation) if s.relation is not None else "every clustered table"
+    if s.relation is None:
+        st.notx = "CLUSTER without a table"
+    st.lock(t, AE, ctx.new(t))
+    st.slow("rewrite")
+    if not ctx.new(t):
+        st.find("table-rewrite", "high", f"CLUSTER rewrites {t} in index order under ACCESS EXCLUSIVE: reads and writes wait.", REPACK)
+
+
+def h_ReindexStmt(s, ctx, st):
+    conc = any(d.defname.lower() == "concurrently" for d in s.params or ())
+    what = {RO.REINDEX_OBJECT_INDEX: "INDEX", RO.REINDEX_OBJECT_TABLE: "TABLE", RO.REINDEX_OBJECT_SCHEMA: "SCHEMA",
+            RO.REINDEX_OBJECT_SYSTEM: "SYSTEM", RO.REINDEX_OBJECT_DATABASE: "DATABASE"}[s.kind]
+    st.kind = f"REINDEX {what}" + (" CONCURRENTLY" if conc else "")
+    name = rv(s.relation) if s.relation is not None else (s.name or "current database")
+    target = f"table of index {name}" if what == "INDEX" else name
+    st.slow("index")
+    if what in ("SCHEMA", "SYSTEM", "DATABASE"):
+        st.notx = st.kind
+    if conc:
+        need(st, ctx, 12, "REINDEX CONCURRENTLY")
+        st.notx = st.kind
+        st.lock(target, SUE)
+        return
+    st.lock(target, SH)
+    st.lock(name if what == "INDEX" else f"indexes of {name}", AE)
+    st.find("reindex", "high", f"REINDEX {what} {name} blocks writes to the table and takes ACCESS EXCLUSIVE on the index"
+            f"{'es' if what != 'INDEX' else ''}, so queries that would use it wait too, for the whole rebuild.",
+            f"REINDEX {what} CONCURRENTLY {name};  -- PostgreSQL 12+, outside a transaction" if ctx.pg >= 12 else
+            "-- before PostgreSQL 12: CREATE INDEX CONCURRENTLY a copy, DROP INDEX CONCURRENTLY the old one, ALTER INDEX ... RENAME.")
+
+
+def h_LockStmt(s, ctx, st):
+    mode = MODES[s.mode - 1]
+    st.kind = f"LOCK TABLE IN {mode} MODE"
+    st.slow("catalog")
+    for r in s.relations:
+        st.lock(rv(r), mode, ctx.new(rv(r)))
+
+
+def h_AlterEnumStmt(s, ctx, st):
+    st.kind = "ALTER TYPE ADD VALUE" if s.new_val and not s.old_val else "ALTER TYPE RENAME VALUE"
+    st.slow("catalog")
+    if not s.old_val and s.new_val:
+        st.enum_add = True
+
+
+def h_AlterDomainStmt(s, ctx, st):
+    st.kind = "ALTER DOMAIN"
+    st.slow("catalog")
+    d = dotted(s.type_name)
+    if s.subtype == "C" and isinstance(s.def_, ast.Constraint) and not s.def_.skip_validation:
+        st.slow("scan")
+        name = s.def_.conname or ident(d.split(".")[-1], suffix="check")
+        con = sql(s.def_) if s.def_.conname else f"CONSTRAINT {name} {sql(s.def_)}"
+        st.find("domain-constraint", "high", f"Adding a constraint to domain {d} scans every table column that uses it, "
+                "locking those tables against writes.",
+                f"ALTER DOMAIN {d} ADD {con} NOT VALID;  -- instant; new values are checked\n"
+                f"ALTER DOMAIN {d} VALIDATE CONSTRAINT {name};")
+    elif s.subtype in ("O", "V"):
+        st.slow("scan")
+
+
+def h_dml(s, ctx, st, kind):
+    t = rv(s.relation)
+    st.kind = kind
+    st.lock(t, RE, ctx.new(t))
+    st.slow("rows")
+    for part in (getattr(s, "fromClause", None), getattr(s, "usingClause", None), getattr(s, "selectStmt", None),
+                 getattr(s, "whereClause", None), getattr(s, "sourceRelation", None)):
+        if part is not None:
+            reads(part, ctx, st)
+    if kind in ("UPDATE", "DELETE") and s.where_clause is None and not ctx.new(t):
+        verb = "updates" if kind == "UPDATE" else "deletes"
+        st.find("update-all-rows", "medium", f"{kind} without WHERE {verb} every row of {t} in one transaction: it row-locks them all "
+                "(blocking concurrent writes to them), generates WAL and dead tuples for the whole table.",
+                f"-- batch it; each batch in its own short transaction, repeat until 0 rows:\n"
+                + (f"UPDATE {t} SET ... WHERE ctid IN (SELECT ctid FROM {t} WHERE <not yet updated> LIMIT 5000);" if kind == "UPDATE"
+                   else f"DELETE FROM {t} WHERE ctid IN (SELECT ctid FROM {t} LIMIT 5000);"))
+
+
+def h_InsertStmt(s, ctx, st):
+    h_dml(s, ctx, st, "INSERT")
+
+
+def h_UpdateStmt(s, ctx, st):
+    h_dml(s, ctx, st, "UPDATE")
+
+
+def h_DeleteStmt(s, ctx, st):
+    h_dml(s, ctx, st, "DELETE")
+
+
+def h_MergeStmt(s, ctx, st):
+    need(st, ctx, 15, "MERGE")
+    h_dml(s, ctx, st, "MERGE")
+
+
+def h_CopyStmt(s, ctx, st):
+    st.kind = "COPY FROM" if s.is_from else "COPY TO"
+    st.slow("rows")
+    if s.relation is not None:
+        t = rv(s.relation)
+        st.lock(t, RE if s.is_from else AS, ctx.new(t))
+
+
+def h_SelectStmt(s, ctx, st):
+    st.kind = "SELECT"
+    st.slow("rows")
+    mode = RS if s.locking_clause else AS
+    reads(s, ctx, st, mode)
+
+
+def h_DoStmt(s, ctx, st):
+    st.kind = "DO block"
+    st.find("not-analysed", "medium", "The body of a DO block is not analysed: check its statements by hand.")
+
+
+NO_TABLE = {  # statements that change catalogs only and lock no user table
+    "CreateFunctionStmt": "CREATE FUNCTION", "CreateSeqStmt": "CREATE SEQUENCE", "AlterSeqStmt": "ALTER SEQUENCE",
+    "CreateEnumStmt": "CREATE TYPE (enum)", "CompositeTypeStmt": "CREATE TYPE", "CreateDomainStmt": "CREATE DOMAIN",
+    "CreateSchemaStmt": "CREATE SCHEMA", "CreateExtensionStmt": "CREATE EXTENSION", "AlterExtensionStmt": "ALTER EXTENSION",
+    "GrantStmt": "GRANT/REVOKE", "GrantRoleStmt": "GRANT role", "CreateRoleStmt": "CREATE ROLE", "AlterRoleStmt": "ALTER ROLE",
+    "AlterRoleSetStmt": "ALTER ROLE SET", "DropRoleStmt": "DROP ROLE", "AlterOwnerStmt": "ALTER OWNER", "DefineStmt": "CREATE (definition)",
+    "AlterFunctionStmt": "ALTER FUNCTION", "CreateRangeStmt": "CREATE TYPE (range)", "AlterDefaultPrivilegesStmt": "ALTER DEFAULT PRIVILEGES",
+    "CreatedbStmt": "CREATE DATABASE", "DropdbStmt": "DROP DATABASE", "AlterSystemStmt": "ALTER SYSTEM", "CreateCastStmt": "CREATE CAST",
+    "CreateOpClassStmt": "CREATE OPERATOR CLASS", "CreatePublicationStmt": "CREATE PUBLICATION", "AlterPublicationStmt": "ALTER PUBLICATION",
+    "CreateSubscriptionStmt": "CREATE SUBSCRIPTION", "CreateEventTrigStmt": "CREATE EVENT TRIGGER", "CreateConversionStmt": "CREATE CONVERSION",
+    "CreateTableSpaceStmt": "CREATE TABLESPACE", "DropTableSpaceStmt": "DROP TABLESPACE", "CreateForeignServerStmt": "CREATE SERVER",
+    "CreateFdwStmt": "CREATE FOREIGN DATA WRAPPER", "CreateUserMappingStmt": "CREATE USER MAPPING", "ImportForeignSchemaStmt": "IMPORT FOREIGN SCHEMA",
+    "AlterCollationStmt": "ALTER COLLATION", "AlterTSConfigurationStmt": "ALTER TEXT SEARCH CONFIGURATION", "CreatePLangStmt": "CREATE LANGUAGE",
+    "AlterEventTrigStmt": "ALTER EVENT TRIGGER", "NotifyStmt": "NOTIFY", "ListenStmt": "LISTEN", "DiscardStmt": "DISCARD",
+    "CheckPointStmt": "CHECKPOINT", "ExplainStmt": "EXPLAIN", "DeallocateStmt": "DEALLOCATE", "PrepareStmt": "PREPARE",
+    "CreateTransformStmt": "CREATE TRANSFORM", "CreateAmStmt": "CREATE ACCESS METHOD", "AlterTypeStmt": "ALTER TYPE", "AlterOpFamilyStmt": "ALTER OPERATOR FAMILY",
+    "CreateOpFamilyStmt": "CREATE OPERATOR FAMILY", "ReassignOwnedStmt": "REASSIGN OWNED", "DropOwnedStmt": "DROP OWNED",
+    "SecLabelStmt": "SECURITY LABEL", "AlterDatabaseSetStmt": "ALTER DATABASE SET", "AlterDatabaseStmt": "ALTER DATABASE",
+}
+NOTX_TYPES = {"CreatedbStmt": "CREATE DATABASE", "DropdbStmt": "DROP DATABASE", "AlterSystemStmt": "ALTER SYSTEM",
+              "CreateTableSpaceStmt": "CREATE TABLESPACE", "DropTableSpaceStmt": "DROP TABLESPACE",
+              "CreateSubscriptionStmt": "CREATE SUBSCRIPTION"}
+HANDLERS = {k[2:]: v for k, v in globals().items() if k.startswith("h_") and k != "h_dml"}
+
+
+def analyse(stmt, ctx):
+    name = type(stmt).__name__
+    st = St(NO_TABLE.get(name, name.removesuffix("Stmt")))
+    if name in HANDLERS:
+        HANDLERS[name](stmt, ctx, st)
+    elif name in NO_TABLE:
+        st.notx = NOTX_TYPES.get(name, "")
+        if name not in ('CreateFunctionStmt', 'CreateEnumStmt', 'CreateSeqStmt', 'CreateRoleStmt',
+                        'GrantRoleStmt', 'AlterRoleStmt', 'AlterRoleSetStmt', 'NotifyStmt', 'ListenStmt',
+                        'CreateDomainStmt', 'AlterDefaultPrivilegesStmt', 'CreateEventTrigStmt'):
+            st.find("not-analysed", "medium", "This operation can reach schema objects or execute nested SQL; its table locks are not modelled.")
+        if name == "CreateSubscriptionStmt":
+            st.notx = "" if any(d.defname == "create_slot" and sql(d.arg) in ("false", "'false'") for d in stmt.options or ()) else st.notx
+    else:
+        st.find("not-analysed", "medium", f"{st.kind} statements are not modelled; check its locks in the PostgreSQL docs.")
+    return st
+
+
+# ---------- the run over files ----------
+def timeout_value(args):
+    if not args:
+        return None
+    v = args[0]
+    v = getattr(v, "val", v)
+    raw = str(getattr(v, "sval", None) or getattr(v, "ival", "")).strip().lower()
+    return None if re.fullmatch(r"0+(\.0*)?\s*(us|ms|s|min|h|d)?", raw or "0") else raw
+
+
+def set_config(stmt):
+    """SELECT set_config('lock_timeout', '5s', is_local) -> (name, value, local)."""
+    if type(stmt).__name__ != "SelectStmt" or not stmt.target_list or len(stmt.target_list) != 1:
+        return None
+    f = stmt.target_list[0].val
+    if not isinstance(f, ast.FuncCall) or f.funcname[-1].sval != "set_config" or len(f.args or ()) != 3:
+        return None
+    try:
+        name, val, loc = (a.val for a in f.args)
+        return name.sval.lower(), timeout_value([val]), bool(getattr(loc, "boolval", False))
+    except AttributeError:
+        return None
+
+
+class Lines:
+    def __init__(self, text):
+        self.starts = [0] + [m.end() for m in re.finditer("\n", text)]
+
+    def at(self, off):
+        i = bisect_right(self.starts, off) - 1
+        return i + 1, off - self.starts[i] + 1
+
+
+def check(files, pg=PG_DEFAULT, txn_mode="auto", assume_timeouts=False, max_statements=None):
+    """files: [(name, text)] in the order they run. Returns the full report dict."""
+    if not PG_MIN <= pg <= PG_MAX:
+        raise SQLError(f"PostgreSQL version must be {PG_MIN}-{PG_MAX}")
+    if txn_mode not in TXN_MODES:
+        raise SQLError(f"transaction mode must be one of {', '.join(TXN_MODES)}")
+    if not files or not any(t.strip() for _, t in files):
+        raise SQLError('paste SQL or upload a non-empty .sql file')
+    if len(files) > MAX_FILES or sum(len(t.encode('utf-8')) for _, t in files) > MAX_BYTES:
+        raise SQLError('limit: 100 files and 4 MiB aggregate UTF-8 SQL')
+    ctx, out, total = Ctx(pg), [], 0
+    for name, text in files:
+        text = newlines(text)
+        prepared, units, framework, notes = prepare(text, name, txn_mode)
+        lines = Lines(prepared)
+        parsed = parse(prepared)
+        total += len(parsed)
+        if total > (max_statements or MAX_STATEMENTS):
+            raise SQLError(f"limit: {max_statements or MAX_STATEMENTS} statements per check")
+        out.append(run_file(name, prepared, units, framework, notes, lines, parsed, ctx, assume_timeouts))
+    return report(out, pg)
+
+
+def run_file(name, text, units, framework, notes, lines, parsed, ctx, assume_timeouts):
+    rows = []
+    lt, st_to = {"session": None, "local": None}, {"session": None, "local": None}
+    txn = None  # {"how", "line", "held": {target: (mode, line)}, "implicit"}
+    cur_unit, warned_lt, warned_st = None, False, False
+
+    def end_txn():
+        nonlocal txn
+        txn = None
+        lt["local"] = st_to["local"] = None
+
+    for start, end, stmt, err in parsed:
+        line, col = lines.at(start)
+        # implicit transactions of the migration runner (goose, dbmate, Flyway, Liquibase changesets, --transaction always)
+        unit = next((u for u in units if u[0] <= start < u[1]), None)
+        if unit is not cur_unit:
+            if cur_unit and txn and txn["implicit"]:
+                end_txn()
+            cur_unit = unit
+            if unit and not txn:
+                txn = {"how": f"implicit ({unit[2]})", "line": line, "held": {}, "implicit": True}
+        text_of = text[start:end].strip()
+        row = {"n": len(rows) + 1, "line": line, "col": col, "end_line": lines.at(max(start, end - 1))[0],
+               "sql": text_of[:PREVIEW] + ("..." if len(text_of) > PREVIEW else "")}
+        if err:
+            el, ec = lines.at(err[1])
+            row.update(kind="(parse error)", locks=[], work="none", blocks="nothing", transaction=txn["how"] if txn else "",
+                       findings=[{"rule": "parse-error", "severity": "high", "message": f"line {el}, column {ec}: {err[0]}",
+                                  "fix": "", "line": el, "col": ec}])
+            rows.append(row)
+            continue
+        kind = type(stmt).__name__
+        if kind == "TransactionStmt":
+            k = stmt.kind
+            row.update(kind=TK.Name(k)[11:].replace("_", " "), locks=[], work="none", blocks="nothing", findings=[])
+            if k in (TK.TRANS_STMT_BEGIN, TK.TRANS_STMT_START):
+                if not txn:
+                    txn = {"how": f"BEGIN at line {line}", "line": line, "held": {}, "implicit": False}
+            if k in (TK.TRANS_STMT_ROLLBACK, TK.TRANS_STMT_ROLLBACK_TO):
+                ctx.tables.clear()
+                ctx.nn_checks.clear()
+                ctx.nn_ok.clear()
+                ctx.cons.clear()
+            if k in (TK.TRANS_STMT_COMMIT, TK.TRANS_STMT_ROLLBACK, TK.TRANS_STMT_COMMIT_PREPARED, TK.TRANS_STMT_PREPARE):
+                if txn:
+                    row["note"] = "releases " + (", ".join(f"{m} on {t}" for t, (m, _) in txn["held"].items()) or "no table locks")
+                end_txn()
+            row["transaction"] = txn["how"] if txn else ""
+            rows.append(row)
+            continue
+        if kind == "VariableSetStmt" or set_config(stmt):
+            sc = set_config(stmt)
+            if sc:
+                nm, val, local = sc
+            else:
+                nm = (stmt.name or "").lower()
+                local = stmt.is_local
+                val = timeout_value(stmt.args) if stmt.kind == VK.VAR_SET_VALUE else None
+                if stmt.kind == VK.VAR_RESET_ALL:
+                    lt["session"] = lt["local"] = st_to["session"] = st_to["local"] = None
+            for var, store in (("lock_timeout", lt), ("statement_timeout", st_to)):
+                if nm == var:
+                    if local:
+                        if txn:
+                            store["local"] = val
+                    else:
+                        store["session"] = val
+                        if txn:
+                            store["local"] = None
+            row.update(kind="SET " + nm if nm else "SET", locks=[], work="none", blocks="nothing", findings=[],
+                       transaction=txn["how"] if txn else "")
+            rows.append(row)
+            continue
+        st = analyse(stmt, ctx)
+        if kind == "LockStmt" and not txn:
+            st.find("lock-outside-transaction", "high", "LOCK TABLE can only be used in transaction blocks; outside one it fails.",
+                    "BEGIN;\n" + text_of + ";\n-- ... the statements that need the lock ...\nCOMMIT;")
+        if getattr(st, "enum_add", False) and txn:
+            if ctx.pg < 12:
+                st.find("enum-add-value", "high", "ALTER TYPE ... ADD VALUE cannot run inside a transaction block before PostgreSQL 12: it fails.", NOTX_FIX)
+            else:
+                st.find("enum-add-value", "low", "The new enum value cannot be used until this transaction commits; "
+                        "statements later in the same transaction that use it fail.", "-- commit before using the new value (separate migration).")
+        if st.notx and txn:
+            st.find("no-transaction", "high", f"{st.notx} cannot run inside a transaction block ({txn['how']}): it fails with "
+                    "\"cannot run inside a transaction block\".", NOTX_FIX)
+        effective_lt = assume_timeouts or (lt["local"] if txn and lt["local"] is not None else lt["session"])
+        effective_st = assume_timeouts or (st_to["local"] if txn and st_to["local"] is not None else st_to["session"])
+        existing = [l for l in st.locks if not l["new"]]
+        top = strongest([l["mode"] for l in existing])
+        if top and blocks_writes(top) and st.work in SLOW and not any(f["severity"] == "high" for f in st.findings):
+            st.find("long-lock", "high", f"{st.kind} holds {top} on {', '.join(l['target'] for l in existing if l['mode'] == top)} "
+                    f"while it {WORK[st.work].split(' while')[0].replace('time grows', 'runs for a time that grows')}: {blocks(top)} wait.")
+        if top and blocks_writes(top) and not effective_lt:
+            st.find("missing-lock-timeout", "medium",
+                    f"No lock_timeout is set: if {top} on {existing[0]['target'] if len(existing) == 1 else 'these tables'} has to wait "
+                    f"for a long-running query, every later query on the table queues behind it ({blocks(top)} stall).",
+                    "" if warned_lt else "SET lock_timeout = '5s';  -- at the top of the migration (SET LOCAL inside a transaction); retry on timeout")
+            warned_lt = True
+        if existing and st.work in ("scan", "rewrite", "index") and not effective_st and not warned_st:
+            st.find("missing-statement-timeout", "low", "No statement_timeout is set: nothing bounds how long this statement runs.",
+                    "SET statement_timeout = '30min';  -- an upper bound you are willing to hold these locks for")
+            warned_st = True
+        if txn:
+            held = {t: (m, ln) for t, (m, ln) in txn["held"].items() if blocks_writes(m) and not ctx.new(t)}
+            others = {t: v for t, v in held.items() if not any(l["target"] == t for l in st.locks)}
+            if others and (st.work in SLOW or (top and blocks_writes(top))):
+                desc = ", ".join(f"{m} on {t} (line {ln})" for t, (m, ln) in others.items())
+                sev = "high" if st.work in SLOW and any(m == AE for m, _ in others.values()) else "medium"
+                st.find("locks-accumulate", sev, f"Locks are held until COMMIT ({txn['how']}), so {desc} still blocks traffic "
+                        f"while this statement runs" + (" for a long time." if st.work in SLOW else " and waits for its own lock."),
+                        "-- split the migration so each risky step commits on its own (separate migration files or transactions);\n"
+                        "-- then a slow step only holds its own lock, and a lock wait cannot stall the tables changed earlier.")
+            for l in st.locks:
+                prev = txn["held"].get(l["target"])
+                if not prev or rank(l["mode"]) > rank(prev[0]):
+                    txn["held"][l["target"]] = (l["mode"], line)
+        unknown = any(f['rule'] == 'not-analysed' for f in st.findings)
+        row.update(kind=st.kind, locks=st.locks, work=st.work, blocks='unknown (not modelled)' if unknown else blocks(top), transaction=txn["how"] if txn else "",
+                   findings=sorted(st.findings, key=lambda f: -SEVERITIES.index(f["severity"])))
+        rows.append(row)
+    for r in rows:
+        r["risk"] = SEVERITIES[max((SEVERITIES.index(f["severity"]) for f in r["findings"]), default=0)]
+        r["work_text"] = WORK.get(r["work"], "")
+    return {"name": name, "framework": framework, "statements": rows,
+            "notes": [{"line": lines.at(o)[0], "text": t} for o, t in notes]}
+
+
+def report(files, pg):
+    counts = {s: 0 for s in SEVERITIES}
+    n = 0
+    for f in files:
+        for r in f["statements"]:
+            n += 1
+            counts[r["risk"]] += 1
+    risk = next((s for s in reversed(SEVERITIES) if counts[s]), "info")
+    return {"pg": pg, "risk": risk, "statements": n, "counts": counts, "files": files,
+            "scope": "Static estimates only. No database is contacted. Existing schema, data, partitions, triggers, function bodies, dependencies and actual lock duration are unknown. Review rewrite examples before running; they are not automatic fixes."}
+
+
+def newlines(text):
+    return text.lstrip("\ufeff").replace("\r\n", "\n").replace("\r", "\n")
+
+
+def failing(rep, threshold):
+    """True if any statement's risk is at or above threshold (high|medium|low|never)."""
+    if threshold == "never":
+        return False
+    return any(rep["counts"][s] for s in SEVERITIES[SEVERITIES.index(threshold):])
+
+
+# ---------- output formats ----------
+LEVEL = {"high": "error", "medium": "warning", "low": "note", "info": "note"}
+
+
+def sarif(rep, version):
+    used = sorted({f["rule"] for fl in rep["files"] for r in fl["statements"] for f in r["findings"]})
+    results = []
+    for fl in rep["files"]:
+        for r in fl["statements"]:
+            for f in r["findings"]:
+                msg = f["message"] + (f"\n\nSafer:\n{f['fix']}" if f["fix"] else "")
+                results.append({"ruleId": f["rule"], "level": LEVEL[f["severity"]], "message": {"text": msg},
+                                "properties": {"severity": f["severity"], "statement": r["kind"],
+                                               "locks": [f"{l['mode']} on {l['target']}" for l in r["locks"]]},
+                                "locations": [{"physicalLocation": {
+                                    "artifactLocation": {"uri": fl["name"].replace("\\", "/")},
+                                    "region": {"startLine": f.get("line", r["line"]), "startColumn": f.get("col", r["col"]),
+                                               **({} if "line" in f else {"endLine": r["end_line"]})}}}]})
+    return {"$schema": "https://json.schemastore.org/sarif-2.1.0.json", "version": "2.1.0",
+            "runs": [{"tool": {"driver": {"name": "localtools-postgres-migration-checker", "version": version,
+                                          "informationUri": "https://github.com/chayprabs/localtools/tree/main/postgres-migration-checker",
+                                          "rules": [{"id": r, "name": r, "shortDescription": {"text": RULES[r]}} for r in used]}},
+                      "properties": {"postgresVersion": rep["pg"]}, "results": results}]}
+
+
+def _md(s):
+    return s.replace("|", "\\|").replace("\n", " ").replace('`', '&#96;')
+
+
+def markdown(rep):
+    c = rep["counts"]
+    out = [f"# Postgres migration check (PostgreSQL {rep['pg']})", "",
+           f"**Risk: {rep['risk'].upper()}** · {rep['statements']} statements · {c['high']} high, {c['medium']} medium, "
+           f"{c['low']} low, {c['info']} info", ""]
+    for fl in rep["files"]:
+        out += [f"## {fl['name']}", "", f"Runner: {fl['framework']}", ""]
+        out += [f"- line {n['line']}: {n['text']}" for n in fl["notes"]] + ([""] if fl["notes"] else [])
+        out += ["| # | Line | Statement | Locks | Blocks | Work | Risk |", "|---|---|---|---|---|---|---|"]
+        for r in fl["statements"]:
+            locks = "; ".join(f"{l['mode']} on {l['target']}" + (" (new)" if l["new"] else "") for l in r["locks"]) or "none"
+            out.append(f"| {r['n']} | {r['line']} | `{_md(r['sql'][:80])}` | {_md(locks)} | {r['blocks']} | {r['work']} | {r['risk']} |")
+        out.append("")
+        for r in fl["statements"]:
+            for f in r["findings"]:
+                out += [f"### Line {f.get('line', r['line'])} · {f['severity']} · {f['rule']}", "", f["message"], ""]
+                if f["fix"]:
+                    fence = '`' * max(3, 1 + max((len(m.group()) for m in re.finditer(r'`+', f['fix'])), default=0))
+                    out += [fence + "sql", f["fix"], fence, ""]
+    return "\n".join(out) + "\n"
+
+
+def human(rep):
+    out = []
+    for fl in rep["files"]:
+        for n in fl["notes"]:
+            out.append(f"{fl['name']}:{n['line']}: note: {n['text']}")
+        for r in fl["statements"]:
+            locks = ", ".join(f"{l['mode']} on {l['target']}" for l in r["locks"] if not l["new"]) or "no lock on existing tables"
+            out.append(f"{fl['name']}:{r['line']}:{r['col']}: {r['risk'].upper():6} {r['kind']}: {locks}"
+                       + (f"; blocks {r['blocks']}" if r["blocks"] != "nothing" and any(not l['new'] for l in r['locks']) else "")
+                       + (f"; {r['work']}" if r["work"] in SLOW else ""))
+            for f in r["findings"]:
+                out.append(f"    [{f['rule']}] {f['message']}")
+                for ln in f["fix"].splitlines():
+                    out.append(f"      {ln}")
+    return "\n".join(out) + ("\n" if out else "")
+
+
+def dumps(rep):
+    return json.dumps(rep, indent=2, ensure_ascii=False)