fastapi-sqlalchemy-pg-catalog: minimal repro sample for keploy/integrations#193

FastAPI + SQLAlchemy 2.x + psycopg2 + Postgres 13 sample built to
exercise the v3 dispatcher's simple-query ClassCatalog branch. The
sample's init.sql pre-creates the `project` table so SQLAlchemy's
Base.metadata.create_all skips CREATE TABLE at record time -- the
shape the dispatcher bug requires.

Used by the keploy/integrations Woodpecker lane
sqlalchemy-pg-catalog-postgres to assert that recorded `type: query`
mocks with `class: CATALOG` are consulted by the simple-query path,
not just the extended-query path.

Signed-off-by: Akash Kumar <meakash7902@gmail.com>

Author: AkashKumar7902

fastapi-sqlalchemy-pg-catalog/README.md

@@ -0,0 +1,87 @@
+# fastapi-sqlalchemy-pg-catalog
+
+Minimal FastAPI + SQLAlchemy 2.x + psycopg2 + Postgres 13 sample that
+reproduces the Postgres v3 dispatcher's simple-query `ClassCatalog`
+asymmetry (keploy/integrations#193).
+
+## What the bug looks like
+
+At app boot, SQLAlchemy's `Base.metadata.create_all(engine)` issues a
+`pg_catalog.pg_class` probe per declared table to decide whether to
+skip `CREATE TABLE`. With psycopg2 + parameter-less SQL the probe
+goes through the **simple-query** protocol path.
+
+In `pkg/postgres/v3/replayer/dispatcher/dispatcher.go`:
+
+* The **extended-query** path (`runEngineForPortal`, `case
+  match.ClassCatalog`) consults the recorded transactional mock first
+  and only falls back to the synthetic `Engines.Catalog.Execute` on
+  miss.
+* The **simple-query** path (`dispatchBySQLHash`, `case
+  match.ClassCatalog`) goes straight to the synthetic engine — even
+  though a recorded `type: query` mock with `class: CATALOG` and the
+  correct rows is sitting in `mocks.yaml`.
+
+With no `type: catalog` snapshot present, the synthetic engine
+answers `rows: 0, cc: "SELECT 0"`. SQLAlchemy reads zero rows as
+"table missing", issues `CREATE TABLE project ...`, and the
+transactional engine misses (because the recording never captured a
+CREATE TABLE — at record time the table already existed). The app
+worker dies with `psycopg2.DatabaseError: keploy-pg-v3: no recorded
+invocation matched`, every HTTP testcase that follows fails with
+connection-reset.
+
+## Reproducing locally
+
+```bash
+cd fastapi-sqlalchemy-pg-catalog
+docker compose build
+
+# Baseline (no keploy) — should pass
+docker compose up -d
+bash flow.sh
+docker compose down -v
+
+# Record
+( bash flow.sh > flow-record.log 2>&1 ) &
+sudo -E keploy record \
+  -c "docker compose -f docker-compose.yml up" \
+  --container-name pg-catalog-repro-app \
+  --cmd-type docker-compose \
+  --record-timer 60s
+
+# Replay (pre-fix: FAILS with "no recorded invocation matched" on CREATE TABLE)
+sudo -E keploy test \
+  -c "docker compose -f docker-compose.yml up" \
+  --container-name pg-catalog-repro-app \
+  --cmd-type docker-compose \
+  --apiTimeout 120 --delay 15 --disableMockUpload
+```
+
+## Layout
+
+| File                        | Purpose                                                                   |
+|-----------------------------|---------------------------------------------------------------------------|
+| `app/main.py`               | FastAPI app with one declarative `Project` model + lifespan create_all   |
+| `app/Dockerfile`            | Python 3.12-slim + requirements                                           |
+| `app/requirements.txt`      | fastapi, uvicorn, sqlalchemy 2.0.36, psycopg2-binary 2.9.10               |
+| `docker-compose.yml`        | postgres:13.22-alpine + app, app published at host port 8123             |
+| `init.sql`                  | Pre-creates the `project` table so record-time create_all is a no-op      |
+| `flow.sh`                   | Drives `GET /health` and `GET /projects` against the app                  |
+
+## Compose env knobs
+
+Set these to isolate concurrent runs (the CI lane drives a 3-cell
+matrix on one Docker daemon and overrides each):
+
+| Env var          | Default                 | Purpose                                  |
+|------------------|-------------------------|------------------------------------------|
+| `APP_CONTAINER`  | `pg-catalog-repro-app`  | App container name (keploy `--container-name`) |
+| `DB_CONTAINER`   | `pg-catalog-repro-db`   | Postgres container name                  |
+| `APP_HOST_PORT`  | `8123`                  | Host-side port mapped to app's 8000      |
+| `COMPOSE_NET`    | `reprnet`               | Docker network name                      |
+
+## Used by
+
+* `keploy/integrations` Woodpecker lane
+  `.woodpecker/sqlalchemy-pg-catalog-postgres.yml`

fastapi-sqlalchemy-pg-catalog/app/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY main.py .
+
+EXPOSE 8000
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--log-level", "info"]

fastapi-sqlalchemy-pg-catalog/app/main.py

@@ -0,0 +1,70 @@
+"""
+Minimal FastAPI + SQLAlchemy + psycopg2 app that exercises the Postgres
+v3 dispatcher's simple-query ClassCatalog branch via SQLAlchemy's
+``Base.metadata.create_all`` table-existence probe.
+
+Boot sequence:
+  1. SQLAlchemy creates an engine over psycopg2 (simple-query for
+     parameter-less SQL).
+  2. ``Base.metadata.create_all(engine)`` issues one
+     ``SELECT pg_catalog.pg_class.relname ...`` probe per declared table
+     to decide whether each ``CREATE TABLE`` should be skipped.
+  3. FastAPI starts serving requests.
+
+The probe is what hits the dispatcher's ``case match.ClassCatalog``
+branch in ``pkg/postgres/v3/replayer/dispatcher/dispatcher.go``
+(simple-query path, ``dispatchBySQLHash``).
+"""
+
+import logging
+import os
+import sys
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from sqlalchemy import Column, Integer, String, create_engine, select
+from sqlalchemy.orm import Session, declarative_base
+
+logging.basicConfig(
+    level=logging.INFO,
+    stream=sys.stdout,
+    format="%(asctime)s %(levelname)s %(name)s %(message)s",
+)
+log = logging.getLogger("repro")
+
+DATABASE_URL = os.environ["DATABASE_URL"]
+
+Base = declarative_base()
+
+
+class Project(Base):
+    __tablename__ = "project"
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String(100), nullable=False)
+
+
+engine = create_engine(DATABASE_URL, echo=True, future=True)
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    log.info("startup: running Base.metadata.create_all (pg_class probe expected)")
+    Base.metadata.create_all(engine)
+    log.info("startup: create_all complete")
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.get("/health")
+def health():
+    return {"ok": True}
+
+
+@app.get("/projects")
+def list_projects():
+    with Session(engine) as s:
+        rows = s.execute(select(Project)).scalars().all()
+        return [{"id": r.id, "name": r.name} for r in rows]

fastapi-sqlalchemy-pg-catalog/app/requirements.txt

@@ -0,0 +1,4 @@
+fastapi==0.115.0
+uvicorn==0.30.6
+sqlalchemy==2.0.36
+psycopg2-binary==2.9.10

fastapi-sqlalchemy-pg-catalog/docker-compose.yml

@@ -0,0 +1,34 @@
+services:
+  postgres:
+    image: postgres:13.22-alpine
+    container_name: ${DB_CONTAINER:-pg-catalog-repro-db}
+    environment:
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: testdb
+    volumes:
+      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
+    networks:
+      - reprnet
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d testdb"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+
+  app:
+    build: ./app
+    container_name: ${APP_CONTAINER:-pg-catalog-repro-app}
+    environment:
+      DATABASE_URL: postgresql+psycopg2://postgres:postgres@postgres:5432/testdb
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "${APP_HOST_PORT:-8123}:8000"
+    networks:
+      - reprnet
+
+networks:
+  reprnet:
+    name: ${COMPOSE_NET:-reprnet}
+    driver: bridge

fastapi-sqlalchemy-pg-catalog/flow.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Drives traffic during keploy record. Hits both endpoints.
+set -uo pipefail
+
+APP_HOST_PORT="${APP_HOST_PORT:-8123}"
+APP_URL="${APP_URL:-http://localhost:${APP_HOST_PORT}}"
+
+echo "[flow] waiting for app at $APP_URL ..."
+for i in $(seq 1 60); do
+  if curl -sf "$APP_URL/health" > /dev/null 2>&1; then
+    echo "[flow] app ready after ${i}s"
+    break
+  fi
+  sleep 1
+done
+
+echo "[flow] GET /health"
+curl -sS "$APP_URL/health" && echo
+
+echo "[flow] GET /projects"
+curl -sS "$APP_URL/projects" && echo
+
+echo "[flow] done"

fastapi-sqlalchemy-pg-catalog/init.sql

@@ -0,0 +1,15 @@
+-- Pre-create the `project` table so SQLAlchemy's create_all() sees it
+-- exists at record time and skips CREATE TABLE. This is what the bug
+-- (keploy/integrations#193) requires: at record time the pg_class
+-- probe answers "table exists", so CREATE TABLE is never sent and
+-- never recorded. At replay time, if the simple-query dispatcher path
+-- skips the recorded mock, the synthetic catalog engine returns zero
+-- rows, SQLAlchemy concludes "table missing", and issues an
+-- unrecorded CREATE TABLE -- which then misses the transactional
+-- engine, raises a DatabaseError, and kills app boot.
+CREATE TABLE IF NOT EXISTS project (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(100) NOT NULL
+);
+
+INSERT INTO project (name) VALUES ('seed') ON CONFLICT DO NOTHING;