From c1002d2a65eee739ee0c82cbe8dc13ed50ca996e Mon Sep 17 00:00:00 2001 From: Tubelight30 Date: Wed, 15 Apr 2026 14:59:14 +0530 Subject: [PATCH 1/3] doc: add minimal Docker Postgres setup Document a minimal Docker-based PostgreSQL setup for running the test suite, including notes about go test caching and timezone-related timestamptz failures. --- CONTRIBUTING.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2283ae670..ebf436ebb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,6 +34,35 @@ simplify environment variable handling. 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 PostgreSQL in Docker (Minimal) + +If you prefer not to install PostgreSQL locally, you can run a minimal PostgreSQL instance in Docker and point +`PGX_TEST_DATABASE` at it. This is enough to run most of the test suite with `go test ./...`. + +From the repository root: + +``` +docker run --name pgx-pg -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres \ + -p 5432:5432 -d postgres:18 + +docker exec -it pgx-pg createdb -U postgres pgx_test +docker exec -i pgx-pg psql -U postgres -d pgx_test < testsetup/postgresql_setup.sql + +export PGX_TEST_DATABASE="host=localhost port=5432 user=postgres password=postgres dbname=pgx_test" +go test ./... +``` + +Notes: + +* If tests appear to pass unexpectedly quickly and you see `(cached)`, force a re-run with `go test -count=1 ./...`. +* Docker PostgreSQL images often default to `TimeZone=UTC` while `time.Local` uses your host timezone. If you see + timestamp-with-timezone related test failures (e.g. a `timestamptz` value round-tripping with a different offset), + you can run the tests in UTC with: + +``` +TZ=UTC go test -count=1 ./... +``` + ### 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 From 98f49f36d8ad3ffb18d33d1536bf646741b0d946 Mon Sep 17 00:00:00 2001 From: Tubelight30 Date: Wed, 15 Apr 2026 15:02:03 +0530 Subject: [PATCH 2/3] Revert "doc: add minimal Docker Postgres setup" This reverts commit c1002d2a65eee739ee0c82cbe8dc13ed50ca996e. --- CONTRIBUTING.md | 29 ----------------------------- 1 file changed, 29 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ebf436ebb..2283ae670 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,35 +34,6 @@ simplify environment variable handling. 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 PostgreSQL in Docker (Minimal) - -If you prefer not to install PostgreSQL locally, you can run a minimal PostgreSQL instance in Docker and point -`PGX_TEST_DATABASE` at it. This is enough to run most of the test suite with `go test ./...`. - -From the repository root: - -``` -docker run --name pgx-pg -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres \ - -p 5432:5432 -d postgres:18 - -docker exec -it pgx-pg createdb -U postgres pgx_test -docker exec -i pgx-pg psql -U postgres -d pgx_test < testsetup/postgresql_setup.sql - -export PGX_TEST_DATABASE="host=localhost port=5432 user=postgres password=postgres dbname=pgx_test" -go test ./... -``` - -Notes: - -* If tests appear to pass unexpectedly quickly and you see `(cached)`, force a re-run with `go test -count=1 ./...`. -* Docker PostgreSQL images often default to `TimeZone=UTC` while `time.Local` uses your host timezone. If you see - timestamp-with-timezone related test failures (e.g. a `timestamptz` value round-tripping with a different offset), - you can run the tests in UTC with: - -``` -TZ=UTC go test -count=1 ./... -``` - ### 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 From 13488ca5feb310ffb9b0b4b6d06eb118b96d2e1c Mon Sep 17 00:00:00 2001 From: Tubelight30 Date: Wed, 15 Apr 2026 15:04:40 +0530 Subject: [PATCH 3/3] doc: add minimal Docker Postgres setup Document a minimal Docker-based PostgreSQL setup for running the test suite, including notes about go test caching and timezone-related timestamptz failures. --- CONTRIBUTING.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2283ae670..ebf436ebb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,6 +34,35 @@ simplify environment variable handling. 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 PostgreSQL in Docker (Minimal) + +If you prefer not to install PostgreSQL locally, you can run a minimal PostgreSQL instance in Docker and point +`PGX_TEST_DATABASE` at it. This is enough to run most of the test suite with `go test ./...`. + +From the repository root: + +``` +docker run --name pgx-pg -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres \ + -p 5432:5432 -d postgres:18 + +docker exec -it pgx-pg createdb -U postgres pgx_test +docker exec -i pgx-pg psql -U postgres -d pgx_test < testsetup/postgresql_setup.sql + +export PGX_TEST_DATABASE="host=localhost port=5432 user=postgres password=postgres dbname=pgx_test" +go test ./... +``` + +Notes: + +* If tests appear to pass unexpectedly quickly and you see `(cached)`, force a re-run with `go test -count=1 ./...`. +* Docker PostgreSQL images often default to `TimeZone=UTC` while `time.Local` uses your host timezone. If you see + timestamp-with-timezone related test failures (e.g. a `timestamptz` value round-tripping with a different offset), + you can run the tests in UTC with: + +``` +TZ=UTC go test -count=1 ./... +``` + ### 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