pythia-postgres 0.1.0__py3-none-any.whl

pythia_postgres/queries/object-names.sql

@@ -0,0 +1,56 @@
+-- Purpose: objects in a schema whose name matches a LIKE pattern in any case,
+--          for `ls`: relations, functions and procedures, triggers, and
+--          stand-alone types
+-- Binds:   %(s)s schema, %(p)s LIKE pattern, %(n)s row cap
+-- Returns: NAME, TYPE, DETAIL (comment, signature, or the trigger's table)
+select name, type, detail
+  from (select c.relname as name,
+               case c.relkind when 'r' then 'TABLE'
+                              when 'p' then 'PARTITIONED TABLE'
+                              when 'v' then 'VIEW'
+                              when 'm' then 'MATERIALIZED VIEW'
+                              when 'S' then 'SEQUENCE'
+                              when 'f' then 'FOREIGN TABLE' end as type,
+               coalesce(obj_description(c.oid, 'pg_class'), '') as detail
+          from pg_class c
+          join pg_namespace n on n.oid = c.relnamespace
+         where n.nspname = %(s)s
+           and c.relkind in ('r', 'p', 'v', 'm', 'S', 'f')
+           and c.relname ilike %(p)s
+        union all
+        select p.proname,
+               case p.prokind when 'p' then 'PROCEDURE'
+                              when 'a' then 'AGGREGATE'
+                              when 'w' then 'WINDOW FUNCTION'
+                              else 'FUNCTION' end,
+               '(' || pg_get_function_identity_arguments(p.oid) || ')'
+          from pg_proc p
+          join pg_namespace n on n.oid = p.pronamespace
+         where n.nspname = %(s)s
+           and p.proname ilike %(p)s
+        union all
+        select t.tgname, 'TRIGGER', 'on ' || c.relname
+          from pg_trigger t
+          join pg_class c on c.oid = t.tgrelid
+          join pg_namespace n on n.oid = c.relnamespace
+         where n.nspname = %(s)s
+           and not t.tgisinternal
+           and t.tgname ilike %(p)s
+        union all
+        select ty.typname,
+               case ty.typtype when 'e' then 'ENUM'
+                               when 'd' then 'DOMAIN'
+                               when 'r' then 'RANGE'
+                               else 'TYPE' end,
+               ''
+          from pg_type ty
+          join pg_namespace n on n.oid = ty.typnamespace
+         where n.nspname = %(s)s
+           and ty.typname ilike %(p)s
+           and (ty.typtype in ('e', 'd', 'r')
+                or (ty.typtype = 'c'
+                    and exists (select 1 from pg_class rc
+                                 where rc.oid = ty.typrelid
+                                   and rc.relkind = 'c')))) o
+ order by type, name
+ limit %(n)s

pythia_postgres/queries/plpgsql-check-installed.sql

@@ -0,0 +1,7 @@
+-- Purpose: whether the plpgsql_check extension is installed in this
+--          database — without it, PostgreSQL checks a PL/pgSQL body's syntax
+--          at CREATE time and nothing else
+-- Binds:   none
+-- Returns: INSTALLED (one row, true or false)
+select exists (select 1 from pg_extension where extname = 'plpgsql_check')
+         as installed

pythia_postgres/queries/plpgsql-check.sql

@@ -0,0 +1,27 @@
+-- Purpose: what plpgsql_check reports for the PL/pgSQL functions of a schema,
+--          or those holding one name. A trigger function is checked against
+--          the first table whose trigger uses it; one no trigger uses cannot
+--          be checked (plpgsql-unchecked.sql names those).
+-- Binds:   %(s)s schema, %(n)s object name or NULL for the whole schema
+-- Returns: NAME, TYPE, LINE, POSITION, SEVERITY, MESSAGE
+select p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')'
+         as name,
+       case p.prokind when 'p' then 'PROCEDURE' else 'FUNCTION' end as type,
+       c.lineno as line,
+       c.position as position,
+       c.level as severity,
+       c.message || coalesce(' (' || c.detail || ')', '') as message
+  from pg_proc p
+  join pg_namespace n on n.oid = p.pronamespace
+  join pg_language l on l.oid = p.prolang and l.lanname = 'plpgsql'
+ cross join lateral plpgsql_check_function_tb(
+         p.oid,
+         coalesce((select t.tgrelid from pg_trigger t
+                    where t.tgfoid = p.oid
+                    order by t.oid limit 1), 0)) c
+ where n.nspname = %(s)s
+   and (%(n)s::text is null or p.proname = %(n)s)
+   and p.prorettype <> 'event_trigger'::regtype
+   and (p.prorettype <> 'trigger'::regtype
+        or exists (select 1 from pg_trigger t where t.tgfoid = p.oid))
+ order by 1, 3

pythia_postgres/queries/plpgsql-unchecked.sql

@@ -0,0 +1,16 @@
+-- Purpose: the PL/pgSQL functions plpgsql-check.sql cannot check — trigger
+--          functions no trigger uses, and event trigger functions — so the
+--          gap is named instead of read as clean
+-- Binds:   %(s)s schema, %(n)s object name or NULL for the whole schema
+-- Returns: NAME
+select p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')'
+         as name
+  from pg_proc p
+  join pg_namespace n on n.oid = p.pronamespace
+  join pg_language l on l.oid = p.prolang and l.lanname = 'plpgsql'
+ where n.nspname = %(s)s
+   and (%(n)s::text is null or p.proname = %(n)s)
+   and (p.prorettype = 'event_trigger'::regtype
+        or (p.prorettype = 'trigger'::regtype
+            and not exists (select 1 from pg_trigger t where t.tgfoid = p.oid)))
+ order by 1

pythia_postgres/queries/rehearsal-limits.sql

@@ -0,0 +1,7 @@
+-- Purpose: bound a rehearsal, for this transaction only: a preview must not
+--          hold locks or rewrite a large table for long (the confirm run is
+--          the same rehearsal, so the write gets the same bounds)
+-- Binds:   %(st)s statement_timeout, %(lt)s lock_timeout (e.g. '30s', '5s')
+-- Returns: STATEMENT_TIMEOUT, LOCK_TIMEOUT
+select set_config('statement_timeout', %(st)s, true) as statement_timeout,
+       set_config('lock_timeout', %(lt)s, true) as lock_timeout

pythia_postgres/queries/resolve.sql

@@ -0,0 +1,34 @@
+-- Purpose: every object in a schema holding a name — relations, and each
+--          overload of a function — as the catalog identifies it, so the
+--          dependency walks can start from oids instead of names
+-- Binds:   %(s)s schema, %(n)s object name (already folded)
+-- Returns: CLASSID, OBJID, TYPE, LABEL, BARE_NAME
+select 'pg_class'::regclass::oid as classid,
+       c.oid                     as objid,
+       case c.relkind when 'r' then 'TABLE'
+                      when 'p' then 'PARTITIONED TABLE'
+                      when 'v' then 'VIEW'
+                      when 'm' then 'MATERIALIZED VIEW'
+                      when 'S' then 'SEQUENCE'
+                      when 'f' then 'FOREIGN TABLE' end as type,
+       c.relname                 as label,
+       c.relname                 as bare_name
+  from pg_class c
+  join pg_namespace n on n.oid = c.relnamespace
+ where n.nspname = %(s)s
+   and c.relname = %(n)s
+   and c.relkind in ('r', 'p', 'v', 'm', 'S', 'f')
+union all
+select 'pg_proc'::regclass::oid,
+       p.oid,
+       case p.prokind when 'p' then 'PROCEDURE'
+                      when 'a' then 'AGGREGATE'
+                      when 'w' then 'WINDOW FUNCTION'
+                      else 'FUNCTION' end,
+       p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')',
+       p.proname
+  from pg_proc p
+  join pg_namespace n on n.oid = p.pronamespace
+ where n.nspname = %(s)s
+   and p.proname = %(n)s
+ order by 3, 4

pythia_postgres/queries/row-set-count.sql

@@ -0,0 +1,11 @@
+-- Purpose: how many rows an UPDATE or DELETE will touch, and a fingerprint of
+--          which (their ctids: an update in between gives a row a new one)
+-- Binds:   none — the engine puts the statement's own table and predicate
+--          where the TARGET and WHERE markers stand, and runs the text with
+--          no parameters, so a percent sign in the predicate is read as
+--          written
+-- Returns: N, FINGERPRINT
+select count(*) as n,
+       md5(coalesce(string_agg(ctid::text, ',' order by ctid), '')) as fingerprint
+  from /*TARGET*/
+ /*WHERE*/

pythia_postgres/queries/row-set-sample.sql

@@ -0,0 +1,8 @@
+-- Purpose: the first rows an UPDATE or DELETE will touch, for the person
+--          approving it to read (one beyond the sample, so a cut is announced)
+-- Binds:   none — filled and run like row-set-count.sql
+-- Returns: every column of the target
+select *
+  from /*TARGET*/
+ /*WHERE*/
+ limit 11

pythia_postgres/queries/search-path-catalog.sql

@@ -0,0 +1,7 @@
+-- Purpose: leave only pg_catalog on search_path for the rest of this
+--          transaction, as pg_dump does, so every name the catalog prints
+--          back (defaults, indexes, constraints, views) comes out qualified
+--          and the DDL runs the same from any session
+-- Binds:   none
+-- Returns: SEARCH_PATH
+select set_config('search_path', 'pg_catalog', true) as search_path

pythia_postgres/queries/search-path-first.sql

@@ -0,0 +1,13 @@
+-- Purpose: put the configured schema first on search_path for the rest of
+--          this transaction only, so a checker resolves unqualified names as
+--          the application whose schema it is would; allowed in a read-only
+--          transaction, and gone when it ends. Also says whether this account
+--          may use the schema at all: without USAGE, PostgreSQL leaves it off
+--          the path silently and every name in it looks missing.
+-- Binds:   %(s)s schema
+-- Returns: SEARCH_PATH (the path now in force), SCHEMA_USAGE, ACCOUNT
+select set_config('search_path',
+                  quote_ident(%(s)s) || ', ' || current_setting('search_path'),
+                  true) as search_path,
+       has_schema_privilege(%(s)s, 'USAGE') as schema_usage,
+       current_user as account

pythia_postgres/queries/sequence-ddl.sql

@@ -0,0 +1,16 @@
+-- Purpose: the CREATE SEQUENCE statement for one sequence
+-- Binds:   %(objid)s the sequence's oid
+-- Returns: STATEMENT
+select 'CREATE SEQUENCE ' || quote_ident(n.nspname) || '.' || quote_ident(c.relname)
+       || ' AS ' || format_type(s.seqtypid, null)
+       || ' INCREMENT BY ' || s.seqincrement
+       || ' MINVALUE ' || s.seqmin
+       || ' MAXVALUE ' || s.seqmax
+       || ' START WITH ' || s.seqstart
+       || ' CACHE ' || s.seqcache
+       || case when s.seqcycle then ' CYCLE' else ' NO CYCLE' end || ';'
+         as statement
+  from pg_sequence s
+  join pg_class c on c.oid = s.seqrelid
+  join pg_namespace n on n.oid = c.relnamespace
+ where s.seqrelid = %(objid)s::int8::oid

pythia_postgres/queries/server-version.sql

@@ -0,0 +1,6 @@
+-- Purpose: what `check` reports as the server — its version, and the
+--          database this session is connected to
+-- Binds:   none
+-- Returns: VERSION, DATABASE (one row)
+select current_setting('server_version') as version,
+       current_database()                as database

pythia_postgres/queries/session-power.sql

@@ -0,0 +1,13 @@
+-- Purpose: whether this session can do far more than changing one schema
+--          needs: a superuser, a role that creates roles, or the schema's
+--          owner
+-- Binds:   %(s)s schema
+-- Returns: SUPERUSER, CREATEROLE, OWNS_SCHEMA, ACCOUNT
+select r.rolsuper as superuser,
+       r.rolcreaterole as createrole,
+       coalesce((select ns.nspowner = r.oid
+                   from pg_namespace ns
+                  where ns.nspname = %(s)s), false) as owns_schema,
+       r.rolname as account
+  from pg_roles r
+ where r.rolname = current_user

pythia_postgres/queries/source.sql

@@ -0,0 +1,28 @@
+-- Purpose: the source of every function, procedure or view holding a name,
+--          as PostgreSQL itself prints it back — one unit per overload
+-- Binds:   %(s)s schema, %(n)s object name (already folded)
+-- Returns: UNIT, DEFINITION
+select unit, definition
+  from (select p.proname || '(' || pg_get_function_identity_arguments(p.oid)
+               || ')' as unit,
+               pg_get_functiondef(p.oid) as definition,
+               1 as k
+          from pg_proc p
+          join pg_namespace n on n.oid = p.pronamespace
+         where n.nspname = %(s)s
+           and p.proname = %(n)s
+           and p.prokind in ('f', 'p', 'w')
+        union all
+        select c.relname,
+               case c.relkind
+                 when 'v' then 'CREATE OR REPLACE VIEW '
+                 else 'CREATE MATERIALIZED VIEW ' end
+               || quote_ident(n.nspname) || '.' || quote_ident(c.relname)
+               || E' AS\n' || pg_get_viewdef(c.oid, true),
+               2
+          from pg_class c
+          join pg_namespace n on n.oid = c.relnamespace
+         where n.nspname = %(s)s
+           and c.relname = %(n)s
+           and c.relkind in ('v', 'm')) s
+ order by k, unit

pythia_postgres/queries/table-columns.sql

@@ -0,0 +1,16 @@
+-- Purpose: column definitions as a CREATE TABLE writes them, defaults,
+--          identity and generated expressions included
+-- Binds:   %(objid)s the table's oid
+-- Returns: NAME, DATA_TYPE, NOT_NULL, DEFAULT_EXPR, IDENTITY, GENERATED
+select quote_ident(a.attname)                     as name,
+       format_type(a.atttypid, a.atttypmod)       as data_type,
+       a.attnotnull                               as not_null,
+       pg_get_expr(d.adbin, d.adrelid)            as default_expr,
+       a.attidentity                              as identity,
+       a.attgenerated                             as generated
+  from pg_attribute a
+  left join pg_attrdef d on d.adrelid = a.attrelid and d.adnum = a.attnum
+ where a.attrelid = %(objid)s::int8::oid
+   and a.attnum > 0
+   and not a.attisdropped
+ order by a.attnum

pythia_postgres/queries/table-constraints.sql

@@ -0,0 +1,13 @@
+-- Purpose: a table's primary key, unique, check, exclusion and foreign key
+--          constraints as PostgreSQL prints them back (NOT NULL is on the
+--          columns, so contype 'n' of PostgreSQL 18 is left out)
+-- Binds:   %(objid)s the table's oid
+-- Returns: NAME, DEFINITION
+select quote_ident(k.conname)            as name,
+       pg_get_constraintdef(k.oid, true) as definition
+  from pg_constraint k
+ where k.conrelid = %(objid)s::int8::oid
+   and k.contype in ('p', 'u', 'c', 'x', 'f')
+ order by case k.contype when 'p' then 1 when 'u' then 2 when 'c' then 3
+                         when 'x' then 4 else 5 end,
+          k.conname

pythia_postgres/queries/table-extras.sql

@@ -0,0 +1,43 @@
+-- Purpose: the statements that follow a CREATE TABLE: indexes no constraint
+--          owns, triggers, and comments on the table and its columns
+-- Binds:   %(objid)s the table's oid
+-- Returns: STATEMENT
+select stmt as statement
+  from (select 1 as k, ic.relname as sort_key,
+               pg_get_indexdef(i.indexrelid) || ';' as stmt
+          from pg_index i
+          join pg_class ic on ic.oid = i.indexrelid
+         where i.indrelid = %(objid)s::int8::oid
+           and not exists (select 1 from pg_constraint k
+                            where k.conindid = i.indexrelid
+                              and k.contype in ('p', 'u', 'x'))
+        union all
+        select 2, t.tgname, pg_get_triggerdef(t.oid, true) || ';'
+          from pg_trigger t
+         where t.tgrelid = %(objid)s::int8::oid
+           and not t.tgisinternal
+        union all
+        select 3, '',
+               'COMMENT ON TABLE ' || quote_ident(n.nspname) || '.'
+               || quote_ident(c.relname) || ' IS ' || quote_literal(d.description)
+               || ';'
+          from pg_class c
+          join pg_namespace n on n.oid = c.relnamespace
+          join pg_description d on d.objoid = c.oid
+                               and d.classoid = 'pg_class'::regclass
+                               and d.objsubid = 0
+         where c.oid = %(objid)s::int8::oid
+        union all
+        select 4, lpad(a.attnum::text, 6, '0'),
+               'COMMENT ON COLUMN ' || quote_ident(n.nspname) || '.'
+               || quote_ident(c.relname) || '.' || quote_ident(a.attname)
+               || ' IS ' || quote_literal(d.description) || ';'
+          from pg_class c
+          join pg_namespace n on n.oid = c.relnamespace
+          join pg_attribute a on a.attrelid = c.oid
+          join pg_description d on d.objoid = c.oid
+                               and d.classoid = 'pg_class'::regclass
+                               and d.objsubid = a.attnum
+         where c.oid = %(objid)s::int8::oid
+           and a.attnum > 0) x
+ order by k, sort_key

pythia_postgres/queries/table-head.sql

@@ -0,0 +1,18 @@
+-- Purpose: what the first line of a table's DDL needs — its qualified name,
+--          persistence, partition key, and the parent it is a partition of
+-- Binds:   %(objid)s the table's oid
+-- Returns: QNAME, UNLOGGED, PARTITION_KEY, PARTITION_OF, PARTITION_BOUND
+select quote_ident(n.nspname) || '.' || quote_ident(c.relname) as qname,
+       c.relpersistence = 'u' as unlogged,
+       case when c.relkind = 'p' then pg_get_partkeydef(c.oid) end as partition_key,
+       (select quote_ident(pn.nspname) || '.' || quote_ident(pc.relname)
+          from pg_inherits i
+          join pg_class pc on pc.oid = i.inhparent
+          join pg_namespace pn on pn.oid = pc.relnamespace
+         where c.relispartition
+           and i.inhrelid = c.oid) as partition_of,
+       case when c.relispartition then pg_get_expr(c.relpartbound, c.oid) end
+         as partition_bound
+  from pg_class c
+  join pg_namespace n on n.oid = c.relnamespace
+ where c.oid = %(objid)s::int8::oid

pythia_postgres/read.py

@@ -0,0 +1,299 @@
+"""The read tier for PostgreSQL: pythia's Learn movement, asked of the live
+catalog.
+
+PostgreSQL's catalog records less than Oracle's in one place that matters:
+pg_depend does not see into a PL/pgSQL body, or a SQL function whose body is
+a string. The dependency walks therefore ask twice — the catalog, and then a
+whole-word search of function source — and mark what only the search vouches
+for (how = "text"), naming that blind spot every time instead of returning a
+clean-looking answer it cannot stand behind.
+"""
+import re
+
+from pythia_core.output import TEXT_HOW
+
+from .catalog import fold, q
+
+CATALOG_HOW = "catalog"
+FUNCTION_TYPES = ("FUNCTION", "PROCEDURE", "WINDOW FUNCTION", "AGGREGATE")
+SOURCE_TYPES = ("FUNCTION", "PROCEDURE", "WINDOW FUNCTION", "VIEW",
+                "MATERIALIZED VIEW")
+COLUMN_TYPES = ("TABLE", "PARTITIONED TABLE", "VIEW", "MATERIALIZED VIEW",
+                "FOREIGN TABLE")
+TABLE_TYPES = ("TABLE", "PARTITIONED TABLE")
+
+DDL_NOTE = ("-- rebuilt from the catalog by pythia-pg; pg_dump --schema-only "
+            "is the reference")
+
+BLIND_TEXT_IN = (
+    "PL/pgSQL bodies and SQL functions with a string body are not in "
+    "pg_depend, so functions are matched by name as text ([text]): a column "
+    "or variable with the same name gives a false match, and a name built at "
+    "run time (EXECUTE format(...)) is not seen at all")
+BLIND_TEXT_OUT = (
+    "function bodies are read as text against the names of existing tables, "
+    "views, sequences and functions ([text]): a variable or column sharing a "
+    "name gives a false match, a name built at run time (EXECUTE) is not "
+    "seen, and a name that exists in several schemas is listed for each — "
+    "search_path decides which one runs")
+BLIND_ELSEWHERE = (
+    "other databases on this server, and other servers (dblink, "
+    "postgres_fdw), are never seen")
+NOT_INSTALLED = (
+    "plpgsql_check is not installed in this database, so the only check was "
+    "PostgreSQL's own, of syntax, when each function was created: a missing "
+    "table or column in a PL/pgSQL body shows up at run time. A superuser "
+    "can add it where the server has the package: CREATE EXTENSION "
+    "plpgsql_check;")
+
+
+def resolve(conn, schema, name):
+    """(classid, objid, type, label, bare_name) of everything holding a name."""
+    return q(conn, "resolve.sql", s=schema, n=fold(name))[1]
+
+
+def object_names(conn, schema, pattern, fetch):
+    return q(conn, "object-names.sql", s=schema, p=pattern, n=fetch)
+
+
+def split_definition(definition):
+    return str(definition).rstrip("\n").split("\n")
+
+
+def source(conn, schema, name):
+    rows = []
+    for unit, definition in q(conn, "source.sql", s=schema, n=fold(name))[1]:
+        rows.extend((unit, i, line)
+                    for i, line in enumerate(split_definition(definition), 1))
+    return rows
+
+
+def columns(conn, schema, name):
+    rel = [r for r in resolve(conn, schema, name) if r[2] in COLUMN_TYPES]
+    if not rel:
+        return None
+    return q(conn, "columns.sql", objid=rel[0][1])
+
+
+def table_ddl(conn, objid):
+    qname, unlogged, partkey, partof, bound = q(conn, "table-head.sql",
+                                                objid=objid)[1][0]
+    lines = []
+    if partof:
+        tail = f" PARTITION BY {partkey}" if partkey else ""
+        lines.append(f"CREATE TABLE {qname} PARTITION OF {partof} {bound}{tail};")
+    else:
+        body = []
+        for name, dtype, not_null, default, identity, generated in q(
+                conn, "table-columns.sql", objid=objid)[1]:
+            col = f"    {name} {dtype}"
+            if generated:
+                col += f" GENERATED ALWAYS AS ({default}) STORED"
+            elif identity:
+                col += (" GENERATED " + ("ALWAYS" if identity == "a" else
+                                         "BY DEFAULT") + " AS IDENTITY")
+            elif default is not None:
+                col += f" DEFAULT {default}"
+            if not_null:
+                col += " NOT NULL"
+            body.append(col)
+        body.extend(f"    CONSTRAINT {cname} {cdef}" for cname, cdef in
+                    q(conn, "table-constraints.sql", objid=objid)[1])
+        lines.append(f"CREATE {'UNLOGGED ' if unlogged else ''}TABLE {qname} (")
+        lines.append(",\n".join(body))
+        lines.append(")" + (f" PARTITION BY {partkey}" if partkey else "") + ";")
+    extras = [r[0] for r in q(conn, "table-extras.sql", objid=objid)[1]]
+    if extras:
+        lines.append("")
+        lines.extend(extras)
+    return "\n".join(lines)
+
+
+def ddl(conn, schema, name):
+    # names printed back by the catalog follow search_path: fix it first, so
+    # the DDL means the same in whatever session runs it
+    q(conn, "search-path-catalog.sql")
+    objs = resolve(conn, schema, name)
+    if not objs:
+        return ""
+    parts = []
+    for _classid, objid, otype, label, _bare in objs:
+        if otype in TABLE_TYPES:
+            parts.append(table_ddl(conn, objid))
+        elif otype == "SEQUENCE":
+            parts.append(q(conn, "sequence-ddl.sql", objid=objid)[1][0][0])
+        elif otype not in SOURCE_TYPES:
+            parts.append(f"-- {label}: pythia-pg does not rebuild the DDL of "
+                         f"a {otype} yet; pg_dump --schema-only is the "
+                         "reference")
+    if any(r[2] in SOURCE_TYPES for r in objs):
+        for _unit, definition in q(conn, "source.sql", s=schema, n=fold(name))[1]:
+            text = str(definition).rstrip()
+            parts.append(text if text.endswith(";") else text + ";")
+    if any(r[2] in TABLE_TYPES for r in objs):
+        parts.insert(0, DDL_NOTE)
+    return "\n\n".join(parts)
+
+
+GREP_COLS = ("NAME", "TYPE", "LINE", "TEXT")
+
+
+def grep(conn, schema, text, fetch):
+    needle = str(text).lower()
+    out = []
+    for unit, otype, definition in q(conn, "grep.sql", s=schema, t=text)[1]:
+        for i, line in enumerate(split_definition(definition), 1):
+            if needle in line.lower():
+                out.append((unit, otype, i, line.strip()))
+                if len(out) >= fetch:
+                    return GREP_COLS, out
+    return GREP_COLS, out
+
+
+# --- dependency walks ---------------------------------------------------------
+
+def word_pattern(name):
+    """A PostgreSQL regular expression matching name as a whole word in any
+    case (the query uses ~*): every character that is not a letter, digit or
+    underscore is escaped."""
+    esc = "".join(ch if ch.isalnum() or ch == "_" else "\\" + ch for ch in name)
+    return f"\\m{esc}\\M"
+
+
+_COMMENTS = re.compile(r"--[^\n]*|/\*.*?\*/", re.S)
+_QUOTED = re.compile(r'"((?:[^"]|"")+)"')
+_WORD = re.compile(r"[A-Za-z_][A-Za-z0-9_$]*")
+
+
+def body_names(body):
+    """The names a function body could be referring to: unquoted words
+    folded to lower case, quoted identifiers exactly. Comments are dropped;
+    string literals are kept, because dynamic SQL and nextval('seq') name
+    real objects inside them."""
+    text = _COMMENTS.sub(" ", str(body or ""))
+    names = {m.group(1).replace('""', '"') for m in _QUOTED.finditer(text)}
+    names |= {w.lower() for w in _WORD.findall(_QUOTED.sub(" ", text))}
+    return names
+
+
+def bare(name, otype):
+    return name.split("(", 1)[0] if otype in FUNCTION_TYPES else name
+
+
+def walk(roots, depth, children):
+    """Depth-first from each root, in the order a tree is read. An object
+    reached twice is listed twice (that is the graph) but walked once."""
+    rows = []
+    seen = {(r[0], r[1]) for r in roots}
+
+    def visit(node, level):
+        if level > depth:
+            return
+        for schema, name, otype, nclass, nobj, how in children(node):
+            rows.append((level, schema, name, otype, how))
+            if nobj is not None and (nclass, nobj) not in seen:
+                seen.add((nclass, nobj))
+                visit((nclass, nobj, otype, bare(name, otype)), level + 1)
+
+    for classid, objid, otype, _label, bare_name in roots:
+        visit((classid, objid, otype, bare_name), 1)
+    return rows
+
+
+def _overload_note(roots, name):
+    if len(roots) > 1:
+        labels = ", ".join(r[3] for r in roots)
+        return f"{name} names {len(roots)} objects ({labels}); the walk starts from each"
+    return None
+
+
+def dependents(conn, schema, name, depth):
+    roots = resolve(conn, schema, name)
+    if not roots:
+        return None
+
+    def children(node):
+        classid, objid, otype, bare_name = node
+        out = [(s, n, t, c, o, CATALOG_HOW) for s, n, t, c, o in
+               q(conn, "dependents-catalog.sql", classid=classid, objid=objid)[1]]
+        seen = {o for *_, o, _ in out if o is not None}
+        for s, n, t, c, o in q(conn, "dependents-text.sql",
+                               pattern=word_pattern(bare_name), objid=objid)[1]:
+            if o not in seen:
+                out.append((s, n, t, c, o, TEXT_HOW))
+        return out
+
+    rows = walk(roots, depth, children)
+    notes = [n for n in (_overload_note(roots, name), BLIND_TEXT_IN,
+                         BLIND_ELSEWHERE) if n]
+    return rows, notes
+
+
+def dependencies(conn, schema, name, depth):
+    roots = resolve(conn, schema, name)
+    if not roots:
+        return None
+    cache = {}
+
+    def candidates():
+        if "all" not in cache:
+            by_name = {}
+            for bare_name, *rest in q(conn, "name-candidates.sql")[1]:
+                by_name.setdefault(bare_name, []).append(tuple(rest))
+            cache["all"] = by_name
+        return cache["all"]
+
+    def children(node):
+        classid, objid, otype, _bare = node
+        out = [(s, n, t, c, o, CATALOG_HOW) for s, n, t, c, o in
+               q(conn, "dependencies-catalog.sql", classid=classid, objid=objid)[1]]
+        if otype not in FUNCTION_TYPES:
+            return out
+        found = q(conn, "function-body.sql", objid=objid)[1]
+        if not found or found[0][0] not in ("plpgsql", "sql"):
+            return out
+        seen = {o for *_, o, _ in out if o is not None} | {objid}
+        words = body_names(found[0][1])
+        for word in sorted(words):
+            for s, n, t, c, o in candidates().get(word, ()):
+                if o not in seen:
+                    seen.add(o)
+                    out.append((s, n, t, c, o, TEXT_HOW))
+        return out
+
+    rows = walk(roots, depth, children)
+    notes = [n for n in (_overload_note(roots, name), BLIND_TEXT_OUT,
+                         BLIND_ELSEWHERE) if n]
+    return rows, notes
+
+
+# --- errors -----------------------------------------------------------------------
+
+def compile_errors(conn, schema, name):
+    if name is not None:
+        objs = resolve(conn, schema, name)
+        if not objs:
+            return None
+        if not any(r[2] in FUNCTION_TYPES for r in objs):
+            return [], (f"{name} is a {objs[0][2]}, not a function: there is no "
+                        "PL/pgSQL body for plpgsql_check to read")
+    if not q(conn, "plpgsql-check-installed.sql")[1][0][0]:
+        return [], NOT_INSTALLED
+    n = fold(name) if name is not None else None
+    # unqualified names in a body resolve by search_path at run time; check
+    # them the way the schema's own application resolves them
+    _path, usage, account = q(conn, "search-path-first.sql", s=schema)[1][0]
+    if not usage:
+        return [], (f"this account has no USAGE on schema {schema}, so "
+                    "PostgreSQL leaves it off search_path and every name in "
+                    "it would look missing to plpgsql_check — no list is "
+                    "better than a false one. A DBA grants it: GRANT USAGE "
+                    f"ON SCHEMA {schema} TO {account};")
+    rows = q(conn, "plpgsql-check.sql", s=schema, n=n)[1]
+    unchecked = [r[0] for r in q(conn, "plpgsql-unchecked.sql", s=schema, n=n)[1]]
+    blind = None
+    if unchecked:
+        blind = (f"not checked: {', '.join(unchecked)} — plpgsql_check reads a "
+                 "trigger function through a table whose trigger uses it, and "
+                 "these have none (or are event trigger functions)")
+    return rows, blind