@damiangilgonzalez/harness 1.3.7

package/skills/fastapi/references/database.md

@@ -0,0 +1,347 @@
+# Async SQLAlchemy 2.0 + Alembic
+
+The async persistence layer for a FastAPI service on SQLAlchemy 2.0, asyncpg 0.30 (or
+psycopg 3 async), Alembic 1.13+, and PostgreSQL 16. The rules that prevent the two failures that
+sink async ORM code: **one session per request with explicit commit/rollback**, and **never lazy-load
+a relationship in async** — eager-load everything you serialize.
+
+## Engine & session factory
+
+```python
+from collections.abc import AsyncIterator
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from app.core.config import get_settings
+
+engine = create_async_engine(
+    str(get_settings().database_url),
+    pool_size=10,
+    max_overflow=20,
+    pool_pre_ping=True,
+    pool_recycle=1800,
+)
+async_session_factory = async_sessionmaker(engine, expire_on_commit=False)
+
+
+async def get_db() -> AsyncIterator[AsyncSession]:
+    async with async_session_factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+```
+
+`expire_on_commit=False` is mandatory: with the default `True`, attributes expire after commit
+and the *next* access triggers a lazy reload — which in async raises `MissingGreenlet`. The
+`get_db` dependency owns the transaction lifecycle; services call `flush`, never `commit`.
+
+## Declarative models (2.0 style)
+
+```python
+from datetime import datetime
+from uuid import UUID, uuid4
+
+from sqlalchemy import func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class TimestampMixin:
+    created_at: Mapped[datetime] = mapped_column(server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(
+        server_default=func.now(), onupdate=func.now()
+    )
+
+
+class User(TimestampMixin, Base):
+    __tablename__ = "users"
+
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    email: Mapped[str] = mapped_column(unique=True, index=True)
+    full_name: Mapped[str]
+    hashed_password: Mapped[str]
+    is_active: Mapped[bool] = mapped_column(default=True)
+```
+
+`Mapped[...]` drives both the Python type and (where unambiguous) the column type. A bare
+`Mapped[str]` is `NOT NULL`; `Mapped[str | None]` is nullable. `server_default=func.now()` puts
+the default in the database (resilient to non-ORM writes); `onupdate` fires on ORM updates.
+
+## Relationships
+
+```python
+from uuid import UUID, uuid4
+
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.db.base import Base
+
+
+class Order(Base):
+    __tablename__ = "orders"
+
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    user_id: Mapped[UUID] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True)
+    amount_cents: Mapped[int]
+
+    user: Mapped["User"] = relationship(back_populates="orders")
+
+
+# On the User model:
+#   orders: Mapped[list["Order"]] = relationship(
+#       back_populates="user", cascade="all, delete-orphan"
+#   )
+```
+
+`back_populates` keeps both sides in sync in the identity map. `cascade="all, delete-orphan"`
+deletes orphaned children when removed from the collection; pair it with a DB-level
+`ondelete="CASCADE"` on the FK so deletes are correct even outside the ORM.
+
+## Querying
+
+```python
+from uuid import UUID
+
+from sqlalchemy import delete, func, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.user import User
+
+
+async def queries(db: AsyncSession, pk: UUID, email: str) -> None:
+    # Filtered, ordered, paginated SELECT -> list of model instances.
+    result = await db.execute(
+        select(User).where(User.is_active.is_(True)).order_by(User.created_at.desc()).limit(50)
+    )
+    users: list[User] = list(result.scalars().all())
+
+    # Single row or None (raises on >1):
+    one = await db.execute(select(User).where(User.email == email))
+    maybe_user: User | None = one.scalar_one_or_none()
+
+    # Fast identity-map lookup by primary key:
+    by_pk: User | None = await db.get(User, pk)
+
+    # Core UPDATE / DELETE with RETURNING (no round-trip to reload):
+    updated = await db.execute(
+        update(User).where(User.id == pk).values(is_active=False).returning(User.id)
+    )
+    _changed_id = updated.scalar_one_or_none()
+    await db.execute(delete(User).where(User.id == pk))
+
+    # Aggregate:
+    total = await db.execute(select(func.count()).select_from(User))
+    _count: int = total.scalar_one()
+```
+
+Use `.scalars()` to unwrap single-entity rows into model instances; without it you get `Row`
+tuples. `scalar_one_or_none()` is the safe "fetch by unique key" idiom; `db.get` is the only one
+that consults the identity map first and can skip a query entirely.
+
+## N+1 & eager loading
+
+**Lazy loading is unsafe in async SQLAlchemy.** Accessing an unloaded relationship outside an
+awaited load triggers implicit I/O on the event loop and raises
+`sqlalchemy.exc.MissingGreenlet` (or, if it ever succeeds, fires one query per parent row — the
+N+1). Load relationships explicitly.
+
+```python
+# Bad: lazy access in async -> MissingGreenlet, or N+1 if it slips through.
+async def bad(db: AsyncSession) -> list[int]:
+    result = await db.execute(select(User))
+    users = result.scalars().all()
+    return [len(u.orders) for u in users]  # u.orders was never loaded -> raises / N queries
+```
+
+```python
+from sqlalchemy.orm import joinedload, selectinload
+
+
+# Good: eager-load up front in one extra query (collections) / one join (scalars).
+async def good_collections(db: AsyncSession) -> list[int]:
+    result = await db.execute(select(User).options(selectinload(User.orders)))
+    users = result.scalars().unique().all()
+    return [len(u.orders) for u in users]
+
+
+async def good_scalar(db: AsyncSession) -> list[str]:
+    result = await db.execute(select(Order).options(joinedload(Order.user)))
+    orders = result.scalars().all()
+    return [o.user.full_name for o in orders]
+```
+
+Choose `selectinload` for collections (one follow-up `IN (...)` query, no row multiplication);
+choose `joinedload` for scalar many-to-one (a single `JOIN`, no extra round-trip). Call
+`.unique()` when a `joinedload` on a collection would otherwise duplicate parent rows.
+
+## Repository / CRUD layer
+
+Keep `select`/`flush` out of routers behind a generic repository so persistence is swappable
+and testable in isolation.
+
+```python
+from typing import Generic, TypeVar
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.base import Base
+
+ModelT = TypeVar("ModelT", bound=Base)
+
+
+class Repository(Generic[ModelT]):
+    def __init__(self, model: type[ModelT], db: AsyncSession) -> None:
+        self.model = model
+        self.db = db
+
+    async def get(self, pk: UUID) -> ModelT | None:
+        return await self.db.get(self.model, pk)
+
+    async def list(self, limit: int, offset: int) -> list[ModelT]:
+        result = await self.db.execute(select(self.model).limit(limit).offset(offset))
+        return list(result.scalars().all())
+
+    async def add(self, obj: ModelT) -> ModelT:
+        self.db.add(obj)
+        await self.db.flush()
+        return obj
+
+    async def delete(self, obj: ModelT) -> None:
+        await self.db.delete(obj)
+        await self.db.flush()
+```
+
+`flush` pushes pending SQL (assigning generated PKs / surfacing constraint errors) **without**
+committing — the request's `get_db` owns the outer commit. Services compose repositories and
+enforce business rules; routers call services.
+
+## Transactions
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+async def transfer(db: AsyncSession, debit_id, credit_id, cents: int) -> None:
+    # Multi-statement atomicity: both updates commit together or neither does.
+    async with db.begin():
+        await debit(db, debit_id, cents)
+        await credit(db, credit_id, cents)
+
+
+async def with_savepoint(db: AsyncSession) -> None:
+    # Nested SAVEPOINT: roll back a sub-step without aborting the whole transaction.
+    async with db.begin_nested():
+        await risky_step(db)
+```
+
+With the `get_db` commit-on-success pattern, prefer `flush` inside services and let the
+dependency own the single outer commit. Reach for `db.begin()` explicitly only when a service
+must guarantee atomicity across statements it would otherwise leave to the request boundary.
+
+## Alembic (async)
+
+Async migrations need an `env.py` that runs the engine inside an event loop and dispatches DDL
+via `run_sync`.
+
+```python
+import asyncio
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from app.core.config import get_settings
+from app.db.base import Base
+
+config = context.config
+config.set_main_option("sqlalchemy.url", str(get_settings().database_url))
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def do_run_migrations(connection: Connection) -> None:
+    context.configure(connection=connection, target_metadata=target_metadata, compare_type=True)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    asyncio.run(run_async_migrations())
+
+
+run_migrations_online()
+```
+
+```ini
+# alembic.ini (sqlalchemy.url is overridden from env in env.py; leave a placeholder here)
+[alembic]
+script_location = alembic
+sqlalchemy.url = driver://user:pass@localhost/dbname
+```
+
+```bash
+alembic revision --autogenerate -m "create users"
+alembic upgrade head
+```
+
+Autogenerate is a draft, not an oracle: it misses server defaults, CHECK constraints, some type
+changes, and table/column renames (it sees a drop + add). **Always read the generated migration**
+before committing, and add `compare_type=True` (above) to catch column type drift. For a
+review-then-apply workflow in prod, emit offline SQL with `alembic upgrade head --sql`.
+
+## Connection pooling & production
+
+Total open connections is bounded by `workers × (pool_size + max_overflow)` and must stay under
+Postgres `max_connections` (default 100) with headroom for admin and other clients. With 5
+gunicorn workers and the engine above (`10 + 20`), that is up to 150 connections — already over
+the default. Either shrink the pool, raise `max_connections`, or front the DB with pgbouncer.
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.pool import NullPool
+
+# Behind pgbouncer in transaction-pooling mode: SQLAlchemy must not pool, and asyncpg's
+# prepared-statement cache breaks because statements outlive the server-side session.
+engine = create_async_engine(
+    "postgresql+asyncpg://user:pass@pgbouncer:6432/app",
+    poolclass=NullPool,
+    connect_args={
+        "statement_cache_size": 0,
+        "server_settings": {"statement_timeout": "5000"},  # ms; kill runaway queries
+    },
+)
+```
+
+`pool_pre_ping=True` issues a cheap liveness check before handing out a connection, transparently
+replacing ones the DB or a load balancer dropped. `pool_recycle=1800` proactively closes
+connections older than 30 minutes to dodge idle-timeout resets. A `statement_timeout` is the
+backstop that stops one slow query from holding a connection forever.
+
+## See Also
+
+- [`production.md`](production.md) — worker/pool math, health checks, graceful shutdown.
+- [`postgresdb`](../../postgresdb/SKILL.md) — engine-level schema/index design, EXPLAIN, expand-contract migrations, PgBouncer pooling beneath this async layer.

package/skills/fastapi/references/production.md

@@ -0,0 +1,338 @@
+# Running FastAPI in production
+
+Shipping an async FastAPI service: ASGI server + worker math, structured JSON logging with
+request correlation, liveness vs readiness probes, graceful shutdown, pagination and caching at
+scale, performance defaults, and observability. For the container image and CI/CD pipeline,
+**See Also [`deployment`](../../deployment/SKILL.md)** — this file keeps only a Docker *note*.
+
+## ASGI server
+
+```bash
+# Dev: one process, autoreload on file change.
+uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
+
+# Prod: gunicorn process manager + uvicorn workers (install the `uvicorn-worker` package).
+# Worker count rule of thumb: (2 * CPU cores) + 1
+gunicorn app.main:app \
+  -k uvicorn_worker.UvicornWorker \
+  --workers 5 --timeout 30 --graceful-timeout 30 \
+  --bind 0.0.0.0:8000 --forwarded-allow-ips '*'
+```
+
+Never run `--reload` in prod: it watches the filesystem, spawns a reloader process, and
+disables key optimizations. gunicorn gives you a battle-tested process manager (restart on
+crash, graceful reload). The worker class lives in the standalone `uvicorn-worker` package
+(`pip install uvicorn-worker`) — the old `uvicorn.workers.UvicornWorker` was deprecated in
+uvicorn 0.30 and only emits a warning today. `uvicorn app.main:app --workers 5` is a fine
+gunicorn-free alternative.
+`--timeout` kills a worker stuck on a single request; `--graceful-timeout` is the drain window on
+shutdown. For async workloads the `(2×CPU)+1` formula is a starting point — profile real
+concurrency, since one async worker handles many in-flight requests.
+
+## Structured logging
+
+Emit JSON so logs are queryable, and bind a request id so every line in a request correlates.
+
+```python
+import logging
+
+import structlog
+
+structlog.configure(
+    processors=[
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.dict_tracebacks,
+        structlog.processors.JSONRenderer(),
+    ],
+    wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
+    cache_logger_on_first_use=True,
+)
+logger = structlog.get_logger()
+```
+
+```python
+import uuid
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.types import ASGIApp
+import structlog
+
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app: ASGIApp) -> None:
+        super().__init__(app)
+
+    async def dispatch(self, request: Request, call_next):
+        request_id = request.headers.get("X-Request-ID", str(uuid.uuid4()))
+        structlog.contextvars.bind_contextvars(request_id=request_id, path=request.url.path)
+        try:
+            response = await call_next(request)
+        finally:
+            structlog.contextvars.clear_contextvars()
+        response.headers["X-Request-ID"] = request_id
+        return response
+```
+
+`merge_contextvars` injects the bound `request_id` into every log emitted during the request,
+so a single trace id stitches the whole call together. Route uvicorn's own loggers (`uvicorn`,
+`uvicorn.access`) into the same JSON handler so access logs match your format; set log level by
+environment (`DEBUG` in dev, `INFO`/`WARNING` in prod).
+
+## Health & readiness
+
+Split liveness from readiness: liveness must not touch dependencies (a flaky DB should not kill
+the pod), readiness must verify them (a pod with a dead DB should leave the load balancer).
+
+```python
+from fastapi import APIRouter, Response, status
+from sqlalchemy import select
+
+from app.api.deps import DbSession
+
+router = APIRouter()
+
+
+@router.get("")
+async def liveness() -> dict[str, str]:
+    return {"status": "ok"}        # no dependencies — "is the process up?"
+
+
+@router.get("/ready")
+async def readiness(db: DbSession, response: Response) -> dict[str, str]:
+    try:
+        await db.execute(select(1))
+    except Exception:
+        response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+        return {"status": "unavailable"}
+    return {"status": "ready"}     # pings DB/cache — "can it serve traffic?"
+```
+
+In Kubernetes, a failing **liveness** probe restarts the pod; a failing **readiness** probe only
+removes it from the Service endpoints until it recovers. Wire `/health` to liveness and
+`/health/ready` to readiness accordingly.
+
+## Graceful shutdown
+
+```python
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from app.db.base import engine
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    yield
+    # Drain: stop accepting work, finish in-flight requests, then release resources.
+    await engine.dispose()         # close pooled DB connections so the DB sees a clean exit
+```
+
+On `SIGTERM`, gunicorn/uvicorn stop accepting new connections and give in-flight requests up to
+`--graceful-timeout` to finish before forcing exit; the lifespan teardown then runs. Make
+shutdown **idempotent** (safe if called twice) and ensure any in-process background work is
+drained or handed off — connection draining at the load balancer plus the graceful window
+prevents dropped requests during a rolling deploy.
+
+## Pagination at scale
+
+Offset pagination (`LIMIT/OFFSET`) is simple but degrades: large offsets force the DB to scan
+and discard rows, and concurrent inserts shift the window (duplicates/skips). Keyset (cursor)
+pagination stays O(page size) and stable.
+
+```python
+from base64 import urlsafe_b64decode, urlsafe_b64encode
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.user import User
+
+
+async def keyset_page(db: AsyncSession, after: UUID | None, limit: int) -> tuple[list[User], str | None]:
+    stmt = select(User).order_by(User.created_at.desc(), User.id.desc()).limit(limit)
+    if after is not None:
+        stmt = stmt.where(User.id < after)            # seek past the last id of the prev page
+    rows = list((await db.execute(stmt)).scalars().all())
+    next_cursor = urlsafe_b64encode(str(rows[-1].id).encode()).decode() if len(rows) == limit else None
+    return rows, next_cursor
+```
+
+Always include a unique tiebreaker (`id`) in the `ORDER BY` so the ordering is total and stable.
+`COUNT(*)` for a total is expensive on large tables — make it optional or approximate. Return a
+`meta`/`links` envelope with the encoded cursor and a `next`/`prev` link; the contract here is
+a REST-design concern, while the keyset SQL above is the FastAPI-side implementation.
+
+## Caching
+
+```python
+from hashlib import sha256
+
+import orjson
+import redis.asyncio as aioredis
+from fastapi import Response
+
+redis = aioredis.from_url("redis://redis:6379/0")
+
+
+async def cached_json(key: str, ttl: int, build):
+    cached = await redis.get(key)
+    if cached is not None:
+        return orjson.loads(cached)
+    value = await build()
+    await redis.set(key, orjson.dumps(value), ex=ttl)   # explicit TTL; invalidate on write
+    return value
+
+
+def set_etag(response: Response, payload: bytes) -> None:
+    etag = sha256(payload).hexdigest()
+    response.headers["ETag"] = f'"{etag}"'
+    response.headers["Cache-Control"] = "private, max-age=30"
+```
+
+Invalidate the cache key explicitly on any write to the underlying resource — TTL alone serves
+stale data. Guard against cache stampede (many misses recomputing at once) with a short lock
+(`SET key val NX EX`) or jittered TTLs. Use `@lru_cache` only for pure, process-local config
+like `get_settings`.
+
+## Performance
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import ORJSONResponse
+
+app = FastAPI(default_response_class=ORJSONResponse)   # orjson: faster, handles UUID/datetime
+```
+
+Behind a reverse proxy or load balancer, pass `--proxy-headers` (uvicorn) /
+`--forwarded-allow-ips` (gunicorn) so `X-Forwarded-For`/`-Proto` are trusted and `request.url`
+reflects the public scheme. Add `GZipMiddleware` for large JSON responses — it trades CPU for
+bandwidth, so only enable above a size threshold (`minimum_size=1000`). Never run sync/blocking
+I/O on the event loop; offload CPU-bound work with `await anyio.to_thread.run_sync(...)`. Profile
+hot paths with `py-spy record` against a running worker (no code changes, no restart).
+
+## Observability
+
+Instrument with OpenTelemetry (`opentelemetry-instrumentation-fastapi`) for distributed traces,
+or a Prometheus middleware (`prometheus-fastapi-instrumentator`) for metrics. Track the RED
+signals — **R**ate (requests/sec), **E**rrors (5xx ratio), **D**uration (p50/p95/p99 latency) —
+per route, and alert on error ratio and tail latency rather than averages.
+
+```python
+# from prometheus_fastapi_instrumentator import Instrumentator
+# Instrumentator().instrument(app).expose(app, endpoint="/metrics")
+```
+
+Keep this a pointer: pick one tracing and one metrics backend, export to your collector, and
+correlate traces with the `request_id` from the logging middleware.
+
+## Customizing the OpenAPI schema
+
+FastAPI builds the OpenAPI document lazily and caches it on `app.openapi_schema`. To inject
+extra metadata (servers, security schemes, a logo, tags) build the base schema once, mutate
+it, cache it, and **assign your function to `app.openapi`** — assigning the callable (not
+calling it eagerly) preserves the lazy-build-and-cache contract and lets `/docs` and
+`/openapi.json` pick it up.
+
+```python
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
+
+
+def customize_openapi(app: FastAPI) -> None:
+    def build() -> dict[str, Any]:
+        if app.openapi_schema:                 # serve the cached doc on later calls
+            return app.openapi_schema
+        schema = get_openapi(
+            title=app.title,
+            version=app.version,
+            description="Authenticate via the OAuth2 password flow at /auth/login.",
+            routes=app.routes,
+        )
+        schema["servers"] = [{"url": "https://api.example.com", "description": "production"}]
+        schema.setdefault("components", {})["securitySchemes"] = {
+            "bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"},
+        }
+        app.openapi_schema = schema
+        return schema
+
+    app.openapi = build  # type: ignore[method-assign]  # assign, don't call — keep it lazy
+```
+
+Call `customize_openapi(app)` inside `create_app()` before returning. **Bad** =
+`app.openapi_schema = customize_openapi(app)()` at import time — it forces the schema to
+build before every route is registered, so late `include_router` calls go missing from the
+docs.
+
+## AppError subclasses
+
+The base `AppError` + `register_exception_handlers` live in `SKILL.md` (Error handling &
+envelope). Each concrete failure is a subclass that fixes a `code` and HTTP status, so call
+sites stay declarative (`raise NotFoundError("User", ident)`) and the handler renders the
+shared envelope.
+
+```python
+from fastapi import status
+
+from app.exceptions import AppError
+
+
+class NotFoundError(AppError):
+    def __init__(self, resource: str, ident: str) -> None:
+        super().__init__(f"{resource} not found: {ident}", "not_found", 404)
+
+
+class ConflictError(AppError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, "conflict", status.HTTP_409_CONFLICT)
+
+
+class Unauthorized(AppError):
+    def __init__(self, message: str = "Authentication required") -> None:
+        super().__init__(message, "unauthorized", status.HTTP_401_UNAUTHORIZED)
+
+
+class Forbidden(AppError):
+    def __init__(self, message: str = "Insufficient permissions") -> None:
+        super().__init__(message, "forbidden", status.HTTP_403_FORBIDDEN)
+```
+
+`Unauthorized` and `Forbidden` are the ones raised by the auth/RBAC dependencies in
+[`security.md`](security.md). Prefer `NotFoundError` (404) over `Forbidden` (403) for private
+resources whose existence should not leak to an unauthorized caller.
+
+## Docker note
+
+```dockerfile
+FROM python:3.12-slim AS base
+ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
+RUN useradd --create-home --uid 10001 appuser
+WORKDIR /app
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev
+
+COPY app ./app
+USER appuser
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/health').status==200 else 1)"
+CMD ["uv", "run", "gunicorn", "app.main:app", "-k", "uvicorn_worker.UvicornWorker", "--workers", "5", "--bind", "0.0.0.0:8000"]
+```
+
+A slim base, a non-root user, a frozen lockfile install, an explicit `EXPOSE`, and a
+`HEALTHCHECK` hitting `/health`. For multi-stage builds, Compose, registries, and CI/CD,
+**See Also `deployment`** — do not duplicate the pipeline here.
+
+## See Also
+
+- [`database.md`](database.md) — pool sizing vs worker count, pgbouncer, statement timeouts.
+- [`security.md`](security.md) — TLS, proxy headers, security headers, secret injection.
+- [`deployment`](../../deployment/SKILL.md) — Dockerfile, Compose, CI/CD, container runtime.
+- [`postgresdb`](../../postgresdb/SKILL.md) — connection-pool ceilings, PgBouncer modes, partitioning at scale.