@opengroundplan/core 0.1.1

package/templates/layers/db-postgres/files/src/__solutionName.snake__/db/postgres.py

@@ -0,0 +1,256 @@
+"""db-core's Database port over psycopg 3.
+
+One pool per process; each transaction takes a single connection so every
+repository in that unit of work shares the same PostgreSQL transaction.
+
+Rows come back as dicts. ``add``/``update`` accept a mapping, a dataclass, or any
+object with ``__dict__``, so entities are whatever the caller already models.
+"""
+
+import dataclasses
+from typing import Any, Awaitable, Callable, Mapping, TypeVar
+
+from psycopg import AsyncCursor, sql
+from psycopg.rows import dict_row
+from psycopg_pool import AsyncConnectionPool
+
+from .api import use_database
+from .config import db_config
+from .errors import DbError
+from .ports import Criteria, Page, Sort
+from .postgres_config import postgres_config
+from .postgres_errors import to_db_error
+
+R = TypeVar("R")
+
+
+def _fields(entity: Any) -> dict[str, Any]:
+    if isinstance(entity, Mapping):
+        return dict(entity)
+    if dataclasses.is_dataclass(entity) and not isinstance(entity, type):
+        return dataclasses.asdict(entity)
+    if hasattr(entity, "__dict__"):
+        return {k: v for k, v in vars(entity).items() if not k.startswith("_")}
+    raise DbError("unknown", f"Cannot read fields from {type(entity).__name__}")
+
+
+def _id_of(entity: Any) -> Any:
+    return entity["id"] if isinstance(entity, Mapping) else entity.id
+
+
+def _order_by(sort: tuple[Sort, ...]) -> sql.Composable:
+    if not sort:
+        return sql.SQL("")
+    parts = [
+        sql.SQL("{} {}").format(
+            sql.Identifier(s.field),
+            sql.SQL("DESC" if s.direction == "desc" else "ASC"),
+        )
+        for s in sort
+    ]
+    return sql.SQL(" ORDER BY ") + sql.SQL(", ").join(parts)
+
+
+def _where(where: dict[str, Any] | None) -> tuple[sql.Composable, list[Any]]:
+    if not where:
+        return sql.SQL(""), []
+
+    parts: list[sql.Composable] = []
+    values: list[Any] = []
+    for column, value in where.items():
+        if value is None:
+            # IS NULL, because `= NULL` is never true in SQL.
+            parts.append(sql.SQL("{} IS NULL").format(sql.Identifier(column)))
+        else:
+            parts.append(sql.SQL("{} = %s").format(sql.Identifier(column)))
+            values.append(value)
+
+    return sql.SQL(" WHERE ") + sql.SQL(" AND ").join(parts), values
+
+
+class PostgresRepository:
+    """Collections map to tables and entity keys to columns, both quoted as identifiers."""
+
+    def __init__(self, cursor: AsyncCursor, collection: str) -> None:
+        self._cursor = cursor
+        self._collection = collection
+        self._table = sql.Identifier(collection)
+
+    async def find_by_id(self, entity_id: Any) -> dict[str, Any] | None:
+        await self._execute(
+            sql.SQL("SELECT * FROM {} WHERE id = %s LIMIT 1").format(self._table),
+            [entity_id],
+        )
+        return await self._cursor.fetchone()
+
+    async def find(self, criteria: Criteria | None = None) -> list[dict[str, Any]]:
+        criteria = criteria or Criteria()
+        clause, values = _where(criteria.where)
+
+        statement = sql.SQL("SELECT * FROM {}").format(self._table) + clause + _order_by(criteria.sort)
+        if criteria.limit is not None:
+            statement += sql.SQL(" LIMIT %s")
+            values.append(criteria.limit)
+        if criteria.offset:
+            statement += sql.SQL(" OFFSET %s")
+            values.append(criteria.offset)
+
+        await self._execute(statement, values)
+        return await self._cursor.fetchall()
+
+    async def page(self, criteria: Criteria | None = None) -> Page[dict[str, Any]]:
+        criteria = criteria or Criteria()
+        items = await self.find(criteria)
+        total = await self.count(criteria.where)
+        return Page(
+            items=items,
+            total=total,
+            limit=criteria.limit if criteria.limit is not None else len(items),
+            offset=criteria.offset,
+        )
+
+    async def count(self, where: dict[str, Any] | None = None) -> int:
+        clause, values = _where(where)
+        await self._execute(sql.SQL("SELECT count(*) AS count FROM {}").format(self._table) + clause, values)
+        row = await self._cursor.fetchone()
+        return int(row["count"]) if row else 0
+
+    async def add(self, entity: Any) -> dict[str, Any]:
+        values = _fields(entity)
+        if not values:
+            raise DbError("unknown", f"{self._collection}: cannot insert an empty entity")
+
+        statement = sql.SQL("INSERT INTO {} ({}) VALUES ({}) RETURNING *").format(
+            self._table,
+            sql.SQL(", ").join(sql.Identifier(c) for c in values),
+            sql.SQL(", ").join(sql.Placeholder() for _ in values),
+        )
+        await self._execute(statement, list(values.values()))
+        row = await self._cursor.fetchone()
+        return row or {}
+
+    async def update(self, entity: Any) -> dict[str, Any]:
+        values = _fields(entity)
+        entity_id = values.pop("id", None) or _id_of(entity)
+        if not values:
+            raise DbError("unknown", f"{self._collection}: update needs a field besides id")
+
+        assignments = sql.SQL(", ").join(
+            sql.SQL("{} = %s").format(sql.Identifier(c)) for c in values
+        )
+        statement = sql.SQL("UPDATE {} SET {} WHERE id = %s RETURNING *").format(self._table, assignments)
+
+        await self._execute(statement, [*values.values(), entity_id])
+        row = await self._cursor.fetchone()
+        if row is None:
+            raise DbError.not_found(self._collection, entity_id)
+        return row
+
+    async def remove(self, entity_id: Any) -> bool:
+        await self._execute(sql.SQL("DELETE FROM {} WHERE id = %s").format(self._table), [entity_id])
+        return self._cursor.rowcount > 0
+
+    async def _execute(self, statement: sql.Composable, values: list[Any]) -> None:
+        try:
+            await self._cursor.execute(statement, values)
+        except Exception as error:
+            raise to_db_error(error) from error
+
+
+class PostgresUnitOfWork:
+    def __init__(self, cursor: AsyncCursor, transaction: Any) -> None:
+        self._cursor = cursor
+        self._transaction = transaction
+        self._settled = False
+
+    def repository(self, collection: str) -> PostgresRepository:
+        self._assert_open()
+        return PostgresRepository(self._cursor, collection)
+
+    async def commit(self) -> None:
+        # The surrounding `async with connection.transaction()` commits on exit;
+        # marking it settled keeps a second commit from being issued.
+        self._assert_open()
+        self._settled = True
+
+    async def rollback(self) -> None:
+        self._assert_open()
+        self._settled = True
+        raise _Rollback
+
+    @property
+    def settled(self) -> bool:
+        return self._settled
+
+    def _assert_open(self) -> None:
+        if self._settled:
+            raise DbError("unknown", "This unit of work has already been settled.")
+
+
+class _Rollback(Exception):
+    """Unwinds psycopg's transaction context without surfacing to the caller."""
+
+
+class PostgresDatabase:
+    def __init__(self) -> None:
+        self._pool: AsyncConnectionPool | None = None
+        self._closed = False
+
+    def _connections(self) -> AsyncConnectionPool:
+        if self._closed:
+            raise DbError("unavailable", "The database has been closed.")
+        if self._pool is None:
+            self._pool = AsyncConnectionPool(
+                conninfo=postgres_config.conninfo,
+                min_size=db_config.pool_min,
+                max_size=db_config.pool_max,
+                timeout=db_config.connect_timeout_ms / 1000,
+                max_idle=postgres_config.idle_timeout_ms / 1000,
+                # psycopg_pool 3.2+ refuses to open inside __init__.
+                open=False,
+            )
+        return self._pool
+
+    async def transaction(self, work: Callable[[Any], Awaitable[R]]) -> R:
+        pool = self._connections()
+        if pool.closed:
+            await pool.open()
+
+        try:
+            async with pool.connection() as connection:
+                connection.row_factory = dict_row
+                try:
+                    async with connection.transaction() as tx:
+                        async with connection.cursor(row_factory=dict_row) as cursor:
+                            uow = PostgresUnitOfWork(cursor, tx)
+                            return await work(uow)
+                except _Rollback:
+                    # An explicit rollback() is a normal outcome, not a failure.
+                    return None  # type: ignore[return-value]
+        except DbError:
+            raise
+        except Exception as error:
+            raise to_db_error(error) from error
+
+    async def ping(self) -> bool:
+        try:
+            pool = self._connections()
+            if pool.closed:
+                await pool.open()
+            async with pool.connection() as connection:
+                async with connection.cursor() as cursor:
+                    await cursor.execute("SELECT 1")
+            return True
+        except Exception:  # noqa: BLE001 - a probe must report, never raise.
+            return False
+
+    async def close(self) -> None:
+        self._closed = True
+        pool, self._pool = self._pool, None
+        if pool is not None and not pool.closed:
+            await pool.close()
+
+
+def use_postgres() -> None:
+    """Installs PostgreSQL as the engine behind db-core's ``database()``."""
+    use_database(PostgresDatabase)

package/templates/layers/db-postgres/files/src/__solutionName.snake__/db/postgres_config.py

@@ -0,0 +1,81 @@
+"""PostgreSQL-only settings.
+
+The shared surface (url, pool bounds, timeouts) lives in db-core's ``db_config``;
+this module adds what only this engine understands, under the same env prefix.
+"""
+
+import os
+from dataclasses import dataclass
+
+from .config import db_config
+
+_PREFIX = "{{ dbEnvPrefix }}"
+
+_SSL_MODES = ("disable", "prefer", "require", "verify-full")
+
+# Typed defaults. The single place a literal PostgreSQL value may appear.
+_DEFAULTS = {
+    "sslmode": "prefer",
+    "idle_timeout_ms": 30_000,
+    "migrations_dir": "./migrations",
+    "migrations_table": "schema_migrations",
+    # Advisory-lock key. Every app sharing this database must use the same number.
+    "migrations_lock_id": 3_141_592,
+}
+
+
+def _raw(key: str) -> str | None:
+    return os.environ.get(f"{_PREFIX}_{key}") or None
+
+
+def _int(key: str, fallback: int) -> int:
+    value = _raw(key)
+    if value is None:
+        return fallback
+    try:
+        return int(value)
+    except ValueError as exc:
+        raise ValueError(f"{_PREFIX}_{key} must be an integer, got {value!r}") from exc
+
+
+@dataclass(frozen=True, slots=True)
+class PostgresConfig:
+    sslmode: str
+    idle_timeout_ms: int
+    migrations_dir: str
+    migrations_table: str
+    migrations_lock_id: int
+
+    @property
+    def conninfo(self) -> str:
+        """libpq connection string, with the server-side statement cap applied."""
+        if not db_config.url:
+            raise ValueError(f"{_PREFIX}_URL is required when the PostgreSQL layer is installed.")
+
+        # Imported here so importing settings never requires the driver to be present.
+        from psycopg.conninfo import make_conninfo
+
+        return make_conninfo(
+            db_config.url,
+            sslmode=self.sslmode,
+            # libpq counts this in whole seconds.
+            connect_timeout=max(1, db_config.connect_timeout_ms // 1000),
+            options=f"-c statement_timeout={db_config.statement_timeout_ms}",
+        )
+
+
+def load_postgres_config() -> PostgresConfig:
+    sslmode = _raw("SSLMODE") or str(_DEFAULTS["sslmode"])
+    if sslmode not in _SSL_MODES:
+        raise ValueError(f"{_PREFIX}_SSLMODE must be one of {', '.join(_SSL_MODES)}, got {sslmode!r}")
+
+    return PostgresConfig(
+        sslmode=sslmode,
+        idle_timeout_ms=_int("IDLE_TIMEOUT_MS", int(_DEFAULTS["idle_timeout_ms"])),
+        migrations_dir=_raw("MIGRATIONS_DIR") or str(_DEFAULTS["migrations_dir"]),
+        migrations_table=_raw("MIGRATIONS_TABLE") or str(_DEFAULTS["migrations_table"]),
+        migrations_lock_id=_int("MIGRATIONS_LOCK_ID", int(_DEFAULTS["migrations_lock_id"])),
+    )
+
+
+postgres_config = load_postgres_config()

package/templates/layers/db-postgres/files/src/__solutionName.snake__/db/postgres_errors.py

@@ -0,0 +1,48 @@
+"""SQLSTATE translation.
+
+Drivers leak vendor codes; db-core's taxonomy is what callers branch on, so the
+mapping lives here and nowhere else.
+
+Codes: https://www.postgresql.org/docs/current/errcodes-appendix.html
+"""
+
+from typing import Any
+
+from .errors import DbError, DbErrorKind
+
+_BY_CODE: dict[str, DbErrorKind] = {
+    "23505": "conflict",  # unique_violation
+    "23502": "integrity",  # not_null_violation
+    "23503": "integrity",  # foreign_key_violation
+    "23514": "integrity",  # check_violation
+    "23P01": "integrity",  # exclusion_violation
+    "40001": "transient",  # serialization_failure
+    "40P01": "transient",  # deadlock_detected
+    "55P03": "transient",  # lock_not_available
+    "57014": "timeout",  # query_canceled, which is what statement_timeout raises
+    "53300": "unavailable",  # too_many_connections
+    "57P01": "unavailable",  # admin_shutdown
+    "57P02": "unavailable",  # crash_shutdown
+    "57P03": "unavailable",  # cannot_connect_now
+}
+
+# Whole classes that map uniformly, checked after the exact codes above.
+_BY_CLASS: dict[str, DbErrorKind] = {
+    "08": "unavailable",  # connection exception
+    "53": "unavailable",  # insufficient resources
+    "23": "integrity",  # integrity constraint violation
+}
+
+
+def classify(error: BaseException) -> DbErrorKind:
+    sqlstate: Any = getattr(error, "sqlstate", None)
+    if not isinstance(sqlstate, str):
+        return "unknown"
+    return _BY_CODE.get(sqlstate) or _BY_CLASS.get(sqlstate[:2], "unknown")
+
+
+def to_db_error(error: BaseException) -> DbError:
+    """Wraps a driver error as a DbError, preserving the original as detail."""
+    if isinstance(error, DbError):
+        return error
+    return DbError.wrap(classify(error), error)

package/templates/layers/db-postgres/files/src/__solutionName.snake__/db/postgres_migrate.py

@@ -0,0 +1,132 @@
+"""Forward-only SQL migration runner.
+
+Files run in filename order, each in its own transaction, recorded with a
+checksum. An already-applied file that changed is a hard error: the database and
+the repository disagree about history, and guessing which one is right is how
+data gets lost.
+
+Run with:  python -m {{ solutionName | snake }}.db.postgres_migrate
+"""
+
+import hashlib
+import sys
+from pathlib import Path
+
+import psycopg
+from psycopg import sql
+
+from .errors import DbError
+from .postgres_config import postgres_config
+from .postgres_errors import to_db_error
+
+_CREATE_TABLE = sql.SQL(
+    """
+    CREATE TABLE IF NOT EXISTS {table} (
+        version    text PRIMARY KEY,
+        checksum   text NOT NULL,
+        applied_at timestamptz NOT NULL DEFAULT now()
+    )
+    """
+)
+
+
+def _migrations() -> list[Path]:
+    directory = Path(postgres_config.migrations_dir)
+    if not directory.is_dir():
+        raise DbError("unknown", f"Migrations directory not found: {directory}")
+    return sorted(directory.glob("*.sql"))
+
+
+def _checksum(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def run_migrations() -> list[str]:
+    """Applies every pending migration and returns the filenames that ran."""
+    # Identifier() quotes the name safely; a table name cannot be a bound parameter.
+    table = sql.Identifier(postgres_config.migrations_table)
+    files = _migrations()
+    applied: list[str] = []
+
+    # A dedicated connection, not a pooled one: the advisory lock lives on the session.
+    with psycopg.connect(postgres_config.conninfo, autocommit=True) as connection:
+        with connection.cursor() as cursor:
+            # Request traffic runs under a statement_timeout; a migration may
+            # legitimately take far longer than that.
+            cursor.execute("SET statement_timeout = 0")
+            # Serialises concurrent deploys instead of letting them race.
+            cursor.execute("SELECT pg_advisory_lock(%s)", (postgres_config.migrations_lock_id,))
+
+            try:
+                cursor.execute(_CREATE_TABLE.format(table=table))
+                cursor.execute(sql.SQL("SELECT version, checksum FROM {}").format(table))
+                known = dict(cursor.fetchall())
+
+                for path in files:
+                    body = path.read_text(encoding="utf-8")
+                    digest = _checksum(body)
+                    previous = known.get(path.name)
+
+                    if previous is not None:
+                        if previous != digest:
+                            raise DbError(
+                                "conflict",
+                                f"Migration {path.name} was edited after it was applied. "
+                                "Add a new migration instead.",
+                            )
+                        continue
+
+                    try:
+                        # autocommit is on, so the transaction block is explicit.
+                        with connection.transaction():
+                            cursor.execute(body)
+                            cursor.execute(
+                                sql.SQL("INSERT INTO {} (version, checksum) VALUES (%s, %s)").format(table),
+                                (path.name, digest),
+                            )
+                    except DbError:
+                        raise
+                    except Exception as error:
+                        raise DbError(
+                            "unknown", f"Migration {path.name} failed: {to_db_error(error)}"
+                        ) from error
+
+                    applied.append(path.name)
+            finally:
+                cursor.execute("SELECT pg_advisory_unlock(%s)", (postgres_config.migrations_lock_id,))
+
+    return applied
+
+
+def pending_migrations() -> list[str]:
+    """Names of migrations that exist on disk but have not run yet."""
+    table = sql.Identifier(postgres_config.migrations_table)
+    names = [path.name for path in _migrations()]
+
+    with psycopg.connect(postgres_config.conninfo, autocommit=True) as connection:
+        with connection.cursor() as cursor:
+            cursor.execute(_CREATE_TABLE.format(table=table))
+            cursor.execute(sql.SQL("SELECT version FROM {}").format(table))
+            known = {row[0] for row in cursor.fetchall()}
+
+    return [name for name in names if name not in known]
+
+
+def main() -> int:
+    try:
+        applied = run_migrations()
+    except Exception as error:  # noqa: BLE001 - surface the reason, not a traceback.
+        print(error, file=sys.stderr)
+        return 1
+
+    if applied:
+        print(f"Applied {len(applied)}:")
+        for name in applied:
+            print(f"  {name}")
+    else:
+        print("Already up to date.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/layers/db-postgres/files/src/db/postgres/config.ts

@@ -0,0 +1,86 @@
+/**
+ * PostgreSQL-only settings. The shared surface (url, pool bounds, timeouts) lives
+ * in db-core's `dbConfig`; this file adds what only this engine understands and
+ * reuses the same environment prefix.
+ */
+import type { PoolConfig } from 'pg';
+import { dbConfig } from '../config.js';
+
+const PREFIX = '{{ dbEnvPrefix }}';
+
+export type SslMode = 'disable' | 'prefer' | 'require' | 'verify-full';
+
+const SSL_MODES: readonly SslMode[] = ['disable', 'prefer', 'require', 'verify-full'];
+
+/** Typed defaults — the single place a literal PostgreSQL value may appear. */
+const defaults = {
+  sslMode: 'prefer' as SslMode,
+  idleTimeoutMs: 30_000,
+  migrationsDir: './migrations',
+  migrationsTable: 'schema_migrations',
+  /** Advisory-lock key. Every app sharing this database must use the same number. */
+  migrationsLockId: 3_141_592,
+} as const;
+
+/** Declared explicitly rather than mapped off `defaults`, whose literal types would
+ *  make every field assignable only to its own default value. */
+export interface PostgresConfig {
+  sslMode: SslMode;
+  idleTimeoutMs: number;
+  migrationsDir: string;
+  migrationsTable: string;
+  migrationsLockId: number;
+}
+
+function raw(key: string): string | undefined {
+  const value = process.env[`${PREFIX}_${key}`];
+  return value === undefined || value === '' ? undefined : value;
+}
+
+function int(key: string, fallback: number): number {
+  const value = raw(key);
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) throw new Error(`${PREFIX}_${key} must be an integer, got "${value}"`);
+  return parsed;
+}
+
+function mode(key: string, fallback: SslMode): SslMode {
+  const value = raw(key);
+  if (value === undefined) return fallback;
+  if (!SSL_MODES.includes(value as SslMode)) {
+    throw new Error(`${PREFIX}_${key} must be one of ${SSL_MODES.join(', ')}, got "${value}"`);
+  }
+  return value as SslMode;
+}
+
+export const postgresConfig: PostgresConfig = {
+  sslMode: mode('SSLMODE', defaults.sslMode),
+  idleTimeoutMs: int('IDLE_TIMEOUT_MS', defaults.idleTimeoutMs),
+  migrationsDir: raw('MIGRATIONS_DIR') ?? defaults.migrationsDir,
+  migrationsTable: raw('MIGRATIONS_TABLE') ?? defaults.migrationsTable,
+  migrationsLockId: int('MIGRATIONS_LOCK_ID', defaults.migrationsLockId),
+};
+
+/** node-postgres has no `prefer`: it either negotiates TLS or it does not. */
+function toSslOption(value: SslMode): PoolConfig['ssl'] {
+  if (value === 'disable' || value === 'prefer') return false;
+  return { rejectUnauthorized: value === 'verify-full' };
+}
+
+export function toPoolConfig(): PoolConfig {
+  if (!dbConfig.url) {
+    throw new Error(`${PREFIX}_URL is required when the PostgreSQL layer is installed.`);
+  }
+
+  return {
+    connectionString: dbConfig.url,
+    min: dbConfig.poolMin,
+    max: dbConfig.poolMax,
+    connectionTimeoutMillis: dbConfig.connectTimeoutMs,
+    idleTimeoutMillis: postgresConfig.idleTimeoutMs,
+    // Server-side cap, so one runaway query cannot hold a connection forever.
+    statement_timeout: dbConfig.statementTimeoutMs,
+    ssl: toSslOption(postgresConfig.sslMode),
+  };
+}