From 4cb6109f05f0928e7574d96b072d7e090afe527b Mon Sep 17 00:00:00 2001
From: abhinav-galileo <abhinav-galileo@users.noreply.github.com>
Date: Tue, 16 Jun 2026 22:33:43 +0530
Subject: [PATCH 1/2] fix(server): declare plain psycopg dependency

---
 server/pyproject.toml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/server/pyproject.toml b/server/pyproject.toml
index 4779e4fb..0661d9ac 100644
--- a/server/pyproject.toml
+++ b/server/pyproject.toml
@@ -16,7 +16,7 @@ dependencies = [
     "pydantic>=2.5.0",
     "pydantic-settings>=2.1.0",
     "SQLAlchemy>=2.0.0",
-    "psycopg[binary]>=3.1",
+    "psycopg>=3.1",
     "asyncpg>=0.29.0",
     "greenlet>=3.0",
     "alembic>=1.13.0",
@@ -34,6 +34,8 @@ license = {text = "Apache-2.0"}
 
 [project.optional-dependencies]
 galileo = ["agent-control-evaluator-galileo>=7.5.0"]
+binary = ["psycopg[binary]>=3.1"]
+c = ["psycopg[c]>=3.1"]
 
 [dependency-groups]
 dev = [

From 93c9f32791b4ddb4f23aed9598ce786bb9813430 Mon Sep 17 00:00:00 2001
From: abhinav-galileo <abhinav-galileo@users.noreply.github.com>
Date: Wed, 17 Jun 2026 15:07:57 +0530
Subject: [PATCH 2/2] fix(server): install libpq for plain psycopg

---
 .github/workflows/ci.yml             |  5 +++++
 .github/workflows/docker-publish.yml |  9 +++++++++
 server/Dockerfile                    |  5 +++++
 server/README.md                     | 10 ++++++++++
 4 files changed, 29 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0bdbac1f..71cb3cbf 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -42,6 +42,11 @@ jobs:
       - name: Setup uv
         uses: astral-sh/setup-uv@v4
 
+      - name: Install libpq runtime
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libpq5
+
       - name: Show versions
         run: |
           uv --version
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
index 4413809f..2a781674 100644
--- a/.github/workflows/docker-publish.yml
+++ b/.github/workflows/docker-publish.yml
@@ -54,8 +54,17 @@ jobs:
           context: .
           file: server/Dockerfile
           platforms: linux/amd64
+          load: ${{ github.event_name == 'pull_request' }}
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
+
+      - name: Smoke test psycopg runtime
+        if: github.event_name == 'pull_request'
+        env:
+          IMAGE_TAGS: ${{ steps.meta.outputs.tags }}
+        run: |
+          image="$(printf '%s\n' "$IMAGE_TAGS" | head -n 1)"
+          docker run --rm --entrypoint python "$image" -c 'import os; import psycopg; from psycopg import pq; assert os.environ["PSYCOPG_IMPL"] == "python"; assert pq.version() > 0; print(f"psycopg {psycopg.__version__}, libpq {pq.version()}")'
diff --git a/server/Dockerfile b/server/Dockerfile
index 30db201a..7d21f115 100644
--- a/server/Dockerfile
+++ b/server/Dockerfile
@@ -28,6 +28,10 @@ FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
 
 WORKDIR /app
 
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libpq5 \
+    && rm -rf /var/lib/apt/lists/*
+
 # Configure uv environment variables
 ENV UV_COMPILE_BYTECODE=1
 ENV UV_LINK_MODE=copy
@@ -75,6 +79,7 @@ ENV PATH="/app/.venv/bin:$PATH"
 # Set default environment variables
 ENV AGENT_CONTROL_HOST=0.0.0.0
 ENV AGENT_CONTROL_PORT=8000
+ENV PSYCOPG_IMPL=python
 
 # Expose the port
 EXPOSE 8000
diff --git a/server/README.md b/server/README.md
index 368e4ae1..7c56e446 100644
--- a/server/README.md
+++ b/server/README.md
@@ -42,6 +42,16 @@ agent-control-migrate current
 agent-control-migrate upgrade head
 ```
 
+## PostgreSQL driver runtime
+
+`agent-control-server` depends on plain `psycopg`. The published Docker image
+installs Debian `libpq5` and sets `PSYCOPG_IMPL=python` so the server uses
+psycopg's Python implementation with the OS libpq library.
+
+For wheel-based deployments outside Docker, either install the OS libpq runtime
+package for your platform, or install `agent-control-server[binary]` if you want
+psycopg's bundled binary package.
+
 ## Configuration
 
 Server configuration is driven by environment variables (database, auth, observability, evaluators). For the full list and examples, see the docs.