pythia-postgres 0.1.0__py3-none-any.whl

pythia_postgres/__init__.py

@@ -0,0 +1,5 @@
+"""pythia for PostgreSQL: PL/pgSQL development for AI agents, over
+pythia-core. Alpha — see README.md for what works today."""
+__version__ = "0.1.0"     # kept equal to pyproject.toml (tests/test_postgres.py)
+
+from .engine import PostgresEngine  # noqa: E402,F401 — needs __version__ first

pythia_postgres/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

pythia_postgres/catalog.py

@@ -0,0 +1,59 @@
+"""Where pythia-pg's SQL lives and how it is run.
+
+Every statement is a file in queries/, under pythia-core's contract:
+pyformat binds, a header, and its binds declared here. tests/test_postgres.py
+fails on drift in either direction, so queries/ stays reviewable without a
+database.
+"""
+import pathlib
+
+from pythia_core.queries import load_query, run_query
+
+QUERY_DIR = pathlib.Path(__file__).resolve().parent / "queries"
+
+QUERY_BINDS = {
+    "server-version.sql": set(),
+    "current-schema.sql": set(),
+    "resolve.sql": {"s", "n"},
+    "object-names.sql": {"s", "p", "n"},
+    "source.sql": {"s", "n"},
+    "columns.sql": {"objid"},
+    "table-head.sql": {"objid"},
+    "table-columns.sql": {"objid"},
+    "table-constraints.sql": {"objid"},
+    "table-extras.sql": {"objid"},
+    "sequence-ddl.sql": {"objid"},
+    "grep.sql": {"s", "t"},
+    "dependents-catalog.sql": {"classid", "objid"},
+    "dependents-text.sql": {"pattern", "objid"},
+    "dependencies-catalog.sql": {"classid", "objid"},
+    "function-body.sql": {"objid"},
+    "name-candidates.sql": set(),
+    "plpgsql-check-installed.sql": set(),
+    "search-path-first.sql": {"s"},
+    "search-path-catalog.sql": set(),
+    "plpgsql-check.sql": {"s", "n"},
+    "plpgsql-unchecked.sql": {"s", "n"},
+    "code-objects.sql": {"s", "n"},
+    "comment-current.sql": {"s", "t", "c"},
+    "rehearsal-limits.sql": {"st", "lt"},
+    "session-power.sql": {"s"},
+    "row-set-count.sql": set(),
+    "row-set-sample.sql": set(),
+}
+
+
+def q(conn, name, **binds):
+    """(COLUMNS, rows) for one query file. Column names are upper case, as
+    every pythia engine reports them."""
+    cols, rows = run_query(conn, load_query(QUERY_DIR, name), binds)
+    return [str(c).upper() for c in cols], rows
+
+
+def fold(name):
+    """A name as the catalog holds it: an unquoted identifier folds to lower
+    case; a double-quoted one is taken exactly, quotes removed."""
+    name = str(name).strip()
+    if len(name) >= 2 and name[0] == name[-1] == '"':
+        return name[1:-1].replace('""', '"')
+    return name.lower()

pythia_postgres/cli.py

@@ -0,0 +1,8 @@
+"""The `pythia-pg` command: pythia-core's command line, handed this engine."""
+from pythia_core import cli
+
+from .engine import PostgresEngine
+
+
+def main(argv=None):
+    return cli.main(PostgresEngine(), argv)

pythia_postgres/engine.py

@@ -0,0 +1,213 @@
+"""PostgreSQL, through psycopg 3, as a pythia-core engine.
+
+It answers every tier of pythia_core.engine: connect (here), read (read.py),
+write (write.py) — the write tier rehearsing each statement inside a
+transaction, since PostgreSQL's DDL runs in one — release (a script split
+where PostgreSQL would split it), lint (rules.py) and harness (guard.py).
+"""
+import copy
+import sys
+
+from . import __version__, guard, read, write
+from .catalog import QUERY_BINDS, QUERY_DIR, q  # noqa: F401 — QUERY_* re-exported
+
+CONFIG_REL = ".pythia/postgres/connections.json"
+REQUIRED = ("host", "dbname", "user")
+
+
+class PostgresEngine:
+    name = "postgres"
+    label = "PostgreSQL"
+    command = "pythia-pg"
+    env_prefix = "PYTHIA_PG"
+    version = __version__
+    bind_style = "pyformat"
+    default_port = 5432
+    # printed by `pythia-pg policy`: is rollback real, group by group?
+    rollback_notes = {
+        "source": "Yes — the definition is snapshotted before every write; a "
+                  "new object's undo is a DROP.",
+        "comments": "Yes — the previous comment is snapshotted.",
+        "data_dml": "No. After commit only a backup or point-in-time recovery "
+                    "brings rows back. Revalidation checks the rows; it is not "
+                    "an undo.",
+        "structural": "No. A dropped column or table is gone; the rehearsal "
+                      "shows what breaks before anything commits.",
+        "grants": "By hand — write the opposite GRANT or REVOKE.",
+        "session": "Not needed — it ends with the connection.",
+    }
+
+    # --- the connection's life ------------------------------------------------
+
+    def driver_errors(self):
+        try:
+            import psycopg
+        except ModuleNotFoundError:
+            sys.exit("The 'psycopg' package is required to connect: "
+                     'pip install "psycopg[binary]"')
+        return (psycopg.Error,)
+
+    def connect(self, entry):
+        import psycopg
+        gaps = [k for k in REQUIRED if not entry.get(k)]
+        if gaps:
+            sys.exit(f"Connection is missing {', '.join(map(repr, gaps))} — "
+                     f"fill in {CONFIG_REL}.")
+        kw = {"host": entry["host"], "port": int(entry.get("port") or 5432),
+              "dbname": entry["dbname"], "user": entry["user"],
+              "connect_timeout": int(entry.get("connect_timeout") or 10),
+              "application_name": self.command}
+        # no password key means libpq's own sources (PGPASSWORD, ~/.pgpass)
+        if entry.get("password"):
+            kw["password"] = entry["password"]
+        if entry.get("sslmode"):
+            kw["sslmode"] = entry["sslmode"]
+        return psycopg.connect(**kw)
+
+    def session(self, conn, readonly):
+        if readonly:
+            # every transaction this command opens is READ ONLY, so
+            # PostgreSQL itself refuses a write — the second line of defence.
+            # dblink and foreign data wrappers reach past it; the agent
+            # account should not hold them.
+            conn.read_only = True
+        return conn
+
+    def close(self, conn):
+        conn.close()
+
+    def connect_failure(self, exc, conn_name, entry):
+        """Name the next step for the failures PostgreSQL has already
+        diagnosed precisely. Connection errors may carry no SQLSTATE, so the
+        server's message text is the fallback."""
+        text = str(exc)
+        state = getattr(exc, "sqlstate", None) or ""
+        low = text.lower()
+        who = entry.get("user") or "<the connecting user>"
+        head = f"Could not connect using connection {conn_name!r}: {text}"
+        if state == "28P01" or "password authentication failed" in low:
+            return (f"{head}\nWrong password for {who}. Check the entry in "
+                    f"{CONFIG_REL} (or ~/.pgpass when it holds no password).")
+        if "no pg_hba.conf entry" in low:
+            return (f"{head}\nThe server refuses this host/user/database "
+                    "combination. A superuser adds a line for it to "
+                    "pg_hba.conf and reloads the configuration.")
+        if state == "28000" or "not permitted to log in" in low:
+            return (f"{head}\nThe role {who} may not log in. A superuser "
+                    f"allows it:\n  ALTER ROLE {who} LOGIN;")
+        if state == "3D000" or ("database" in low and "does not exist" in low):
+            return (f"{head}\nThe database {entry.get('dbname')!r} does not "
+                    f"exist on this server. Check \"dbname\" in {CONFIG_REL}.")
+        if state == "53300" or "too many clients" in low:
+            return (f"{head}\nThe server is at max_connections. Retry later, "
+                    "or ask a DBA which sessions hold the slots.")
+        return (f"{head}\nCheck host/port/dbname, the credentials, and that "
+                "the server is reachable from here. Use --conn NAME to try a "
+                "different entry.")
+
+    def schema_of(self, entry):
+        # an unquoted PostgreSQL identifier is lower case in the catalog
+        return str(entry.get("schema") or "public").lower()
+
+    def target_of(self, entry):
+        host = entry.get("host")
+        if not host:
+            return ""
+        target = f"{host}:{entry.get('port') or self.default_port}"
+        return f"{target}/{entry['dbname']}" if entry.get("dbname") else target
+
+    # --- what check asks --------------------------------------------------------
+
+    def server_version(self, conn):
+        version, database = q(conn, "server-version.sql")[1][0]
+        return f"PostgreSQL {version} — database {database}"
+
+    def current_schema(self, conn):
+        rows = q(conn, "current-schema.sql")[1]
+        return rows[0][0] if rows and rows[0] and rows[0][0] else None
+
+    # --- the read tier (read.py) -------------------------------------------------
+
+    def object_names(self, conn, schema, pattern, fetch):
+        return read.object_names(conn, schema, pattern, fetch)
+
+    def source(self, conn, schema, name):
+        return read.source(conn, schema, name)
+
+    def columns(self, conn, schema, name):
+        return read.columns(conn, schema, name)
+
+    def ddl(self, conn, schema, name):
+        return read.ddl(conn, schema, name)
+
+    def grep(self, conn, schema, text, fetch):
+        return read.grep(conn, schema, text, fetch)
+
+    def dependencies(self, conn, schema, name, depth):
+        return read.dependencies(conn, schema, name, depth)
+
+    def dependents(self, conn, schema, name, depth):
+        return read.dependents(conn, schema, name, depth)
+
+    def compile_errors(self, conn, schema, name):
+        return read.compile_errors(conn, schema, name)
+
+    # --- the write tier (write.py) -----------------------------------------------
+
+    def classify(self, text):
+        return write.classify(text)
+
+    def prepare_statement(self, text, group):
+        return write.prepare_statement(text, group)
+
+    def parse_object(self, stmt, group):
+        return write.parse_object(stmt, group)
+
+    def destructive_reason(self, stmt, group):
+        return write.destructive_reason(stmt, group)
+
+    def dml_probe(self, stmt):
+        return write.dml_probe(stmt)
+
+    def measure_row_set(self, conn, target, pred):
+        return write.measure_row_set(conn, target, pred)
+
+    def snapshot(self, conn, schema, group, ident):
+        return write.snapshot(conn, schema, group, ident)
+
+    def rehearse(self, conn, schema, group, stmt, ident, snapshot):
+        return write.rehearse(conn, schema, group, stmt, ident, snapshot)
+
+    def restore_statement(self, group, ident, before, outcome):
+        return write.restore_statement(group, ident, before, outcome)
+
+    def privilege_warning(self, conn, schema):
+        return write.privilege_warning(conn, schema)
+
+    # --- the release tier ----------------------------------------------------------
+
+    def split_script(self, text):
+        return write.split_script(text)
+
+    # --- the lint tier (rules.py) ---------------------------------------------------
+
+    def lint_rules(self):
+        from . import rules
+        return list(rules.RULES)
+
+    # --- the harness tier (guard.py) ---------------------------------------------
+
+    def raw_client_pattern(self):
+        return guard.CLIENTS
+
+    def write_sql_pattern(self):
+        return guard.WRITE_SQL
+
+    def script_pattern(self):
+        return guard.SCRIPT
+
+    def connections_template(self):
+        return copy.deepcopy(guard.TEMPLATE)
+
+    def skills_dir(self):
+        return guard.SKILLS_DIR

pythia_postgres/guard.py

@@ -0,0 +1,54 @@
+"""The harness tier: what pythia-core's guard and install need to know
+about PostgreSQL. The guard denies psql (and pgcli, pg_restore) when it
+would write around the gate; reads through psql are left to the client's
+own prompt.
+
+The patterns read a shell command for what it names, never for what it
+means, so a write spelled in a way they do not list gets through, and a
+read that merely mentions DROP TABLE is denied. The gate behind them holds
+either way (pythia-core's SECURITY.md).
+"""
+import pathlib
+
+CLIENTS = r"psql|pgcli|pg_restore"
+
+# matched against the whole command, quoted SQL included
+WRITE_SQL = "|".join((
+    r"\b(create|alter|drop|truncate|grant|revoke|reindex|cluster|vacuum|"
+    r"comment\s+on|insert\s+into|delete\s+from|merge\s+into|lock\s+table|"
+    r"refresh\s+materialized|security\s+label|reassign\s+owned|"
+    r"import\s+foreign\s+schema)\b",
+    r"\bupdate\s+(only\s+)?[\w\".]+(\s+(as\s+)?\w+)?\s+set\b",
+    r"\bdo\s*(\$|')",                         # an anonymous block
+    r"\bcall\s+[\w\".]+\s*\(",
+    r"\bcopy\b[^;|]*\bfrom\b",                 # COPY / \copy into a table
+    r"\bselect\b[^;]*\binto\b",               # SELECT ... INTO makes a table
+    # functions that change state from a plain SELECT; sequences advance
+    # outside any transaction
+    r"\b(nextval|setval|pg_terminate_backend|pg_cancel_backend|lo_unlink|"
+    r"lo_import|dblink_exec|pg_reload_conf)\s*\(",
+    r"\\i(r|nclude(_relative)?)?\b",           # psql running a script file
+))
+
+# matched with quoted text emptied: what the shell hands the client
+SCRIPT = "|".join((
+    r"(?-i:(^|\s)(-f\s*\S|--file(=|\s)))",      # psql -f (case matters: -F is not)
+    r"(^|[^<])<(?![<(&])\s*\S",                 # stdin from a file, not <<, <(
+    r"\|\s*(\S*[/\\])?(psql|pgcli)\b",          # a script piped into the client
+    r"\bpg_restore\b",                          # a dump into a database
+))
+
+TEMPLATE = {
+    "default": "dev",
+    "dev": {
+        "host": "",
+        "port": 5432,
+        "dbname": "",
+        "user": "",
+        "password": "",
+        "schema": "APP_OWNER",
+        "sslmode": "",
+    },
+}
+
+SKILLS_DIR = pathlib.Path(__file__).resolve().parent / "skills"

pythia_postgres/queries/code-objects.sql

@@ -0,0 +1,28 @@
+-- Purpose: every function, procedure and view in a schema holding a name,
+--          with the statement that recreates it and the signature that drops
+--          it — what a write can replace, snapshotted before it runs
+-- Binds:   %(s)s schema, %(n)s object name (already folded)
+-- Returns: UNIT, KIND, QUALIFIED, DEFINITION
+select p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')'
+         as unit,
+       case p.prokind when 'p' then 'PROCEDURE' else 'FUNCTION' end as kind,
+       quote_ident(n.nspname) || '.' || quote_ident(p.proname) || '('
+       || pg_get_function_identity_arguments(p.oid) || ')' as qualified,
+       pg_get_functiondef(p.oid) as definition
+  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,
+       'VIEW',
+       quote_ident(n.nspname) || '.' || quote_ident(c.relname),
+       'CREATE OR REPLACE VIEW ' || quote_ident(n.nspname) || '.'
+       || quote_ident(c.relname) || E' AS\n' || pg_get_viewdef(c.oid, true)
+  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 = 'v'
+ order by 1

pythia_postgres/queries/columns.sql

@@ -0,0 +1,15 @@
+-- Purpose: the columns of one table or view, for `cols`
+-- Binds:   %(objid)s the relation's oid (from resolve.sql)
+-- Returns: POSITION, COLUMN_NAME, DATA_TYPE, NULLABLE, COLUMN_DEFAULT, COMMENT
+select a.attnum                                   as position,
+       a.attname                                  as column_name,
+       format_type(a.atttypid, a.atttypmod)       as data_type,
+       case when a.attnotnull then 'NO' else 'YES' end as nullable,
+       coalesce(pg_get_expr(d.adbin, d.adrelid), '') as column_default,
+       coalesce(col_description(a.attrelid, a.attnum), '') as comment
+  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/comment-current.sql

@@ -0,0 +1,17 @@
+-- Purpose: the comment on a table, or on one of its columns, as it stands —
+--          the snapshot a COMMENT statement is undone with
+-- Binds:   %(s)s schema, %(t)s table, %(c)s column, or NULL for the table
+-- Returns: COMMENT (one row, NULL when there is none; no row when the table
+--          does not exist)
+select case when %(c)s::text is null
+            then obj_description(c.oid, 'pg_class')
+            else (select col_description(c.oid, a.attnum)
+                    from pg_attribute a
+                   where a.attrelid = c.oid
+                     and a.attname = %(c)s
+                     and not a.attisdropped)
+       end as comment
+  from pg_class c
+  join pg_namespace n on n.oid = c.relnamespace
+ where n.nspname = %(s)s
+   and c.relname = %(t)s

pythia_postgres/queries/current-schema.sql

@@ -0,0 +1,5 @@
+-- Purpose: where an unqualified name lands for this session: the first
+--          schema on search_path that exists, NULL when none does
+-- Binds:   none
+-- Returns: CURRENT_SCHEMA (one row)
+select current_schema() as current_schema

pythia_postgres/queries/dependencies-catalog.sql

@@ -0,0 +1,66 @@
+-- Purpose: what the catalog (pg_depend) records one object as depending on
+--          — directly, and for a table or view through its rewrite rules,
+--          column defaults, constraints and triggers. System schemas are
+--          left out.
+-- Binds:   %(classid)s the object's catalog (pg_class or pg_proc, as an oid)
+--          %(objid)s   the object's oid
+-- Returns: SCHEMA, NAME, TYPE, NEXT_CLASSID, NEXT_OBJID
+with parts as (
+  select %(classid)s::int8::oid as classid, %(objid)s::int8::oid as objid
+  union all
+  select 'pg_rewrite'::regclass::oid, r.oid
+    from pg_rewrite r
+   where %(classid)s::int8::oid = 'pg_class'::regclass::oid
+     and r.ev_class = %(objid)s::int8::oid
+  union all
+  select 'pg_attrdef'::regclass::oid, ad.oid
+    from pg_attrdef ad
+   where %(classid)s::int8::oid = 'pg_class'::regclass::oid
+     and ad.adrelid = %(objid)s::int8::oid
+  union all
+  select 'pg_constraint'::regclass::oid, k.oid
+    from pg_constraint k
+   where %(classid)s::int8::oid = 'pg_class'::regclass::oid
+     and k.conrelid = %(objid)s::int8::oid
+  union all
+  select 'pg_trigger'::regclass::oid, t.oid
+    from pg_trigger t
+   where %(classid)s::int8::oid = 'pg_class'::regclass::oid
+     and t.tgrelid = %(objid)s::int8::oid
+     and not t.tgisinternal
+), refs as (
+  select distinct d.refclassid, d.refobjid
+    from pg_depend d
+    join parts p on d.classid = p.classid and d.objid = p.objid
+   where d.deptype in ('n', 'a')
+)
+select n.nspname as schema,
+       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'
+                      else 'FOREIGN TABLE' end as type,
+       'pg_class'::regclass::oid as next_classid,
+       c.oid as next_objid
+  from refs
+  join pg_class c on refs.refclassid = 'pg_class'::regclass::oid
+                 and c.oid = refs.refobjid
+  join pg_namespace n on n.oid = c.relnamespace
+ where c.relkind in ('r', 'p', 'v', 'm', 'S', 'f')
+   and c.oid <> %(objid)s::int8::oid
+   and n.nspname not in ('pg_catalog', 'information_schema')
+union all
+select n.nspname,
+       p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')',
+       case p.prokind when 'p' then 'PROCEDURE' else 'FUNCTION' end,
+       'pg_proc'::regclass::oid,
+       p.oid
+  from refs
+  join pg_proc p on refs.refclassid = 'pg_proc'::regclass::oid
+                and p.oid = refs.refobjid
+  join pg_namespace n on n.oid = p.pronamespace
+ where p.oid <> %(objid)s::int8::oid
+   and n.nspname not in ('pg_catalog', 'information_schema')
+ order by 3, 2

pythia_postgres/queries/dependents-catalog.sql

@@ -0,0 +1,66 @@
+-- Purpose: what the catalog (pg_depend) records as depending on one object:
+--          views and materialized views through their rewrite rules,
+--          SQL-standard function bodies, triggers, constraints, column
+--          defaults and row-level policies. PL/pgSQL bodies are not here —
+--          dependents-text.sql looks for those.
+-- Binds:   %(classid)s the object's catalog (pg_class or pg_proc, as an oid)
+--          %(objid)s   the object's oid
+-- Returns: SCHEMA, NAME, TYPE, NEXT_CLASSID, NEXT_OBJID (NULL where the walk
+--          stops: nothing depends on a trigger or a constraint)
+with d as (
+  select distinct classid, objid
+    from pg_depend
+   where refclassid = %(classid)s::int8::oid
+     and refobjid = %(objid)s::int8::oid
+     and deptype in ('n', 'a')
+)
+select n.nspname as schema,
+       c.relname as name,
+       case c.relkind when 'm' then 'MATERIALIZED VIEW' else 'VIEW' end as type,
+       'pg_class'::regclass::oid as next_classid,
+       c.oid as next_objid
+  from d
+  join pg_rewrite r on d.classid = 'pg_rewrite'::regclass::oid and r.oid = d.objid
+  join pg_class c on c.oid = r.ev_class
+  join pg_namespace n on n.oid = c.relnamespace
+ where c.oid <> %(objid)s::int8::oid
+union all
+select n.nspname,
+       p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')',
+       case p.prokind when 'p' then 'PROCEDURE' else 'FUNCTION' end,
+       'pg_proc'::regclass::oid,
+       p.oid
+  from d
+  join pg_proc p on d.classid = 'pg_proc'::regclass::oid and p.oid = d.objid
+  join pg_namespace n on n.oid = p.pronamespace
+union all
+select n.nspname, t.tgname || ' on ' || c.relname, 'TRIGGER', null, null
+  from d
+  join pg_trigger t on d.classid = 'pg_trigger'::regclass::oid and t.oid = d.objid
+  join pg_class c on c.oid = t.tgrelid
+  join pg_namespace n on n.oid = c.relnamespace
+ where not t.tgisinternal
+union all
+select n.nspname, c.relname, 'TABLE (CONSTRAINT ' || k.conname || ')', null, null
+  from d
+  join pg_constraint k on d.classid = 'pg_constraint'::regclass::oid
+                      and k.oid = d.objid
+  join pg_class c on c.oid = k.conrelid
+  join pg_namespace n on n.oid = c.relnamespace
+ where k.conrelid <> %(objid)s::int8::oid
+union all
+select n.nspname, c.relname, 'TABLE (DEFAULT ' || a.attname || ')', null, null
+  from d
+  join pg_attrdef ad on d.classid = 'pg_attrdef'::regclass::oid and ad.oid = d.objid
+  join pg_class c on c.oid = ad.adrelid
+  join pg_attribute a on a.attrelid = ad.adrelid and a.attnum = ad.adnum
+  join pg_namespace n on n.oid = c.relnamespace
+ where c.oid <> %(objid)s::int8::oid
+union all
+select n.nspname, pol.polname || ' on ' || c.relname, 'POLICY', null, null
+  from d
+  join pg_policy pol on d.classid = 'pg_policy'::regclass::oid and pol.oid = d.objid
+  join pg_class c on c.oid = pol.polrelid
+  join pg_namespace n on n.oid = c.relnamespace
+ where c.oid <> %(objid)s::int8::oid
+ order by 3, 2

pythia_postgres/queries/dependents-text.sql

@@ -0,0 +1,22 @@
+-- Purpose: functions whose source text holds a name as a whole word, any
+--          case — the references pg_depend does not record (PL/pgSQL
+--          bodies, SQL functions with a string body). A match is a lead, not
+--          a proof: a column or a variable can share the name.
+-- Binds:   %(pattern)s the name as a whole-word regular expression, escaped
+--                      by the engine
+--          %(objid)s   the object itself, left out
+-- Returns: SCHEMA, NAME, TYPE, NEXT_CLASSID, NEXT_OBJID
+select n.nspname as schema,
+       p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')' as name,
+       case p.prokind when 'p' then 'PROCEDURE' else 'FUNCTION' end as type,
+       'pg_proc'::regclass::oid as next_classid,
+       p.oid as next_objid
+  from pg_proc p
+  join pg_namespace n on n.oid = p.pronamespace
+  join pg_language l on l.oid = p.prolang
+ where l.lanname in ('plpgsql', 'sql')
+   and n.nspname not in ('pg_catalog', 'information_schema')
+   and n.nspname not like 'pg\_%%'
+   and p.oid <> %(objid)s::int8::oid
+   and p.prosrc ~* %(pattern)s
+ order by 1, 2

pythia_postgres/queries/function-body.sql

@@ -0,0 +1,8 @@
+-- Purpose: a function's language and its source as stored — the text the
+--          engine reads for references pg_depend does not record
+-- Binds:   %(objid)s the function's oid
+-- Returns: LANGUAGE, BODY
+select l.lanname as language, p.prosrc as body
+  from pg_proc p
+  join pg_language l on l.oid = p.prolang
+ where p.oid = %(objid)s::int8::oid

pythia_postgres/queries/grep.sql

@@ -0,0 +1,30 @@
+-- Purpose: every function, procedure or view in a schema whose source holds
+--          a text, any case, with that source as PostgreSQL prints it back
+--          (the engine picks out the lines, numbered as `src` numbers them)
+-- Binds:   %(s)s schema, %(t)s the text
+-- Returns: UNIT, TYPE, DEFINITION
+select unit, type, definition
+  from (select p.proname || '(' || pg_get_function_identity_arguments(p.oid)
+               || ')' as unit,
+               case p.prokind when 'p' then 'PROCEDURE' else 'FUNCTION' end
+                 as type,
+               pg_get_functiondef(p.oid) as definition
+          from pg_proc p
+          join pg_namespace n on n.oid = p.pronamespace
+         where n.nspname = %(s)s
+           and p.prokind in ('f', 'p', 'w')
+        union all
+        select c.relname,
+               case c.relkind when 'v' then 'VIEW' else 'MATERIALIZED VIEW' end,
+               -- the same text source.sql prints, so line numbers agree
+               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)
+          from pg_class c
+          join pg_namespace n on n.oid = c.relnamespace
+         where n.nspname = %(s)s
+           and c.relkind in ('v', 'm')) g
+ where strpos(lower(definition), lower(%(t)s)) > 0
+ order by type, unit

pythia_postgres/queries/name-candidates.sql

@@ -0,0 +1,32 @@
+-- Purpose: every relation and function outside the system schemas, by bare
+--          name — what a word in a function body could be referring to
+-- Binds:   none
+-- Returns: BARE_NAME, SCHEMA, NAME, TYPE, NEXT_CLASSID, NEXT_OBJID
+select c.relname as bare_name,
+       n.nspname as schema,
+       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'
+                      else 'FOREIGN TABLE' end as type,
+       'pg_class'::regclass::oid as next_classid,
+       c.oid as next_objid
+  from pg_class c
+  join pg_namespace n on n.oid = c.relnamespace
+ where c.relkind in ('r', 'p', 'v', 'm', 'S', 'f')
+   and n.nspname not in ('pg_catalog', 'information_schema')
+   and n.nspname not like 'pg\_%%'
+union all
+select p.proname,
+       n.nspname,
+       p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')',
+       case p.prokind when 'p' then 'PROCEDURE' else 'FUNCTION' end,
+       'pg_proc'::regclass::oid,
+       p.oid
+  from pg_proc p
+  join pg_namespace n on n.oid = p.pronamespace
+ where p.prokind in ('f', 'p', 'w')
+   and n.nspname not in ('pg_catalog', 'information_schema')
+   and n.nspname not like 'pg\_%%'