pgdevkit 0.1.0__py3-none-any.whl

pgdevkit/diff.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+import sqlglot
+import sqlglot.expressions as exp
+
+from .models import DatabaseSchema, FunctionDef, IndexDef, TableDef
+
+
+class DiffKind(str, Enum):
+    MISSING_IN_DB = "missing_in_db"
+    MISSING_IN_SCRIPTS = "missing_in_scripts"
+    MISMATCH = "mismatch"
+
+
+@dataclass
+class DiffEntry:
+    kind: DiffKind
+    object_type: str
+    object_name: str
+    detail: str = ""
+
+
+def compute_diff(scripts: DatabaseSchema, db: DatabaseSchema, report_extra_db: bool = False) -> list[DiffEntry]:
+    diffs: list[DiffEntry] = []
+
+    _diff_set("schema", scripts.schemas, db.schemas, diffs, report_extra_db)
+
+    tables_missing_in_db: set[str] = set()
+    tables_missing_in_scripts: set[str] = set()
+
+    for name, obj in scripts.tables.items():
+        if name not in db.tables:
+            tables_missing_in_db.add(name)
+            diffs.append(DiffEntry(DiffKind.MISSING_IN_DB, "table", name))
+        else:
+            _diff_table(name, obj, db.tables[name], diffs)
+    if report_extra_db:
+        for name in db.tables:
+            if name not in scripts.tables:
+                tables_missing_in_scripts.add(name)
+                diffs.append(DiffEntry(DiffKind.MISSING_IN_SCRIPTS, "table", name))
+
+    for name, obj in scripts.views.items():
+        if name not in db.views:
+            diffs.append(DiffEntry(DiffKind.MISSING_IN_DB, "view", name))
+        else:
+            s = _norm_sql(obj.definition)
+            d = _norm_sql(db.views[name].definition)
+            if s != d:
+                diffs.append(DiffEntry(DiffKind.MISMATCH, "view", name, "definition differs"))
+    if report_extra_db:
+        for name in db.views:
+            if name not in scripts.views:
+                diffs.append(DiffEntry(DiffKind.MISSING_IN_SCRIPTS, "view", name))
+
+    for name, obj in scripts.functions.items():
+        if name not in db.functions:
+            diffs.append(DiffEntry(DiffKind.MISSING_IN_DB, "function", name))
+        else:
+            _diff_function(name, obj, db.functions[name], diffs)
+    if report_extra_db:
+        for name in db.functions:
+            if name not in scripts.functions:
+                diffs.append(DiffEntry(DiffKind.MISSING_IN_SCRIPTS, "function", name))
+
+    for name, obj in scripts.enums.items():
+        if name not in db.enums:
+            diffs.append(DiffEntry(DiffKind.MISSING_IN_DB, "enum", name))
+        elif obj.values != db.enums[name].values:
+            diffs.append(DiffEntry(DiffKind.MISMATCH, "enum", name, f"values: {obj.values} vs {db.enums[name].values}"))
+    if report_extra_db:
+        for name in db.enums:
+            if name not in scripts.enums:
+                diffs.append(DiffEntry(DiffKind.MISSING_IN_SCRIPTS, "enum", name))
+
+    for name, obj in scripts.composites.items():
+        if name not in db.composites:
+            diffs.append(DiffEntry(DiffKind.MISSING_IN_DB, "composite_type", name))
+        elif obj.fields != db.composites[name].fields:
+            diffs.append(DiffEntry(DiffKind.MISMATCH, "composite_type", name, "fields differ"))
+    if report_extra_db:
+        for name in db.composites:
+            if name not in scripts.composites:
+                diffs.append(DiffEntry(DiffKind.MISSING_IN_SCRIPTS, "composite_type", name))
+
+    for name, obj in scripts.indexes.items():
+        if name not in db.indexes:
+            if f"{obj.schema}.{obj.table}" not in tables_missing_in_db:
+                diffs.append(DiffEntry(DiffKind.MISSING_IN_DB, "index", name))
+        else:
+            _diff_index(name, obj, db.indexes[name], diffs)
+    if report_extra_db:
+        for name, obj in db.indexes.items():
+            if name not in scripts.indexes:
+                if f"{obj.schema}.{obj.table}" not in tables_missing_in_scripts:
+                    diffs.append(DiffEntry(DiffKind.MISSING_IN_SCRIPTS, "index", name))
+
+    return diffs
+
+
+def _diff_set(obj_type: str, scripts_set: set, db_set: set, diffs: list[DiffEntry], report_extra: bool) -> None:
+    for item in scripts_set:
+        if item not in db_set:
+            diffs.append(DiffEntry(DiffKind.MISSING_IN_DB, obj_type, item))
+    if report_extra:
+        for item in db_set:
+            if item not in scripts_set:
+                diffs.append(DiffEntry(DiffKind.MISSING_IN_SCRIPTS, obj_type, item))
+
+
+def _diff_table(name: str, s: TableDef, d: TableDef, diffs: list[DiffEntry]) -> None:
+    if s.is_partition or d.is_partition:
+        return
+
+    scols = {c.name: c for c in s.columns}
+    dcols = {c.name: c for c in d.columns}
+    for cname, sc in scols.items():
+        if cname not in dcols:
+            diffs.append(DiffEntry(DiffKind.MISSING_IN_DB, "column", f"{name}.{cname}"))
+        else:
+            dc = dcols[cname]
+            issues = []
+            if _norm_type(sc.data_type) != _norm_type(dc.data_type):
+                issues.append(f"type: {sc.data_type!r} vs {dc.data_type!r}")
+            if sc.is_nullable != dc.is_nullable:
+                issues.append(f"nullable: {sc.is_nullable} vs {dc.is_nullable}")
+            if issues:
+                diffs.append(DiffEntry(DiffKind.MISMATCH, "column", f"{name}.{cname}", "; ".join(issues)))
+    for cname in dcols:
+        if cname not in scols:
+            diffs.append(DiffEntry(DiffKind.MISSING_IN_SCRIPTS, "column", f"{name}.{cname}"))
+
+
+def _diff_function(name: str, s: FunctionDef, d: FunctionDef, diffs: list[DiffEntry]) -> None:
+    issues = []
+    if _norm_type(s.return_type) != _norm_type(d.return_type):
+        issues.append(f"return_type: {s.return_type!r} vs {d.return_type!r}")
+    if _norm_body(s.body) != _norm_body(d.body):
+        issues.append("body differs")
+    if issues:
+        diffs.append(DiffEntry(DiffKind.MISMATCH, "function", name, "; ".join(issues)))
+
+
+def _diff_index(name: str, s: IndexDef, d: IndexDef, diffs: list[DiffEntry]) -> None:
+    s_info = _parse_index_def(s.definition)
+    d_info = _parse_index_def(d.definition)
+
+    if s_info is None or d_info is None:
+        if _norm_sql(s.definition) != _norm_sql(d.definition):
+            diffs.append(DiffEntry(DiffKind.MISMATCH, "index", name, "definition differs"))
+        return
+
+    issues = []
+    if s_info["unique"] != d_info["unique"]:
+        issues.append(f"unique: {s_info['unique']} vs {d_info['unique']}")
+    if s_info["using"] != d_info["using"]:
+        issues.append(f"using: {s_info['using']} vs {d_info['using']}")
+    if s_info["columns"] != d_info["columns"]:
+        issues.append(f"columns: ({', '.join(s_info['columns'])}) vs ({', '.join(d_info['columns'])})")
+    if s_info["where_ast"] != d_info["where_ast"]:
+        issues.append(f"where: {s_info['where_display']!r} vs {d_info['where_display']!r}")
+
+    if issues:
+        diffs.append(DiffEntry(DiffKind.MISMATCH, "index", name, "; ".join(issues)))
+
+
+def _parse_index_def(definition: str) -> dict | None:
+    try:
+        parsed = sqlglot.parse_one(definition, dialect="postgres")
+    except Exception:
+        return None
+    if not isinstance(parsed, exp.Create):
+        return None
+    index_node = parsed.this
+    if not isinstance(index_node, exp.Index):
+        return None
+
+    params = index_node.args.get("params")
+    using_node = params.args.get("using") if params else None
+    using = using_node.name.lower() if using_node else "btree"
+
+    columns = []
+    for col in (params.args.get("columns") if params else None) or []:
+        columns.append(_norm_sql(col.sql(dialect="postgres")))
+
+    where_node = params.args.get("where") if params else None
+    where_ast = _unwrap_paren(where_node.this) if where_node else None
+    where_display = _norm_sql(where_node.this.sql(dialect="postgres")) if where_node else None
+
+    return {
+        "unique": bool(parsed.args.get("unique")),
+        "using": using,
+        "columns": columns,
+        "where_ast": where_ast,
+        "where_display": where_display,
+    }
+
+
+def _unwrap_paren(node):
+    return node.transform(lambda n: n.this if isinstance(n, exp.Paren) else n)
+
+
+def _norm_sql(s: str) -> str:
+    # Postgres's pg_get_viewdef()/pg_get_indexdef() always append a trailing
+    # ";", while sqlglot's Expression.sql() rendering never does; strip it so
+    # semantically-identical definitions compare equal.
+    return " ".join(s.lower().split()).rstrip(";")
+
+
+def _norm_body(s: str) -> str:
+    lines = [l.strip() for l in s.splitlines()]
+    return "\n".join(l.lower() for l in lines if l)
+
+
+_TYPE_SYNONYMS = {
+    "int": "integer", "int4": "integer",
+    "int2": "smallint",
+    "int8": "bigint",
+    "float4": "real",
+    "float8": "double precision",
+    "bool": "boolean",
+    "decimal": "numeric",
+    "varchar": "character varying",
+    "char": "character", "bpchar": "character",
+    "timestamptz": "timestamp with time zone",
+    "timestamp": "timestamp without time zone",
+    "timetz": "time with time zone",
+    "time": "time without time zone",
+    "varbit": "bit varying",
+    "serial": "integer", "serial4": "integer",
+    "smallserial": "smallint", "serial2": "smallint",
+    "bigserial": "bigint", "serial8": "bigint",
+}
+
+
+def _norm_type(t: str) -> str:
+    s = " ".join(t.lower().split())
+
+    array_suffix = ""
+    while s.endswith("[]"):
+        array_suffix += "[]"
+        s = s[:-2].strip()
+
+    match = re.search(r"\(([^)]*)\)", s)
+    params = f"({match.group(1)})" if match else ""
+    base = (s[: match.start()] + s[match.end() :]).strip() if match else s
+    base = " ".join(base.split())
+
+    base = _TYPE_SYNONYMS.get(base, base)
+    return f"{base}{params}{array_suffix}"

pgdevkit/docs/database-layout.md

@@ -0,0 +1,145 @@
+# `database/` folder layout
+
+The Postgres schema is versioned as plain `.sql` files under a `database/`
+folder in the repo — that folder *is* the source of truth for the schema.
+`pgdb testdb` (see [`pgdevkit/testdb/schema.py`](../pgdevkit/testdb/schema.py))
+applies it to a local test database; a human applies the same files to
+production.
+
+This is the single source for the convention — don't duplicate this table or
+these rules elsewhere; link here instead.
+
+---
+
+## Layer directories
+
+Top-level directories group tables/objects by conceptual layer — one
+directory per Postgres schema, or per logical grouping within one schema.
+Names and count are entirely per-project; a generic example:
+
+```
+database/
+├── schema.sql            # CREATE SCHEMA statements
+├── 0_public/              # shared types/functions usable from anywhere
+├── 1_reference_data/      # dimension / reference tables
+├── 2_transactional/       # fact / transactional tables
+├── 3_app/                 # user-editable, app-owned tables
+├── 4_reporting/           # aggregated / statistics tables
+├── permissions.sql        # grants
+```
+
+The leading number is a **display/sort aid only** — it groups related
+folders together in a file listing so a human can scan them top-to-bottom in
+a sensible order. It does not control apply order: `pgdb testdb` applies
+files by object-type priority (below) and resolves cross-file dependencies
+itself, regardless of which numbered folder a file sits in. Feel free to
+renumber layers for readability without worrying about breaking anything.
+
+---
+
+## Object-type subfolders, in apply order
+
+Within a layer directory, group files by object type. This is what actually
+controls apply order, across all layer directories — cross-file dependencies
+between objects of the same type (e.g. one view selecting from another) are
+resolved automatically; this table only fixes the order *between* types.
+This table must match `_TYPE_ORDER` / `_SCHEMA_QUALIFIED_TYPES` in
+[`pgdevkit/testdb/schema.py`](../pgdevkit/testdb/schema.py) exactly — update
+both together.
+
+| Priority | Directory | Object type |
+|---|---|---|
+| 1 | `schema` | `CREATE SCHEMA` |
+| 2 | `types` | Custom types / enums |
+| 3 | `tables` | Tables |
+| 4 | `scalar_functions` | Scalar functions |
+| 5 | `functions` | Functions |
+| 6 | `views` | Views |
+| 7 | `table_functions` | Table functions |
+| 8 | `procedures` | Procedures |
+| 100 | `permissions` | Grants |
+| 101 | `indexes` | Indexes |
+
+One object per file: `tables/user.sql`, `views/all_edits.sql`,
+`types/measurement_unit.sql`.
+
+---
+
+## File-naming conventions
+
+| Suffix | Meaning |
+|---|---|
+| `<name>.sql` | The object's live definition (`CREATE TABLE`, `CREATE OR REPLACE VIEW`, ...) |
+| `<name>.test_data.json` | Seed rows for a table — a JSON array of row objects, loaded after the table is created |
+| `<name>.init.sql` | One-time setup for an object (e.g. a backfill), run once, kept separate from the reusable definition |
+| `<name>.prod.sql` / `.prod` anywhere in the name | Production-only (real permission grants, real user accounts) — skipped by `pgdb testdb` |
+| `all.sql` | Generated concatenation of the whole tree — not hand-edited, not committed |
+
+---
+
+## Migrations
+
+One-off, non-idempotent changes (rename/drop column, backfill, data fix) go
+in a `migrations/` (or `_migration_scripts/`) folder — one file per change,
+named by date:
+
+```
+database/migrations/2026-07-10_customer_geocode.sql
+```
+
+Rules:
+
+- Skipped by `pgdb testdb` — it only applies the layer directories above.
+- Update the corresponding table/view `.sql` file in the same change so its
+  definition already reflects the new shape — the migration and the
+  source-of-truth file must never drift apart.
+- Applied to production manually, once, by a human, after being verified
+  locally.
+- Never edited after being applied — a further change gets a new dated file.
+
+---
+
+## `COMMENT ON` — document schema in the object's own file
+
+Add a `COMMENT ON` for every table, and for any column whose purpose isn't
+obvious from its name and type (flags, status codes, denormalized fields,
+units). Put it directly in the table's `.sql` file, right after the
+`CREATE TABLE` — not in a migration, wiki, or README. It lives with the
+definition it describes and survives `\d+` / `pg_catalog` inspection.
+
+```sql
+-- database/1_reference_data/tables/user.sql
+create table dim.user (
+    id bigint generated always as identity primary key,
+    email text not null,
+    is_active boolean not null default true
+);
+
+comment on table dim.user is 'End-user accounts; one row per registered person.';
+comment on column dim.user.is_active is 'False once a user is soft-deleted; keep for audit trail.';
+```
+
+---
+
+## Backfilling untracked objects
+
+If a table, scalar function, or table function was created directly on the
+database and never got a `.sql` file, use `pgdb fetch-missing` to find it and
+generate one — see `pgdb fetch-missing --help`. It connects to Postgres,
+diffs the live schema against what's already tracked under `database/`, and
+for each object you select, reverse-engineers its DDL into the matching
+layer folder's `tables/`, `views/`, `scalar_functions/`, or
+`table_functions/` subfolder. The layer folder is matched by schema name
+against the existing top-level directories under `database/`, ignoring their
+leading sort number.
+
+---
+
+## Quick checklist
+
+- [ ] New table/view/function/type gets its own `.sql` file under the right layer + object-type folder
+- [ ] Object-type folder (`tables`, `views`, ...) matches the apply-order table above — that's what governs ordering, not the layer's leading number
+- [ ] One-off changes go in `migrations/`, dated, never edited after applying
+- [ ] The live `.sql` file is updated in the same change as any migration touching that object
+- [ ] `.prod` files are production-only and skipped by `pgdb testdb`
+- [ ] Every table (and non-obvious column) has a `COMMENT ON`, placed in the object's own `.sql` file

pgdevkit/fetch_missing.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import psycopg
+
+from .diff import DiffKind, compute_diff
+from .introspect import introspect_db
+from .parser import parse_directory
+
+_LAYER_PREFIX_RE = re.compile(r"^\d+_?")
+
+# Matches the `tables`/`views`/`scalar_functions`/`table_functions` object-type
+# subfolders documented in docs/database-layout.md.
+SUBFOLDER = {
+    "table": "tables",
+    "view": "views",
+    "scalar_function": "scalar_functions",
+    "table_function": "table_functions",
+}
+
+
+@dataclass
+class MissingObject:
+    object_type: str  # "table" | "view" | "scalar_function" | "table_function"
+    schema: str
+    name: str
+
+    @property
+    def qualified_name(self) -> str:
+        return f"{self.schema}.{self.name}"
+
+
+def layer_folder_for(scripts_dir: Path, schema: str) -> Path:
+    """Map a schema name to its existing layer directory under scripts_dir,
+    matched by stripping each top-level folder's leading sort number (e.g.
+    "1_reference_data" -> "reference_data"). Falls back to scripts_dir/schema
+    if no existing folder matches."""
+    if scripts_dir.is_dir():
+        for entry in scripts_dir.iterdir():
+            if not entry.is_dir() or entry.name in ("migrations", "_migration_scripts"):
+                continue
+            if _LAYER_PREFIX_RE.sub("", entry.name).lower() == schema.lower():
+                return entry
+    return scripts_dir / schema
+
+
+def find_missing_objects(scripts_dir: Path, conninfo: str) -> list[MissingObject]:
+    """Tables, views, and functions that exist in the live database but
+    aren't tracked as .sql files under scripts_dir."""
+    scripts = parse_directory(scripts_dir)
+    db = introspect_db(conninfo)
+    diffs = compute_diff(scripts, db, report_extra_db=True)
+
+    missing: list[MissingObject] = []
+    with psycopg.connect(conninfo) as conn:
+        for d in diffs:
+            if d.kind != DiffKind.MISSING_IN_SCRIPTS or d.object_type not in ("table", "view", "function"):
+                continue
+            schema, name = d.object_name.split(".", 1)
+            object_type = d.object_type
+            if object_type == "function":
+                object_type = "table_function" if _returns_set(conn, schema, name) else "scalar_function"
+            missing.append(MissingObject(object_type, schema, name))
+    return missing
+
+
+def _returns_set(conn: Any, schema: str, name: str) -> bool:
+    with conn.cursor() as cur:
+        cur.execute(
+            """
+            SELECT p.proretset
+            FROM pg_catalog.pg_proc p
+            JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+            WHERE n.nspname = %s AND p.proname = %s AND p.prokind = 'f'
+            ORDER BY p.oid LIMIT 1
+            """,
+            (schema, name),
+        )
+        row = cur.fetchone()
+        return bool(row and row[0])
+
+
+def reconstruct_ddl(conn: Any, obj: MissingObject) -> str:
+    """Reverse-engineer the DDL for a missing object from pg_catalog."""
+    if obj.object_type == "table":
+        return _table_ddl(conn, obj.schema, obj.name)
+    if obj.object_type == "view":
+        return _view_ddl(conn, obj.schema, obj.name)
+    return _function_ddl(conn, obj.schema, obj.name)
+
+
+def _table_ddl(conn: Any, schema: str, table: str) -> str:
+    with conn.cursor() as cur:
+        cur.execute(
+            """
+            SELECT c.oid
+            FROM pg_catalog.pg_class c
+            JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+            WHERE n.nspname = %s AND c.relname = %s AND c.relkind = 'r'
+            """,
+            (schema, table),
+        )
+        row = cur.fetchone()
+        if not row:
+            raise ValueError(f"Table {schema}.{table} not found in pg_catalog")
+        oid = row[0]
+
+        cur.execute(
+            """
+            SELECT
+                a.attname,
+                pg_catalog.format_type(a.atttypid, a.atttypmod),
+                a.attnotnull,
+                a.attidentity,
+                a.attgenerated,
+                CASE
+                    WHEN a.attidentity = 'a' THEN 'GENERATED ALWAYS AS IDENTITY'
+                    WHEN a.attidentity = 'd' THEN 'GENERATED BY DEFAULT AS IDENTITY'
+                    WHEN a.attgenerated = 's' THEN
+                        'GENERATED ALWAYS AS (' || pg_catalog.pg_get_expr(ad.adbin, ad.adrelid) || ') STORED'
+                    WHEN ad.adbin IS NOT NULL THEN
+                        'DEFAULT ' || pg_catalog.pg_get_expr(ad.adbin, ad.adrelid)
+                    ELSE NULL
+                END
+            FROM pg_catalog.pg_attribute a
+            LEFT JOIN pg_catalog.pg_attrdef ad
+                ON ad.adrelid = a.attrelid AND ad.adnum = a.attnum
+            WHERE a.attrelid = %s AND a.attnum > 0 AND NOT a.attisdropped
+            ORDER BY a.attnum
+            """,
+            (oid,),
+        )
+        columns = cur.fetchall()
+
+        cur.execute(
+            """
+            SELECT conname, pg_catalog.pg_get_constraintdef(oid, true)
+            FROM pg_catalog.pg_constraint
+            WHERE conrelid = %s
+            ORDER BY contype, conname
+            """,
+            (oid,),
+        )
+        constraints = cur.fetchall()
+
+        cur.execute(
+            """
+            SELECT indexname, indexdef
+            FROM pg_indexes
+            WHERE schemaname = %s AND tablename = %s
+              AND indexname NOT IN (
+                  SELECT conname FROM pg_catalog.pg_constraint WHERE conrelid = %s
+              )
+            ORDER BY indexname
+            """,
+            (schema, table, oid),
+        )
+        indexes = cur.fetchall()
+
+    col_defs: list[str] = []
+    for attname, data_type, not_null, identity, _generated, extra in columns:
+        col_def = f"{attname} {data_type}"
+        if not_null and not identity:
+            col_def += " NOT NULL"
+        if extra:
+            col_def += f" {extra}"
+        col_defs.append(col_def)
+
+    for conname, condef in constraints:
+        col_defs.append(f"CONSTRAINT {conname} {condef}")
+
+    ddl = f"CREATE TABLE IF NOT EXISTS {schema}.{table} (\n"
+    ddl += ",\n".join(f"    {c}" for c in col_defs)
+    ddl += "\n);\n"
+
+    for _, indexdef in indexes:
+        indexdef = re.sub(r"^CREATE INDEX\b", "CREATE INDEX IF NOT EXISTS", indexdef)
+        indexdef = re.sub(r"^CREATE UNIQUE INDEX\b", "CREATE UNIQUE INDEX IF NOT EXISTS", indexdef)
+        ddl += f"\n{indexdef};\n"
+
+    return ddl
+
+
+def _view_ddl(conn: Any, schema: str, name: str) -> str:
+    with conn.cursor() as cur:
+        cur.execute(
+            """
+            SELECT pg_get_viewdef(c.oid, true)
+            FROM pg_catalog.pg_class c
+            JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+            WHERE n.nspname = %s AND c.relname = %s AND c.relkind = 'v'
+            """,
+            (schema, name),
+        )
+        row = cur.fetchone()
+        if not row or row[0] is None:
+            raise ValueError(f"View {schema}.{name} not found in pg_catalog")
+        return f"CREATE OR REPLACE VIEW {schema}.{name} AS\n{row[0].rstrip()};\n"
+
+
+def _function_ddl(conn: Any, schema: str, name: str) -> str:
+    """Fetch a function's DDL via pg_get_functiondef.
+
+    If the function is overloaded, this uses the lowest-oid (oldest) match —
+    good enough to seed a file; resolve manually if there's more than one."""
+    with conn.cursor() as cur:
+        cur.execute(
+            """
+            SELECT p.oid
+            FROM pg_catalog.pg_proc p
+            JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+            WHERE n.nspname = %s AND p.proname = %s AND p.prokind = 'f'
+            ORDER BY p.oid LIMIT 1
+            """,
+            (schema, name),
+        )
+        row = cur.fetchone()
+        if not row:
+            raise ValueError(f"Function {schema}.{name} not found in pg_catalog")
+
+        cur.execute("SELECT pg_catalog.pg_get_functiondef(%s)", (row[0],))
+        ddl_row = cur.fetchone()
+        if not ddl_row or ddl_row[0] is None:
+            raise ValueError(f"Could not reconstruct DDL for function {schema}.{name}")
+        return ddl_row[0].rstrip() + ";\n"