go-postgresql is a framework for building PostgreSQL compatible servers in Go.
go-postgresql implements the PostgreSQL wire protocol and automatically interprets the major message flow (startup, authentication, parameter/status, etc.). This lets you focus on implementing your own DDL (Data Definition Language) and DML (Data Manipulation Language) logic instead of re‑implementing the protocol machinery.
All startup and system messages are handled for you. Provide implementations for the SQL execution interfaces and you have a functioning PostgreSQL‑compatible server.
Core capabilities provided by go-postgresql:
- Full PostgreSQL wire protocol handling (startup, authentication prompts, message flow, ready states)
- Pluggable SQL execution via the
go-sqlparserexecutor interface - Extensible authentication (password / TLS client cert integration via
go-authenticator) - Structured error response generation matching PostgreSQL fields
- COPY (simple) stream handling helpers
- Prepared statement and portal management
- Tracing hooks (span start/finish) using
go-tracing - Modular connection and message reader abstractions
- Integration helpers for system catalog style queries
Optional integrations (via related Cybergarage projects):
- Test harness utilities (
go-sqltest) - Safe numeric and type conversion (
go-safecast) - SASL authentication flows (
go-sasl) - Deterministic logging and debugging (
go-logger)
Representative example projects built with go-postgresql:
- go-postgresqld – Minimal in‑memory server example.
- go-sqlserver – Alternative SQL server implementation.
- PuzzleDB – Pluggable multi‑model database.
Run the example in‑memory server (go-postgresqld) locally:
docker run --rm -p 5432:5432 cybergarage/go-postgresqld:latestConnect using psql (requires it installed):
psql "host=127.0.0.1 port=5432 user=postgres sslmode=disable"Run the PuzzleDB example image:
docker run --rm -p 5432:5432 cybergarage/puzzledb:latestTip: Use -e POSTGRES_INIT=... (if the image supports custom init scripts) or mount volumes for persistence in extended setups.
go-postgresql is developed in collaboration with other Cybergarage libraries:
- PostgreSQL
- Frontend/Backend Protocol
- Additional links in doc/references.md