PostgreSQL Driver Decision
Status: accepted on 2026-10-24.
Decision
Use pg8000 for the synchronous PostgreSQL metadata and PGVector providers.
Keep DSN parsing and driver-specific transaction behavior in
memory.backend.postgres_driver so storage providers depend only on the
project's small internal connection adapter.
pg8000 is a production/stable, synchronous DB-API 2.0 driver released under
BSD-3-Clause. It supports Python 3.9 and newer, ships a platform-independent
pure-Python wheel, uses %s parameter binding, handles PostgreSQL arrays, and
does not require libpq or a compiler. Version 1.31.5 was released in
September 2025. See the pg8000 package record.
The adapter preserves postgres:// and postgresql:// URL configuration,
percent-encoded credentials and database names, host and port selection,
connection timeout, application name, startup parameters, and the common
sslmode values. It also commits a successful connection context and rolls
back a failed one, preserving the transaction contract previously supplied by
psycopg.
OpenTelemetry uses the generic DB-API integration because no maintained pg8000-specific instrumentor is available. The generic integration traces DB-API connect and cursor operations without capturing bound parameters. See the OpenTelemetry DB-API instrumentation.
Candidates
| Driver | License | Maintenance and Python support | Binary/native requirements | Compatibility result |
|---|---|---|---|---|
pg8000 |
BSD-3-Clause | Production/stable; latest evaluated release 1.31.5; Python 3.9+ | Pure Python; no libpq |
Selected. Synchronous DB-API and %s binding minimize provider changes. A small adapter is required for URL parsing and connection-context transactions. |
asyncpg |
Apache-2.0 | Production/stable; actively released; Python 3.9+ | Native-extension wheels or a source build | Rejected for this migration. It is asyncio-native, is not DB-API, and uses $1 binding, requiring a backend-wide async contract and SQL rewrite. See the asyncpg package record. |
PyGreSQL |
PostgreSQL License | Mature; actively released; Python 3.8-3.14 at evaluation | C extension and system libpq |
Rejected. It is permissive and synchronous, but adds native runtime/build requirements that the existing binary psycopg extra avoided. See the PyGreSQL package record. |
psycopg 3 |
LGPL-3.0-only | Production/stable; Python 3.10+ | Pure Python with libpq, or bundled binary extra |
Rejected because the runtime license is the reason for this migration. See the psycopg package record. |
Compatibility Notes
- Provider names, YAML fields, DSN fields, schemas, and stored data do not change.
sslmode=preferandsslmode=allowuse pg8000's default opportunistic TLS.require,verify-ca, andverify-fullcreate explicit TLS contexts.sslrootcert,sslcert, andsslkeyURL parameters are supported. Other unrecognized URL query parameters are sent as PostgreSQL startup parameters.- pg8000 reports server errors as a diagnostic dictionary in the first
exception argument. Conflict handling reads SQLSTATE
23505from that shape in addition to the previoussqlstateandpgcodeattributes. - The pure-Python protocol implementation can have different throughput than a C-backed libpq driver. The service currently opens short-lived synchronous connections, so deployment-specific load testing remains appropriate.
Validation
Unit coverage verifies DSN translation, TLS mode handling, commit/rollback,
pg8000's unique-violation shape, the optional dependency set, and generic
OpenTelemetry wiring. The existing live PostgreSQL and PGVector contract tests
remain the compatibility gate and run in CI with uv sync --extra postgres.
A fresh FOSSA scan should confirm that neither psycopg nor
psycopg-binary remains in the resolved dependency graph.