pgdevkit 0.1.0__py3-none-any.whl

pgdevkit/parser.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import re
+import logging
+from pathlib import Path
+
+import sqlglot
+import sqlglot.expressions as exp
+
+from .models import (
+    ColumnDef, ConstraintDef, CompositeTypeDef, DatabaseSchema,
+    EnumDef, FunctionDef, IndexDef, TableDef, ViewDef,
+)
+
+logger = logging.getLogger(__name__)
+
+# Regex to extract dollar-quoted body
+_DOLLAR_BODY = re.compile(r'\$(\w*)\$(.*?)\$\1\$', re.DOTALL | re.IGNORECASE)
+
+# Regex for CREATE TYPE AS ENUM inside DO blocks
+_DO_ENUM = re.compile(
+    r'CREATE\s+TYPE\s+(\w+(?:\.\w+)?)\s+AS\s+ENUM\s*\(([^)]+)\)',
+    re.IGNORECASE | re.DOTALL,
+)
+
+# Regex for CREATE TYPE AS composite inside DO blocks
+_DO_COMPOSITE = re.compile(
+    r'CREATE\s+TYPE\s+(\w+(?:\.\w+)?)\s+AS\s*\(([^)]+)\)',
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+def parse_directory(scripts_dir: Path) -> DatabaseSchema:
+    db_schema = DatabaseSchema()
+    for sql_file in sorted(scripts_dir.rglob("*.sql")):
+        _parse_file(sql_file, db_schema)
+    return db_schema
+
+
+def _parse_file(path: Path, db_schema: DatabaseSchema) -> None:
+    content = path.read_text(encoding="utf-8")
+    try:
+        exprs = sqlglot.parse(content, dialect="postgres", error_level=sqlglot.ErrorLevel.WARN)
+    except Exception as e:
+        logger.warning("sqlglot failed on %s: %s", path.name, e)
+        exprs = []
+
+    for expr in exprs:
+        if expr is None:
+            continue
+        try:
+            _handle_expr(expr, content, db_schema)
+        except Exception as e:
+            logger.debug("Skipping expression in %s: %s", path.name, e)
+
+    _extract_do_block_objects(content, db_schema)
+
+
+def _handle_expr(expr: exp.Expression, raw: str, db_schema: DatabaseSchema) -> None:
+    if not isinstance(expr, exp.Create):
+        return
+    kind = (expr.args.get("kind") or "").upper()
+    if kind == "TABLE":
+        _handle_table(expr, db_schema)
+    elif kind == "VIEW":
+        _handle_view(expr, db_schema)
+    elif kind in ("FUNCTION", "PROCEDURE"):
+        _handle_function(expr, raw, db_schema, kind.lower())
+    elif kind == "TYPE":
+        _handle_type(expr, db_schema)
+    elif kind == "SCHEMA":
+        _handle_schema_create(expr, db_schema)
+    elif kind == "INDEX":
+        _handle_index(expr, db_schema)
+
+
+def _resolve_name(expr: exp.Create) -> tuple[str, str] | None:
+    """Return (schema, name) from a CREATE expression."""
+    this = expr.this
+    if isinstance(this, exp.Schema):
+        table_node = this.this
+    else:
+        table_node = this
+
+    if isinstance(table_node, exp.Table):
+        db_node = table_node.args.get("db")
+        schema = db_node.name if db_node else "public"
+        return schema, table_node.name
+    return None
+
+
+def _handle_table(expr: exp.Create, db_schema: DatabaseSchema) -> None:
+    result = _resolve_name(expr)
+    if not result:
+        return
+    tschema, tname = result
+    properties = expr.args.get("properties")
+    is_partition = any(
+        isinstance(p, exp.PartitionedOfProperty) for p in (properties.expressions if properties else [])
+    )
+    table = TableDef(schema=tschema, name=tname, is_partition=is_partition)
+
+    this = expr.this
+    items = this.expressions if isinstance(this, exp.Schema) else []
+
+    pk_columns: set[str] = set()
+    for item in items:
+        if isinstance(item, exp.ColumnDef):
+            col = _parse_column_def(item)
+            if col:
+                table.columns.append(col)
+        else:
+            constr = _parse_table_constraint(item)
+            if constr:
+                table.constraints.append(constr)
+            pk_columns |= _extract_primary_key_columns(item)
+
+    for col in table.columns:
+        if col.name in pk_columns:
+            col.is_nullable = False
+
+    db_schema.tables[table.qualified_name] = table
+
+
+def _extract_primary_key_columns(item: exp.Expression) -> set[str]:
+    inner = item
+    if isinstance(item, exp.Constraint):
+        inner = item.args.get("kind") or (item.expressions[0] if item.expressions else None)
+    if isinstance(inner, exp.PrimaryKey):
+        return {e.name for e in inner.expressions if hasattr(e, "name")}
+    return set()
+
+
+def _parse_column_def(col: exp.ColumnDef) -> ColumnDef | None:
+    name = col.name
+    if not name or col.kind is None:
+        return None
+    data_type = col.kind.sql(dialect="postgres").lower()
+    is_serial = col.kind.this in (
+        exp.DataType.Type.SERIAL, exp.DataType.Type.SMALLSERIAL, exp.DataType.Type.BIGSERIAL,
+    )
+    is_nullable = not is_serial
+    default = None
+    is_generated = False
+
+    for c in col.constraints:
+        ck = c.kind
+        if isinstance(ck, (exp.NotNullColumnConstraint, exp.PrimaryKeyColumnConstraint)):
+            is_nullable = False
+        elif isinstance(ck, exp.DefaultColumnConstraint):
+            default = ck.this.sql(dialect="postgres") if ck.this else None
+        elif isinstance(ck, exp.GeneratedAsIdentityColumnConstraint):
+            is_generated = True
+            is_nullable = False
+        elif isinstance(ck, exp.ComputedColumnConstraint):
+            is_generated = True
+
+    return ColumnDef(name=name, data_type=data_type, is_nullable=is_nullable, default=default, is_generated=is_generated)
+
+
+def _parse_table_constraint(item: exp.Expression) -> ConstraintDef | None:
+    name = None
+    kind = "UNKNOWN"
+
+    if isinstance(item, exp.Constraint):
+        name = item.name or None
+        inner = item.args.get("kind") or (item.expressions[0] if item.expressions else None)
+    else:
+        inner = item
+
+    if isinstance(inner, exp.PrimaryKey):
+        kind = "PRIMARY KEY"
+    elif isinstance(inner, exp.UniqueColumnConstraint):
+        kind = "UNIQUE"
+    elif isinstance(inner, exp.ForeignKey):
+        kind = "FOREIGN KEY"
+    elif isinstance(inner, exp.Check):
+        kind = "CHECK"
+    else:
+        return None
+
+    definition = item.sql(dialect="postgres").lower()
+    return ConstraintDef(name=name, kind=kind, definition=definition)
+
+
+def _handle_view(expr: exp.Create, db_schema: DatabaseSchema) -> None:
+    result = _resolve_name(expr)
+    if not result:
+        return
+    vschema, vname = result
+    query = expr.expression
+    definition = query.sql(dialect="postgres").lower() if query else ""
+    view = ViewDef(schema=vschema, name=vname, definition=definition)
+    db_schema.views[view.qualified_name] = view
+
+
+def _handle_function(expr: exp.Create, raw: str, db_schema: DatabaseSchema, kind: str) -> None:
+    # Get name/schema from sqlglot
+    func_node = expr.this
+    fname = func_node.name if hasattr(func_node, "name") else ""
+    if fname:
+        db_node = func_node.args.get("db") if hasattr(func_node, "args") else None
+        fschema = db_node.name if db_node else "public"
+    else:
+        # sqlglot (30.11.0) parses "CREATE FUNCTION myapp.greet(...)" as a
+        # UserDefinedFunction wrapping a Table (this=Identifier(greet),
+        # db=Identifier(myapp)). UserDefinedFunction.name doesn't unwrap
+        # that nested Table, so pull the name/schema from it directly.
+        inner = func_node.this if hasattr(func_node, "this") else None
+        if isinstance(inner, exp.Table) and inner.name:
+            fname = inner.name
+            db_node = inner.args.get("db")
+            fschema = db_node.name if db_node else "public"
+        else:
+            result = _resolve_name(expr)
+            if not result:
+                return
+            fschema, fname = result
+
+    # Extract args, return type, language, body with regex on raw SQL
+    args, return_type, language, body = _parse_function_details(raw)
+
+    func = FunctionDef(
+        schema=fschema,
+        name=fname,
+        args=args,
+        return_type=return_type,
+        language=language,
+        body=body,
+        kind=kind,
+    )
+    db_schema.functions[func.qualified_name] = func
+
+
+_FUNC_SIG = re.compile(
+    r'CREATE\s+(?:OR\s+REPLACE\s+)?(?:FUNCTION|PROCEDURE)\s+'
+    r'(?:\w+\.)?(\w+)\s*\(([^)]*(?:\([^)]*\)[^)]*)*)\)\s*'
+    r'(?:RETURNS\s+((?:TABLE\s*\([^)]+\)|SETOF\s+\S+|\S+)))?\s*'
+    r'LANGUAGE\s+(\w+)',
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+def _parse_function_details(sql: str) -> tuple[str, str, str, str]:
+    args, return_type, language, body = "", "", "", ""
+
+    m = _FUNC_SIG.search(sql)
+    if m:
+        args = re.sub(r'\s+', ' ', m.group(2) or "").strip().lower()
+        return_type = (m.group(3) or "").strip().lower()
+        language = (m.group(4) or "").strip().lower()
+
+    dm = _DOLLAR_BODY.search(sql)
+    if dm:
+        raw_body = dm.group(2)
+        lines = [l.strip() for l in raw_body.splitlines()]
+        body = "\n".join(l.lower() for l in lines if l)
+
+    return args, return_type, language, body
+
+
+def _handle_type(expr: exp.Create, db_schema: DatabaseSchema) -> None:
+    result = _resolve_name(expr)
+    if not result:
+        return
+    tschema, tname = result
+
+    expression = expr.expression
+    if expression is None:
+        return
+
+    if isinstance(expression, exp.DataType) and expression.this == exp.DataType.Type.ENUM:
+        values = [lit.name for lit in expression.expressions if isinstance(lit, exp.Literal)]
+        enum = EnumDef(schema=tschema, name=tname, values=values)
+        db_schema.enums[enum.qualified_name] = enum
+    elif isinstance(expression, exp.Schema):
+        # Composite type: fields are ColumnDef-like
+        fields = []
+        for col in expression.expressions:
+            if isinstance(col, exp.ColumnDef) and col.kind:
+                fields.append((col.name, col.kind.sql(dialect="postgres").lower()))
+        comp = CompositeTypeDef(schema=tschema, name=tname, fields=fields)
+        db_schema.composites[comp.qualified_name] = comp
+
+
+def _handle_schema_create(expr: exp.Create, db_schema: DatabaseSchema) -> None:
+    this = expr.this
+    name = this.name if hasattr(this, "name") else ""
+    if not name:
+        # sqlglot (30.11.0) parses "CREATE SCHEMA myapp" as a Table node
+        # whose `db` arg holds the schema name and `.name` (the table
+        # identifier) is empty.
+        db_node = this.args.get("db") if hasattr(this, "args") else None
+        name = db_node.name if db_node else ""
+    if name:
+        db_schema.schemas.add(name)
+
+
+def _handle_index(expr: exp.Create, db_schema: DatabaseSchema) -> None:
+    this = expr.this
+    index_name = this.name if hasattr(this, "name") else ""
+    table_node = expr.find(exp.Table)
+    if not table_node:
+        return
+    db_node = table_node.args.get("db")
+    tschema = db_node.name if db_node else "public"
+    tname = table_node.name
+    definition = expr.sql(dialect="postgres").lower()
+    idx = IndexDef(schema=tschema, table=tname, name=index_name, definition=definition)
+    db_schema.indexes[idx.qualified_name] = idx
+
+
+def _extract_do_block_objects(sql: str, db_schema: DatabaseSchema) -> None:
+    """Extract CREATE TYPE statements from DO $$ ... $$ blocks using regex."""
+    for dm in _DOLLAR_BODY.finditer(sql):
+        block = dm.group(2)
+        for m in _DO_ENUM.finditer(block):
+            qualified = m.group(1)
+            parts = qualified.split(".")
+            tschema, tname = (parts[0], parts[1]) if len(parts) == 2 else ("public", parts[0])
+            values_raw = m.group(2)
+            values = [v.strip().strip("'\"") for v in values_raw.split(",") if v.strip()]
+            enum = EnumDef(schema=tschema, name=tname, values=values)
+            db_schema.enums.setdefault(enum.qualified_name, enum)
+        for m in _DO_COMPOSITE.finditer(block):
+            qualified = m.group(1)
+            parts = qualified.split(".")
+            tschema, tname = (parts[0], parts[1]) if len(parts) == 2 else ("public", parts[0])
+            fields_raw = m.group(2)
+            fields = []
+            for field_def in fields_raw.split(","):
+                parts2 = field_def.strip().split()
+                if len(parts2) >= 2:
+                    fields.append((parts2[0], " ".join(parts2[1:]).lower()))
+            comp = CompositeTypeDef(schema=tschema, name=tname, fields=fields)
+            db_schema.composites.setdefault(comp.qualified_name, comp)

pgdevkit/skills/pgdevkit/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: pgdevkit
+plugin: coding
+description: >
+  Use pgdevkit for any PostgreSQL work in a Python project: a local
+  Docker/Podman test database (`pgdb testdb`), importable ORM-free CRUD
+  helpers (`pgdevkit.db`), and the `database/`-folder schema-as-code
+  convention. Supersedes the old postgres-test-setup, postgres-best-practices,
+  and database-in-source skills — pgdevkit is a real dependency now, not
+  copy-pasted reference files. Use whenever the user wants to set up a local
+  test Postgres, write or review psycopg code, add a table/view/function to
+  a `database/` folder, or asks things like "add a database query", "create
+  a repository", "set up a test database", "reset the database", "add a
+  table", "migration script", "backfill missing objects", or mentions
+  psycopg/psycopg2/asyncpg/SQLAlchemy where the user seems open to a
+  different approach.
+---
+
+# pgdevkit — Postgres for Python projects
+
+One dependency covers three things that used to be three separate skills
+with copy-pasted reference files:
+
+| Old skill | Replaced by |
+|---|---|
+| `postgres-test-setup` | `pgdb testdb` (container + schema apply) |
+| `postgres-best-practices` | `pgdevkit.db` (importable CRUD helpers) |
+| `database-in-source` | The `database/` folder convention — see [docs/database-layout.md](../../docs/database-layout.md) |
+
+Core rules for every piece of database code in a project using pgdevkit:
+
+- **No ORM** — use [psycopg](https://www.psycopg.org/psycopg3/) directly, via `pgdevkit.db`'s helpers or hand-written queries.
+- **Inline SQL** — trivial queries of **4 lines or fewer** may be written inline in Python. Anything with JOINs, subqueries, CTEs, aggregations, or multiple conditions lives in its own `.sql` file.
+- **Named parameters** — always `%(name)s` style, never positional `%s`.
+- **The `database/` folder is the source of truth for the schema** — see [docs/database-layout.md](../../docs/database-layout.md) for the layer/object-type/file-naming conventions.
+- **Result mapping** — every query result maps to a Pydantic model; table-mapped models extend `pgdevkit.db.PostgresTableModel`.
+
+---
+
+## Install
+
+```bash
+uv add pgdevkit[cli,db]
+```
+
+`cli` pulls in `typer`/`rich` for the `pgdb` command; `db` pulls in `pydantic`/`psycopg-pool` for the importable CRUD helpers. Skip either extra if the project doesn't need it (e.g. a project using only `pgdb testdb` doesn't need `db`).
+
+---
+
+## Local test database — `pgdb testdb`
+
+Add to `pyproject.toml`:
+
+```toml
+[tool.pgdevkit]
+database_dir = "database"       # optional, defaults to "database"
+env_prefix = "MDM_"              # optional, defaults to "{name.upper()}_"
+extensions = ["vector"]          # optional, CREATE EXTENSION IF NOT EXISTS
+```
+
+`name` is optional too — it falls back to the repo directory name.
+
+In `tests/conftest.py`:
+
+```python
+import pytest
+from pgdevkit.testdb import ensure_testdb
+
+@pytest.fixture(scope="session", autouse=True)
+def _testdb_env():
+    env = ensure_testdb()
+    for key, value in env.items():
+        os.environ[key] = value
+```
+
+`ensure_testdb()` starts the shared `pgdevkit-postgres` container if needed (via `podman`), creates a database scoped to this project+branch (so different worktrees/branches never collide), and applies every `.sql` file under `database_dir` in dependency order, seeding any `.test_data.json` sidecar files.
+
+| What do you need? | Command |
+|---|---|
+| First-time setup / apply new files | `pgdb testdb up` |
+| Breaking change (rename/drop column) | `pgdb testdb reset` |
+| Inspect test DB data | `pgdb testdb run-sql --sql "SELECT ..." --results` |
+| Re-apply one file (e.g. a function/view) | `pgdb testdb run-sql database/path/to/file.sql` |
+| Drop this workspace's database | `pgdb testdb clean` |
+| Drop every database for this project (all branches) | `pgdb testdb clean --all` |
+
+### CI
+
+Podman needs to be available on the runner (`apt-get install -y podman` on `ubuntu-latest` if not preinstalled) — `ensure_testdb()`/`ensure_container()` shell out to it directly. There's no `PGDEVKIT_SKIP_CONTAINER` + service-container escape hatch wired through every fixture yet — if a project's CI can't run podman, it needs its own workaround for now.
+
+---
+
+## Application-side DB code — `pgdevkit.db`
+
+```
+app/
+├── db/
+│   ├── queries/
+│   │   ├── users/
+│   │   │   ├── get_user_by_id.sql
+│   │   │   └── list_active_users.sql
+│   └── repositories/
+│       └── user_repository.py
+├── models/
+│   └── user_models.py         # Pydantic models for the user domain
+```
+
+SQL files live under `db/queries/<topic>/`. Every custom query gets its own file — no multi-statement files that lump unrelated queries together.
+
+### Connection pool
+
+```python
+# db/connection.py
+from pgdevkit.db import PgPool
+
+pool = PgPool(env_prefix="APP_POSTGRES_")  # matches ensure_testdb()'s {env_prefix}POSTGRES_* vars
+
+async def startup():
+    await pool.open()
+```
+
+### Models
+
+```python
+# models/user_models.py
+from __future__ import annotations
+from datetime import datetime
+from pydantic import BaseModel, ConfigDict
+from pgdevkit.db import PostgresTableModel
+
+class UserRow(PostgresTableModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    email: str
+    display_name: str
+    created_at: datetime
+
+    @staticmethod
+    def get_table_name() -> tuple[str, str]:
+        return ("public", "users")
+
+    @staticmethod
+    def get_primary_key() -> list[str]:
+        return ["id"]
+
+class UserSummary(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    display_name: str
+```
+
+Models that represent partial results (joins, aggregations, partial selects) extend `BaseModel` directly instead of `PostgresTableModel`.
+
+### CRUD helpers
+
+```python
+from pgdevkit.db import pg_retrieve, pg_insert, pg_upsert, pg_delete
+```
+
+| Helper | Purpose |
+|--------|---------|
+| `pg_retrieve` | Fetch single row by PK |
+| `pg_retrieve_many` | Fetch rows matching filter dict |
+| `pg_insert` | Insert one row, `RETURNING *` |
+| `pg_update` / `pg_update_dict` | Update by PK |
+| `pg_upsert` / `pg_upsert_dict` | `INSERT ... ON CONFLICT ... DO UPDATE` |
+| `pg_upsert_many` / `pg_upsert_many_dict` | Batch upsert via `executemany` |
+| `pg_insert_many` | Batch insert via `executemany` |
+| `pg_delete` / `pg_delete_dict` | Delete by PK, returns deleted row |
+
+Use these for simple CRUD. For custom `WHERE` clauses, joins, aggregations, or ordering, write a dedicated `.sql` file and a repository method.
+
+### Loading `.sql` files
+
+```python
+# db/loader.py
+from pathlib import Path
+from pgdevkit.db import SqlLoader
+
+sql = SqlLoader(Path(__file__).parent / "queries")
+```
+
+```python
+# db/repositories/user_repository.py
+from psycopg.rows import dict_row
+from pgdevkit.db import pg_retrieve, pg_delete
+from db.connection import pool
+from db.loader import sql
+from models.user_models import UserRow, UserSummary
+
+class UserRepository:
+    async def get_by_id(self, user_id: int) -> UserRow | None:
+        async with pool.connection() as conn:
+            return await pg_retrieve(conn, UserRow, {"id": user_id})
+
+    async def list_active(self, limit: int = 100) -> list[UserSummary]:
+        async with pool.connection() as conn:
+            async with conn.cursor(row_factory=dict_row) as cur:
+                await cur.execute(sql.load_sql("users", "list_active_users"), {"limit": limit})
+                rows = await cur.fetchall()
+        return [UserSummary.model_validate(r) for r in rows]
+
+    async def delete(self, user: UserRow) -> UserRow | None:
+        async with pool.connection() as conn:
+            return await pg_delete(conn, user, UserRow)
+```
+
+Named parameters, `%(name)s` style, dict argument — never positional `%s`, never f-strings or `str.format()` for SQL text.
+
+### Dynamic SQL
+
+Avoid it whenever possible — a static `.sql` file is always clearer. See [`references/dynamic-sql.md`](references/dynamic-sql.md) for t-string templates (3.14+) and `psycopg.sql` (< 3.14) when column/table names genuinely vary at runtime.
+
+### Avoid `LATERAL JOIN` — use a CTE instead
+
+```sql
+with latest_order as (
+    select
+        o.user_id,
+        o.total,
+        row_number() over (partition by o.user_id order by o.created_at desc) as rn
+    from orders as o
+)
+select u.id, u.email, lo.total
+from users as u
+join latest_order as lo on lo.user_id = u.id and lo.rn = 1
+```
+
+### Temporal tables
+
+See [`references/temporal-tables.md`](references/temporal-tables.md) for row-level history via `nearform/temporal_tables`.
+
+### Custom Postgres types in test data
+
+`pgdevkit.testdb.schema`'s test-data seeding handles plain columns and JSONB, but not composite types or enums directly. See [`references/complex_helper.py`](references/complex_helper.py) for a psycopg adapter (`ComplexHelper`) if a project needs that.
+
+### SQL formatting
+
+```bash
+uv add --dev shandy-sqlfmt[jinjafmt]
+sqlfmt db/queries/          # format
+sqlfmt --check db/queries/  # CI check
+```
+
+---
+
+## The `database/` folder & backfilling untracked objects
+
+See [docs/database-layout.md](../../docs/database-layout.md) for the full convention: layer directories, object-type subfolders and their apply order, file-naming rules (`.test_data.json`, `.init.sql`, `.prod`), and how migrations are organised.
+
+If a table, view, or function was created directly on the database and never got a `.sql` file:
+
+```bash
+pgdb fetch-missing database/ --url postgresql://... # dry run, lists what's missing
+pgdb fetch-missing database/ --url postgresql://... --write
+```
+
+It diffs the live schema against `database/`, reverse-engineers DDL for anything untracked, and writes it into the matching layer folder's `tables/`, `views/`, `scalar_functions/`, or `table_functions/` subfolder (matched by schema name against existing top-level directories, ignoring their leading sort number).
+
+---
+
+## Comparing scripts to a live database
+
+```bash
+pgdb compare --url postgresql://... database/
+```
+
+Reports drift between the `database/` `.sql` files and the actual schema — tables, views, functions, enums, composite types, and indexes. Pass `--report-extra-db` to also flag objects that exist in the database but aren't tracked (this is what `pgdb fetch-missing` uses internally).
+
+---
+
+## Quick checklist
+
+- [ ] `[tool.pgdevkit]` configured in `pyproject.toml`; `tests/conftest.py` calls `ensure_testdb()`
+- [ ] New table/view/function/type gets its own `.sql` file under the right layer + object-type folder (see [docs/database-layout.md](../../docs/database-layout.md))
+- [ ] Simple CRUD uses `pgdevkit.db`'s `pg_*` helpers; custom queries use `.sql` files loaded via `SqlLoader`
+- [ ] Inline SQL only for trivial queries ≤ 4 lines; anything with JOINs/CTEs/aggregations/subqueries uses a `.sql` file
+- [ ] All parameters use `%(name)s` style with a dict argument
+- [ ] Results mapped to a Pydantic model; table-mapped models extend `PostgresTableModel`
+- [ ] No `LATERAL JOIN` — use a CTE that groups/aggregates first, then joins it
+- [ ] `.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
+- [ ] Untracked DB objects backfilled via `pgdb fetch-missing`, not left undocumented