73 lines
3.8 KiB
Markdown
73 lines
3.8 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
pgx is a PostgreSQL driver and toolkit for Go (`github.com/jackc/pgx/v5`). It provides both a native PostgreSQL interface and a `database/sql` compatible driver. Requires Go 1.25+ and supports PostgreSQL 14+ and CockroachDB.
|
||
|
||
## Build & Test Commands
|
||
|
||
```bash
|
||
# Run all tests (requires PGX_TEST_DATABASE to be set)
|
||
go test ./...
|
||
|
||
# Run a specific test
|
||
go test -run TestFunctionName ./...
|
||
|
||
# Run tests for a specific package
|
||
go test ./pgconn/...
|
||
|
||
# Run tests with race detector
|
||
go test -race ./...
|
||
|
||
# DevContainer: run tests against specific PostgreSQL versions
|
||
./test.sh pg18 # Default: PostgreSQL 18
|
||
./test.sh pg16 -run TestConnect # Specific test against PG16
|
||
./test.sh crdb # CockroachDB
|
||
./test.sh all # All targets (pg14-18 + crdb)
|
||
|
||
# Format (always run after making changes)
|
||
goimports -w .
|
||
|
||
# Lint
|
||
golangci-lint run ./...
|
||
```
|
||
|
||
## Test Database Setup
|
||
|
||
Tests require `PGX_TEST_DATABASE` environment variable. In the devcontainer, `test.sh` handles this. For local development:
|
||
|
||
```bash
|
||
export PGX_TEST_DATABASE="host=localhost user=postgres password=postgres dbname=pgx_test"
|
||
```
|
||
|
||
The test database needs extensions: `hstore`, `ltree`, and a `uint64` domain. See `testsetup/postgresql_setup.sql` for full setup. Many tests are skipped unless additional `PGX_TEST_*` env vars are set (for TLS, SCRAM, MD5, unix socket, PgBouncer testing).
|
||
|
||
## Architecture
|
||
|
||
The codebase is a layered architecture, bottom-up:
|
||
|
||
- **pgproto3/** — PostgreSQL wire protocol v3 encoder/decoder. Defines `FrontendMessage` and `BackendMessage` types for every protocol message.
|
||
- **pgconn/** — Low-level connection layer (roughly libpq-equivalent). Handles authentication, TLS, query execution, COPY protocol, and notifications. `PgConn` is the core type.
|
||
- **pgx** (root package) — High-level query interface built on `pgconn`. Provides `Conn`, `Rows`, `Tx`, `Batch`, `CopyFrom`, and generic helpers like `CollectRows`/`ForEachRow`. Includes automatic statement caching (LRU).
|
||
- **pgtype/** — Type system mapping between Go and PostgreSQL types (70+ types). Key interfaces: `Codec`, `Type`, `TypeMap`. Custom types (enums, composites, domains) are registered through `TypeMap`.
|
||
- **pgxpool/** — Concurrency-safe connection pool built on `puddle/v2`. `Pool` is the main type; wraps `pgx.Conn`.
|
||
- **stdlib/** — `database/sql` compatibility adapter.
|
||
|
||
Supporting packages:
|
||
- **internal/stmtcache/** — Prepared statement cache with LRU eviction
|
||
- **internal/sanitize/** — SQL query sanitization
|
||
- **tracelog/** — Logging adapter that implements tracer interfaces
|
||
- **multitracer/** — Composes multiple tracers into one
|
||
- **pgxtest/** — Test helpers for running tests across connection types
|
||
|
||
## Key Design Conventions
|
||
|
||
- **Semantic versioning** — strictly followed. Do not break the public API (no removing or renaming exported types, functions, methods, or fields; no changing function signatures).
|
||
- **Minimal dependencies** — adding new dependencies is strongly discouraged (see CONTRIBUTING.md).
|
||
- **Context-based** — all blocking operations take `context.Context`.
|
||
- **Tracer interfaces** — observability via `QueryTracer`, `BatchTracer`, `CopyFromTracer`, `PrepareTracer` on `ConnConfig.Tracer`.
|
||
- **Formatting** — always run `goimports -w .` after making changes to ensure code is properly formatted. CI checks formatting via `gofmt -l -s -w . && git diff --exit-code`. `gofumpt` with extra rules is also enforced via `golangci-lint`.
|
||
- **Linters** — `govet` and `ineffassign` only (configured in `.golangci.yml`).
|
||
- **CI matrix** — tests run against Go 1.25/1.26 × PostgreSQL 14-18 + CockroachDB, on Linux and Windows. Race detector enabled on Linux only.
|