github.com/jackc/pgx/v5 v5.10.0: pgxpool.Pool

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify github.com/jackc/pgx/v5/pgxpool.Pool in pkg:golang/github.com/jackc/pgx/v5@v5.10.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/jackc/pgx/v5@v5.10.0
Demonstrate these symbols/APIs:
  - github.com/jackc/pgx/v5/pgxpool.Pool

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:04c654b387845962c29e0c8665c5d902cbf7b13c599d337bc2a0e3e28b13b1a0","contract":["pgxpool.NewWithConfig initializes a pgxpool.Pool from valid configuration without immediate network connections when MinConns is zero","pgxpool.Pool exposes Config with configured options including MaxConns, MinConns, MaxConnLifetime, MaxConnIdleTime, and HealthCheckPeriod","pgxpool.Pool exposes Stat with connection metrics reflecting active, idle, and total connection counts","pgxpool.Pool supports Reset and Close to release and terminate pool resources offline","pgxpool.Pool Acquire respects canceled context and returns context.Canceled error when offline"],"goal":"verify github.com/jackc/pgx/v5/pgxpool.Pool in pkg:golang/github.com/jackc/pgx/v5@v5.10.0","kind":"HOW","packages":["pkg:golang/github.com/jackc/pgx/v5@v5.10.0"],"schemaVersion":1,"symbols":["github.com/jackc/pgx/v5/pgxpool.Pool"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/jackc/pgx/v5@v5.10.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/jackc/pgx/v5@v5.10.0","symbols":["github.com/jackc/pgx/v5/pgxpool.Pool"],"verifierAdapter":"golang@1"}

module example.com/pgxpoolsample

go 1.25.0

require github.com/jackc/pgx/v5 v5.10.0

require (
	github.com/jackc/pgpassfile v1.0.0 // indirect
	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
	github.com/jackc/puddle/v2 v2.2.2 // indirect
	golang.org/x/sync v0.17.0 // indirect
	golang.org/x/text v0.29.0 // indirect
)

github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package pgxpoolsample

import (
	"context"
	"errors"
	"fmt"
	"time"

	"github.com/jackc/pgx/v5/pgxpool"
)

// PoolOptions holds configuration options for initializing a pgxpool.Pool.
type PoolOptions struct {
	MaxConns          int32
	MinConns          int32
	MaxConnLifetime   time.Duration
	MaxConnIdleTime   time.Duration
	HealthCheckPeriod time.Duration
}

// PoolMetrics captures snapshot metrics from pgxpool.Pool.Stat().
type PoolMetrics struct {
	TotalConns        int32
	IdleConns         int32
	AcquiredConns     int32
	ConstructingConns int32
	MaxConns          int32
	AcquireCount      int64
	EmptyAcquireCount int64
}

// CreatePool creates and configures a new *pgxpool.Pool from a connection string and custom options.
func CreatePool(ctx context.Context, connString string, opts *PoolOptions) (*pgxpool.Pool, error) {
	if connString == "" {
		return nil, errors.New("connection string cannot be empty")
	}

	config, err := pgxpool.ParseConfig(connString)
	if err != nil {
		return nil, fmt.Errorf("failed to parse connection config: %w", err)
	}

	if opts != nil {
		if opts.MaxConns > 0 {
			config.MaxConns = opts.MaxConns
		}
		if opts.MinConns >= 0 {
			config.MinConns = opts.MinConns
		}
		if opts.MaxConnLifetime > 0 {
			config.MaxConnLifetime = opts.MaxConnLifetime
		}
		if opts.MaxConnIdleTime > 0 {
			config.MaxConnIdleTime = opts.MaxConnIdleTime
		}
		if opts.HealthCheckPeriod > 0 {
			config.HealthCheckPeriod = opts.HealthCheckPeriod
		}
	}

	pool, err := pgxpool.NewWithConfig(ctx, config)
	if err != nil {
		return nil, fmt.Errorf("failed to create connection pool: %w", err)
	}

	return pool, nil
}

// InspectPoolConfig returns the active configuration parameters of a pgxpool.Pool.
func InspectPoolConfig(pool *pgxpool.Pool) (PoolOptions, error) {
	if pool == nil {
		return PoolOptions{}, errors.New("pool is nil")
	}
	cfg := pool.Config()
	if cfg == nil {
		return PoolOptions{}, errors.New("pool config is nil")
	}

	return PoolOptions{
		MaxConns:          cfg.MaxConns,
		MinConns:          cfg.MinConns,
		MaxConnLifetime:   cfg.MaxConnLifetime,
		MaxConnIdleTime:   cfg.MaxConnIdleTime,
		HealthCheckPeriod: cfg.HealthCheckPeriod,
	}, nil
}

// GetPoolMetrics retrieves the current pool statistics via pool.Stat().
func GetPoolMetrics(pool *pgxpool.Pool) (PoolMetrics, error) {
	if pool == nil {
		return PoolMetrics{}, errors.New("pool is nil")
	}
	stat := pool.Stat()
	if stat == nil {
		return PoolMetrics{}, errors.New("stat is nil")
	}

	return PoolMetrics{
		TotalConns:        stat.TotalConns(),
		IdleConns:         stat.IdleConns(),
		AcquiredConns:     stat.AcquiredConns(),
		ConstructingConns: stat.ConstructingConns(),
		MaxConns:          stat.MaxConns(),
		AcquireCount:      stat.AcquireCount(),
		EmptyAcquireCount: stat.EmptyAcquireCount(),
	}, nil
}

// ResetAndClose demonstrates resetting and closing the pgxpool.Pool cleanly.
func ResetAndClose(pool *pgxpool.Pool) error {
	if pool == nil {
		return errors.New("pool is nil")
	}
	pool.Reset()
	pool.Close()
	return nil
}

package pgxpoolsample

import (
	"context"
	"errors"
	"testing"
	"time"

	"github.com/jackc/pgx/v5/pgxpool"
)

const testConnStr = "postgres://postgres:secret@127.0.0.1:5432/testdb?sslmode=disable"

func TestCreatePoolAndInspectConfig(t *testing.T) {
	// Assertion: pgxpool.NewWithConfig creates a pgxpool.Pool from valid configuration without immediate connection attempts when MinConns is zero
	// Assertion: pgxpool.Pool exposes Config() with applied pool settings including MaxConns, MinConns, MaxConnLifetime, and HealthCheckPeriod
	ctx := context.Background()
	opts := &PoolOptions{
		MaxConns:          25,
		MinConns:          0,
		MaxConnLifetime:   1 * time.Hour,
		MaxConnIdleTime:   15 * time.Minute,
		HealthCheckPeriod: 30 * time.Second,
	}

	pool, err := CreatePool(ctx, testConnStr, opts)
	if err != nil {
		t.Fatalf("failed to create pool: %v", err)
	}
	defer pool.Close()

	var p *pgxpool.Pool = pool
	if p == nil {
		t.Fatal("expected non-nil pgxpool.Pool")
	}

	cfg, err := InspectPoolConfig(pool)
	if err != nil {
		t.Fatalf("failed to inspect pool config: %v", err)
	}

	if cfg.MaxConns != 25 {
		t.Errorf("expected MaxConns=25, got %d", cfg.MaxConns)
	}
	if cfg.MinConns != 0 {
		t.Errorf("expected MinConns=0, got %d", cfg.MinConns)
	}
	if cfg.MaxConnLifetime != 1*time.Hour {
		t.Errorf("expected MaxConnLifetime=1h, got %v", cfg.MaxConnLifetime)
	}
	if cfg.MaxConnIdleTime != 15*time.Minute {
		t.Errorf("expected MaxConnIdleTime=15m, got %v", cfg.MaxConnIdleTime)
	}
	if cfg.HealthCheckPeriod != 30*time.Second {
		t.Errorf("expected HealthCheckPeriod=30s, got %v", cfg.HealthCheckPeriod)
	}
}

func TestPoolStatMetrics(t *testing.T) {
	// Assertion: pgxpool.Pool exposes Stat() with initial zero active/idle connections and accurate MaxConns capacity
	ctx := context.Background()
	opts := &PoolOptions{
		MaxConns: 10,
		MinConns: 0,
	}

	pool, err := CreatePool(ctx, testConnStr, opts)
	if err != nil {
		t.Fatalf("failed to create pool: %v", err)
	}
	defer pool.Close()

	metrics, err := GetPoolMetrics(pool)
	if err != nil {
		t.Fatalf("failed to get pool metrics: %v", err)
	}

	if metrics.MaxConns != 10 {
		t.Errorf("expected MaxConns=10, got %d", metrics.MaxConns)
	}
	if metrics.TotalConns != 0 {
		t.Errorf("expected TotalConns=0, got %d", metrics.TotalConns)
	}
	if metrics.AcquiredConns != 0 {
		t.Errorf("expected AcquiredConns=0, got %d", metrics.AcquiredConns)
	}
	if metrics.IdleConns != 0 {
		t.Errorf("expected IdleConns=0, got %d", metrics.IdleConns)
	}
}

func TestPoolResetAndClose(t *testing.T) {
	// Assertion: pgxpool.Pool Reset and Close methods cleanly release and terminate pool resources offline
	ctx := context.Background()
	pool, err := CreatePool(ctx, testConnStr, nil)
	if err != nil {
		t.Fatalf("failed to create pool: %v", err)
	}

	if err := ResetAndClose(pool); err != nil {
		t.Fatalf("failed to reset and close pool: %v", err)
	}
}

func TestPoolAcquireContextCanceled(t *testing.T) {
	// Assertion: pgxpool.Pool Acquire respects canceled contexts and returns context.Canceled error when offline
	ctx, cancel := context.WithCancel(context.Background())
	cancel() // Cancel immediately

	pool, err := CreatePool(context.Background(), testConnStr, nil)
	if err != nil {
		t.Fatalf("failed to create pool: %v", err)
	}
	defer pool.Close()

	conn, err := pool.Acquire(ctx)
	if err == nil {
		conn.Release()
		t.Fatal("expected error acquiring with canceled context, got nil")
	}
	if !errors.Is(err, context.Canceled) {
		t.Errorf("expected context.Canceled error, got: %v", err)
	}
}

func TestCreatePoolInvalidConnString(t *testing.T) {
	// Assertion: CreatePool rejects invalid or empty connection strings
	ctx := context.Background()
	_, err := CreatePool(ctx, "", nil)
	if err == nil {
		t.Fatal("expected error for empty connection string, got nil")
	}

	_, err = CreatePool(ctx, "invalid://::bad uri", nil)
	if err == nil {
		t.Fatal("expected error for malformed connection string, got nil")
	}
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/jackc/pgx/v5/pgxpool.Pool in pkg:golang/github.com/jackc/pgx/v5@v5.10.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/jackc/pgx/v5@v5.10.0"
  ],
  "symbols": [
    "github.com/jackc/pgx/v5/pgxpool.Pool"
  ]
}