Merge branch 'master' into oauth-pg18

Author: dvob

.devcontainer/Dockerfile

@@ -0,0 +1,9 @@
+FROM mcr.microsoft.com/devcontainers/go:2-1.25-trixie
+
+RUN apt-get update && apt-get install -y postgresql-common \
+    && yes | /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh \
+    && apt-get install -y postgresql-client-18 \
+    && rm -rf /var/lib/apt/lists/*
+
+USER vscode
+RUN go install golang.org/x/tools/cmd/goimports@latest

.devcontainer/devcontainer.json

@@ -0,0 +1,6 @@
+{
+	"name": "pgx",
+	"dockerComposeFile": "docker-compose.yml",
+	"service": "app",
+	"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}"
+}

.devcontainer/docker-compose.yml

@@ -0,0 +1,99 @@
+volumes:
+  postgres-14-data:
+  postgres-15-data:
+  postgres-16-data:
+  postgres-17-data:
+  postgres-18-data:
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+
+    volumes:
+      - ../..:/workspaces:cached
+
+    environment:
+      PGUSER: postgres
+      PGPASSWORD: postgres
+      PGDATABASE: pgx_test
+      PGHOST: localhost
+
+    # Overrides default command so things don't shut down after the process ends.
+    command: sleep infinity
+
+  postgres-14:
+    image: postgres:14
+    restart: unless-stopped
+    volumes:
+      - postgres-14-data:/var/lib/postgresql
+      - ../testsetup/postgresql_setup.sql:/docker-entrypoint-initdb.d/01-setup.sql:ro
+    network_mode: service:app
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: pgx_test
+      POSTGRES_HOSTNAME: localhost
+    command: postgres -c port=5414
+
+  postgres-15:
+    image: postgres:15
+    restart: unless-stopped
+    volumes:
+      - postgres-15-data:/var/lib/postgresql
+      - ../testsetup/postgresql_setup.sql:/docker-entrypoint-initdb.d/01-setup.sql:ro
+    network_mode: service:app
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: pgx_test
+      POSTGRES_HOSTNAME: localhost
+    command: postgres -c port=5415
+
+  postgres-16:
+    image: postgres:16
+    restart: unless-stopped
+    volumes:
+      - postgres-16-data:/var/lib/postgresql
+      - ../testsetup/postgresql_setup.sql:/docker-entrypoint-initdb.d/01-setup.sql:ro
+    network_mode: service:app
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: pgx_test
+      POSTGRES_HOSTNAME: localhost
+    command: postgres -c port=5416
+
+  postgres-17:
+    image: postgres:17
+    restart: unless-stopped
+    volumes:
+      - postgres-17-data:/var/lib/postgresql
+      - ../testsetup/postgresql_setup.sql:/docker-entrypoint-initdb.d/01-setup.sql:ro
+    network_mode: service:app
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: pgx_test
+      POSTGRES_HOSTNAME: localhost
+    command: postgres -c port=5417
+
+  postgres-18:
+    image: postgres:18
+    restart: unless-stopped
+    volumes:
+      - postgres-18-data:/var/lib/postgresql
+      - ../testsetup/postgresql_setup.sql:/docker-entrypoint-initdb.d/01-setup.sql:ro
+    network_mode: service:app
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: pgx_test
+      POSTGRES_HOSTNAME: localhost
+
+  cockroachdb:
+    image: cockroachdb/cockroach:v25.4.4
+    restart: unless-stopped
+    network_mode: service:app
+    command: start-single-node --insecure --listen-addr=127.0.0.1:26257 --store=type=mem,size=1024MiB

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: jackc

.github/workflows/ci.yml

@@ -14,18 +14,8 @@ jobs:
     strategy:
       matrix:
         go-version: ["1.24", "1.25"]
-        pg-version: [13, 14, 15, 16, 17, cockroachdb]
+        pg-version: [14, 15, 16, 17, 18, cockroachdb]
         include:
-          - pg-version: 13
-            pgx-test-database: "host=127.0.0.1 user=pgx_md5 password=secret dbname=pgx_test"
-            pgx-test-unix-socket-conn-string: "host=/var/run/postgresql dbname=pgx_test"
-            pgx-test-tcp-conn-string: "host=127.0.0.1 user=pgx_md5 password=secret dbname=pgx_test"
-            pgx-test-scram-password-conn-string: "host=127.0.0.1 user=pgx_scram password=secret dbname=pgx_test"
-            pgx-test-md5-password-conn-string: "host=127.0.0.1 user=pgx_md5 password=secret dbname=pgx_test"
-            pgx-test-plain-password-conn-string: "host=127.0.0.1 user=pgx_pw password=secret dbname=pgx_test"
-            pgx-test-tls-conn-string: "host=localhost user=pgx_ssl password=secret sslmode=verify-full sslrootcert=/tmp/ca.pem dbname=pgx_test"
-            pgx-ssl-password: certpw
-            pgx-test-tls-client-conn-string: "host=localhost user=pgx_sslcert sslmode=verify-full sslrootcert=/tmp/ca.pem sslcert=/tmp/pgx_sslcert.crt sslkey=/tmp/pgx_sslcert.key dbname=pgx_test"
           - pg-version: 14
             pgx-test-database: "host=127.0.0.1 user=pgx_md5 password=secret dbname=pgx_test"
             pgx-test-unix-socket-conn-string: "host=/var/run/postgresql dbname=pgx_test"
@@ -82,10 +72,10 @@ jobs:
 
     steps:
       - name: Check out code into the Go module directory
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Go ${{ matrix.go-version }}
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
           go-version: ${{ matrix.go-version }}
 
@@ -147,10 +137,10 @@ jobs:
           database: pgx_test
 
       - name: Check out code into the Go module directory
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Go ${{ matrix.go-version }}
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
           go-version: ${{ matrix.go-version }}
 
@@ -162,7 +152,10 @@ jobs:
         shell: bash
 
       - name: Test
-        # parallel testing is disabled because somehow parallel testing causes Github Actions to kill the runner.
-        run: go test -parallel=1 -race  ./...
+        # Parallel testing is disabled because somehow parallel testing causes Github Actions to kill the runner.
+        # Disabling CGO because that is not working on the Windows runner. Apparently, we could install MingW and set up
+        # CGO to work, but disabling CGO takes less CI time. Without CGO, we also must not use the race detector.
+        run: go test -parallel=1 ./...
         env:
+          CGO_ENABLED: 0
           PGX_TEST_DATABASE: ${{ steps.postgres.outputs.connection-uri }}

.golangci.yml

@@ -1,9 +1,14 @@
 # See for configurations: https://golangci-lint.run/usage/configuration/
-version: 2
+version: "2"
+
+linters:
+  default: none
+  enable:
+    - govet
+    - ineffassign
 
 # See: https://golangci-lint.run/usage/formatters/
 formatters:
-  default: none
   enable:
     - gofmt # https://pkg.go.dev/cmd/gofmt
     - gofumpt # https://github.com/mvdan/gofumpt

CHANGELOG.md

@@ -1,3 +1,27 @@
+# 5.8.0 (December 26, 2025)
+
+* Require Go 1.24+
+* Remove golang.org/x/crypto dependency
+* Add OptionShouldPing to control ResetSession ping behavior (ilyam8)
+* Fix: Avoid overflow when MaxConns is set to MaxInt32
+* Fix: Close batch pipeline after a query error (Anthonin Bonnefoy)
+* Faster shutdown of pgxpool.Pool background goroutines (Blake Gentry)
+* Add pgxpool ping timeout (Amirsalar Safaei)
+* Fix: Rows.FieldDescriptions for empty query
+* Scan unknown types into *any as string or []byte based on format code
+* Optimize pgtype.Numeric (Philip Dubé)
+* Add AfterNetConnect hook to pgconn.Config
+* Fix: Handle for preparing statements that fail during the Describe phase
+* Fix overflow in numeric scanning (Ilia Demianenko)
+* Fix: json/jsonb sql.Scanner source type is []byte
+* Migrate from math/rand to math/rand/v2 (Mathias Bogaert)
+* Optimize internal iobufpool (Mathias Bogaert)
+* Optimize stmtcache invalidation (Mathias Bogaert)
+* Fix: missing error case in interval parsing (Maxime Soulé)
+* Fix: invalidate statement/description cache in Exec (James Hartig)
+* ColumnTypeLength method return the type length for varbit type (DengChan)
+* Array and Composite codecs handle typed nils
+
 # 5.7.6 (September 8, 2025)
 
 * Use ParseConfigError in pgx.ParseConfig and pgxpool.ParseConfig (Yurasov Ilia)

CLAUDE.md

@@ -0,0 +1,73 @@
+# 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.24+ 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
+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** — use `goimports -w .` to format code. 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.24/1.25 × PostgreSQL 14-18 + CockroachDB, on Linux and Windows. Race detector enabled on Linux only.

CONTRIBUTING.md

@@ -10,14 +10,31 @@ proposal. This will help to ensure your proposed change has a reasonable chance
 Adding a dependency is a big deal. While on occasion a new dependency may be accepted, the default answer to any change
 that adds a dependency is no.
 
+## AI
+
+Using AI is acceptable (not that it can really be stopped) under one the following conditions.
+
+* AI was used, but you deeply understand the code and you can answer questions regarding your change. You are not going
+  to answer questions with "I don't know", AI did it. You are not going to "answer" questions by relaying them to your
+  agent. This is wasteful of the code reviewer's time.
+* AI was used to solve a problem without your deep understanding. This can still be a good starting point for a fix or
+  feature. But you need to clearly state that this is an AI proposal. You should include additional information such as
+  the AI used and what prompts were used. You should also be aware that large, complicated, or subtle changes may be
+  rejected simply because the reviewer is not confident in a change that no human understands.
+
 ## Development Environment Setup
 
 pgx tests naturally require a PostgreSQL database. It will connect to the database specified in the `PGX_TEST_DATABASE`
 environment variable. The `PGX_TEST_DATABASE` environment variable can either be a URL or key-value pairs. In addition,
 the standard `PG*` environment variables will be respected. Consider using [direnv](https://github.com/direnv/direnv) to
 simplify environment variable handling.
 
-### Using an Existing PostgreSQL Cluster
+### Devcontainer
+
+The easiest way to start development is with the included devcontainer. It includes containers for each supported
+PostgreSQL version as well as CockroachDB. `./test.sh all` will run the tests against all database types.
+
+### Using an Existing PostgreSQL Cluster Outside of a Devcontainer
 
 If you already have a PostgreSQL development server this is the quickest way to start and run the majority of the pgx
 test suite. Some tests will be skipped that require server configuration changes (e.g. those testing different
@@ -49,7 +66,7 @@ go test ./...
 
 This will run the vast majority of the tests, but some tests will be skipped (e.g. those testing different connection methods).
 
-### Creating a New PostgreSQL Cluster Exclusively for Testing
+### Creating a New PostgreSQL Cluster Exclusively for Testing Outside of a Devcontainer
 
 The following environment variables need to be set both for initial setup and whenever the tests are run. (direnv is
 highly recommended). Depending on your platform, you may need to change the host for `PGX_TEST_UNIX_SOCKET_CONN_STRING`.

README.md

@@ -92,7 +92,7 @@ See the presentation at Golang Estonia, [PGX Top to Bottom](https://www.youtube.
 
 ## Supported Go and PostgreSQL Versions
 
-pgx supports the same versions of Go and PostgreSQL that are supported by their respective teams. For [Go](https://golang.org/doc/devel/release.html#policy) that is the two most recent major releases and for [PostgreSQL](https://www.postgresql.org/support/versioning/) the major releases in the last 5 years. This means pgx supports Go 1.24 and higher and PostgreSQL 13 and higher. pgx also is tested against the latest version of [CockroachDB](https://www.cockroachlabs.com/product/).
+pgx supports the same versions of Go and PostgreSQL that are supported by their respective teams. For [Go](https://golang.org/doc/devel/release.html#policy) that is the two most recent major releases and for [PostgreSQL](https://www.postgresql.org/support/versioning/) the major releases in the last 5 years. This means pgx supports Go 1.24 and higher and PostgreSQL 14 and higher. pgx also is tested against the latest version of [CockroachDB](https://www.cockroachlabs.com/product/).
 
 ## Version Policy
 
@@ -120,6 +120,7 @@ pgerrcode contains constants for the PostgreSQL error codes.
 
 * [github.com/jackc/pgx-gofrs-uuid](https://github.com/jackc/pgx-gofrs-uuid)
 * [github.com/jackc/pgx-shopspring-decimal](https://github.com/jackc/pgx-shopspring-decimal)
+* [github.com/ColeBurch/pgx-govalues-decimal](https://github.com/ColeBurch/pgx-govalues-decimal)
 * [github.com/twpayne/pgx-geos](https://github.com/twpayne/pgx-geos) ([PostGIS](https://postgis.net/) and [GEOS](https://libgeos.org/) via [go-geos](https://github.com/twpayne/go-geos))
 * [github.com/vgarvardt/pgx-google-uuid](https://github.com/vgarvardt/pgx-google-uuid)