Postgres, and a client that shouldn’t be reborn every request

Wiring up Postgres was the easy part: a table for exchanges (prompt, response, timestamp) and a DatabaseClient wrapping a SQLAlchemy connection. The first version created a new client and a new connection on every single request. It worked, but it’s the wrong shape: a real app should open one connection when it starts and reuse it, not pay connection overhead on every prompt.

The fix uses FastAPI’s lifespan context manager: the client is created once, as a global, when the app starts, and closed once, when it stops. It’s a small thing, but the difference between “works in a demo” and “works under real traffic.” is very important.

db_client = DatabaseClient()

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    db_client.close()

app = FastAPI(lifespan=lifespan)

One more bug here, easy to miss: the Postgres container’s credentials were hardcoded directly in docker-compose.yml (admin/example), while the backend correctly read them from .env. They happened to match, so everything worked right up until someone changes .env and the two sides silently disagree. This was fixed by making the database service read the same environment variables as the backend.

Teaching the backend to delegate

The interesting part: how does a Python backend running in a container actually talk to Claude Code?

The obvious-looking answer is to mount the host’s ~/.claude directory into the container but it turns out to be the wrong one. The real mechanism, already proven in a different part of this same infrastructure (a local AI agent I run for other things), is simpler: claude setup-token generates a long-lived OAuth token once and the CLI picks it up from a CLAUDE_CODE_OAUTH_TOKEN environment variable. No mounted credentials directory, no interactive login inside the container.

The rest is a normal Docker build: claude installed via npm (Node’s official Alpine build, chosen specifically to avoid repeating a glibc-vs-musl binary compatibility trap I’d already hit once with a different tool), a persistent named volume for the CLI’s own config so it doesn’t reset on every restart, and a minimal, empty working directory. For now, there is no need for a real project, since the backend is using Claude Code as a text-generation engine here, not as a coding agent that needs to touch real files.

Delegation itself is a subprocess call, deliberately async so one slow request doesn’t block every other one:

proc = await asyncio.create_subprocess_exec(
    "claude", "-p", full_prompt,
    cwd="/workspace",
    stdout=asyncio.subprocess.PIPE,
    stderr=asyncio.subprocess.PIPE,
)
stdout, stderr = await proc.communicate()

It worked on the first real test. Measured round-trip for a simple prompt: about 3.6 seconds for a full CLI process starting up. Worth knowing before this becomes the path for anything latency-sensitive.

The bugs that don’t announce themselves

The endpoint needed conversation history. I’ve decided to get the last N exchanges and fed them back in as context so the model isn’t starting cold every time. This is where the quiet bugs live.

Bug one, the loud one. The query to fetch recent exchanges was written as:

SELECT (prompt, response, created_at) FROM exchanges ...

Those parentheses around the column list look harmless. My wrong assumption was to prevent SQL Injection attacks without knowing Postgres reads that as one composite column, not three separate ones. The first test request worked fine, because there was no history yet to fetch. The second one crashed:

AttributeError: Could not locate column in row for column 'prompt'

A one-word explanation, once you see it: no parentheses, three real columns.

Bug two, the silent one. The timestamp was meant to be captured the moment a request arrives right before it goes anywhere near the LLM. The code looked right:

response = ChatResponse(
    prompt=msg.prompt,
    response=await call_llm(msg.prompt),   # ~3.6s
    created_at=datetime.now(timezone.utc),
)

But… Python evaluates keyword arguments in the order they’re written, not by name. The created_at argument is the last one on the page, so it’s the last thing evaluated after the multi-second LLM call already finished. The timestamp was quietly measuring the wrong moment. Fixed by capturing it as its own variable, first line of the function, before anything else runs.

Bug three, the one that ate its own fix. Recent-history queries naturally come back newest-first. Fed straight into a prompt, that reads backwards to the model: the last message first and the first message last. The fix is to reverse the list in Python before building the context, except the first attempt changed the SQL to sort oldest-first and added the Python-side reverse. Confirmed by literally asking the model to recite the conversation back in order and it gave the order correctly, 1 through 4.

None of these three would show up in a five-minute demo. Two of them only show up once there’s enough data or enough history for the wrong behavior to matter. It is exactly the kind of bug that’s cheap to fix now and expensive to debug later, in production, with a confused conversation to untangle.

What’s next

Backend and database talk to each other, and the backend talks to Claude Code. What’s still missing is a way for a person to talk to any of it. Task 4 is the chat UI. No deadline on when that happens; it happens when it happens.

→ Full build series · Project page

A UI, and a bug that only shows up in markdown

The chat UI itself is unremarkable in the good way: a controlled input, Enter to send, Shift+Enter for a new line, disabled while a response is pending. The more interesting part is what happens to the response once it arrives. Claude Code’s replies come back as markdown and rendering that as plain text loses all of it. Using the react-markdown plus remark-gfm modules fixed that in about ten lines; user messages stay plain text, since they’re not meant to be formatted.

The bug that only exists in the built version

Docker Compose was already running backend, frontend, and Postgres separately in dev (pnpm dev, docker compose up for the rest). The actual test: a full docker compose up from nothing, then a real browser hitting :3000 is where things fell apart, in two layers.

The first layer was the one I expected: no CORS headers on the backend, so a browser calling :8000 directly from :3000 gets blocked. The fix was small: use the CORSMiddleware module scoped to a FRONTEND_ORIGIN environment variable. CORS stands for Cross-Origin Resource Sharing and is a security feature used by web browsers to control how a website on one domain can request and access resources from a different domain. It was chosen over a reverse proxy specifically because this app still isn’t exposed publicly; a proxy earns its complexity once that changes, not before.

The second layer was quieter, and CORS headers wouldn’t have fixed it. The frontend’s fetch('/chat') and fetch('/history') calls use relative paths. In pnpm dev, Vite’s own proxy rewrites those transparently to :8000 so it looked correct. But the Docker frontend serves a static production build (serve -s dist), with no proxy layer at all. A relative /history request there just hits the frontend’s own static server, finds no matching file, and falls through to index.html. This caused the app’s own shell to be silently returned in place of JSON. No error, no crash, just the wrong response shape. It surfaced by literally running curl :3000/history and noticing HTML come back where JSON should have been. This is the kind of gap that only shows up when you run the real, built artifact, not when you re-read the code that produced it.

The fix: bake the backend’s real origin into the static build itself as a VITE_API_BASE_URL build argument threaded through frontend/Dockerfile and docker-compose.yml. Vite inlines VITE_* variables at build time, so the compiled JS calls the backend directly, origin and all, with no proxy required.

Conversation history, for real this time

The exchanges table always had an id column but nothing before now had ever selected it. Adding it to the response model was the easy part; three endpoints followed naturally: GET /history for the full conversation, DELETE /history/{id} for a single exchange, and DELETE /history for everything.

The UI treats a prompt/response pair as the actual unit of storage, which makes it the natural unit of deletion too so history loads on page mount (a refresh won’t lose the conversation in this way), each exchange gets its own delete control, and clearing everything sits behind an explicit confirm/cancel step, since there’s no undo once it’s gone.

Tests, so the browser stops being the test

Every one of the bugs above and the two from Part 3 were caught by hand: reading a stack trace, running curl, opening a real browser. That works, but it doesn’t scale, and it doesn’t repeat automatically. The last piece of v1 was a test suite built specifically so a future change can be verified without a browser at all.

The one real decision here was the backend’s test database: a disposable Postgres, not SQLite. It would have been faster to fake it but the raw SQL in this codebase is Postgres-specific, and two of the bugs already found (the composite-column SELECT and the timestamp-ordering one) are exactly the kind that a friendlier substitute database could paper over instead of catching. Testing against the real thing paid for itself immediately: writing the fixtures surfaced a genuine deadlock where the app’s read methods never closed their implicit transaction, which was harmless in a long-lived production connection but left a lock held just long enough to hang the next test’s cleanup. Something SQLite would never have shown at all. This could’ve been prevented by explictly calling SQLAlchemy’s own .commit() on the connection after a query was called.

The two regression tests for Part 3’s bugs weren’t just written to check current behavior. This was done so each one can be verified by literally reintroducing the original bug, watching the test fail, then reverting it. The frontend side is smaller in comparison: Vitest and React Testing Library, fetch mocked, covering send-and-render, per-exchange delete, and the clear-all confirmation gate.

Where it stands

The v1 is done: the chat, the persisted and deletable history, a Docker Compose stack that survives a clean checkout, and a test suite that means the next change doesn’t have to be verified by hand. What comes after this is a larger, deliberately undated idea. Turning this into something closer to a content system than a chat demo and it stays exactly that: available whenever there’s real appetite for it, not scheduled. This would include a deliberate stage for automatic deployment of the app over to Kubernetes, using a lightwight version of it called K3s.

All posts in this series → · Project page →