tessl/golang-github-com-jackc-pgx-v5

pgx is a pure Go driver and toolkit for PostgreSQL providing a native high-performance interface with PostgreSQL-specific features plus a database/sql compatibility adapter.

—

Pending

Overview

Eval results

Files

Testing Utilities (pgxtest)

Name: tessl/golang-github-com-jackc-pgx-v5
Author: tessl

pgxtest provides utilities for testing pgx-based code. It handles connection lifecycle and allows running tests against multiple query execution modes.

Import

import "github.com/jackc/pgx/v5/pgxtest"

Variables

var AllQueryExecModes = []pgx.QueryExecMode{
    pgx.QueryExecModeCacheStatement,
    pgx.QueryExecModeCacheDescribe,
    pgx.QueryExecModeDescribeExec,
    pgx.QueryExecModeExec,
    pgx.QueryExecModeSimpleProtocol,
}

var KnownOIDQueryExecModes = []pgx.QueryExecMode{
    pgx.QueryExecModeCacheStatement,
    pgx.QueryExecModeCacheDescribe,
    pgx.QueryExecModeDescribeExec,
}

KnownOIDQueryExecModes contains modes where param and result OIDs are known before sending the query.

ConnTestRunner

type ConnTestRunner struct {
    CreateConfig func(ctx context.Context, t testing.TB) *pgx.ConnConfig
    AfterConnect func(ctx context.Context, t testing.TB, conn *pgx.Conn)
    AfterTest    func(ctx context.Context, t testing.TB, conn *pgx.Conn)
    CloseConn    func(ctx context.Context, t testing.TB, conn *pgx.Conn)
}

All fields are required. Use DefaultConnTestRunner() for reasonable defaults.

func DefaultConnTestRunner() ConnTestRunner

RunTest

func (ctr *ConnTestRunner) RunTest(ctx context.Context, t testing.TB, f func(ctx context.Context, t testing.TB, conn *pgx.Conn))

Creates a connection using CreateConfig, calls AfterConnect, runs f, calls AfterTest, then closes with CloseConn.

RunWithQueryExecModes

func RunWithQueryExecModes(
    ctx context.Context,
    t *testing.T,
    ctr ConnTestRunner,
    modes []pgx.QueryExecMode,
    f func(ctx context.Context, t testing.TB, conn *pgx.Conn),
)

Runs f as a sub-test for each query exec mode in modes. If modes is nil, uses AllQueryExecModes. Creates a new connection for each mode.

func TestMyFeature(t *testing.T) {
    ctr := pgxtest.DefaultConnTestRunner()
    pgxtest.RunWithQueryExecModes(context.Background(), t, ctr, nil,
        func(ctx context.Context, t testing.TB, conn *pgx.Conn) {
            // test runs once per query exec mode
            rows, err := conn.Query(ctx, "SELECT 1")
            // ...
        })
}

RunValueRoundTripTests

func RunValueRoundTripTests(
    ctx context.Context,
    t testing.TB,
    ctr ConnTestRunner,
    modes []pgx.QueryExecMode,
    pgTypeName string,
    tests []ValueRoundTripTest,
)

Run round-trip encode/decode tests for a PostgreSQL type across multiple query exec modes.

type ValueRoundTripTest struct {
    Param  any
    Result any
    Test   func(any) bool
}

Param — value to send to PostgreSQL
Result — destination to scan the result into (pointer)
Test — function that validates the scanned value; receives the dereferenced result

pgxtest.RunValueRoundTripTests(ctx, t, ctr, pgxtest.KnownOIDQueryExecModes,
    "int4",
    []pgxtest.ValueRoundTripTest{
        {int32(42), new(int32), func(v any) bool { return *v.(*int32) == 42 }},
        {nil, new(pgtype.Int4), func(v any) bool { return !v.(*pgtype.Int4).Valid }},
    })

Skip Helpers

func SkipCockroachDB(t testing.TB, conn *pgx.Conn, msg string)
func SkipPostgreSQLVersionLessThan(t testing.TB, conn *pgx.Conn, minVersion int64)

Skip the current test if connected to CockroachDB or a PostgreSQL version older than minVersion.

func TestFeatureRequiresPostgres14(t *testing.T) {
    ctr := pgxtest.DefaultConnTestRunner()
    ctr.RunTest(ctx, t, func(ctx context.Context, t testing.TB, conn *pgx.Conn) {
        pgxtest.SkipPostgreSQLVersionLessThan(t, conn, 14_00_00) // 14.0.0
        // test code
    })
}

Install with Tessl CLI

npx tessl i tessl/golang-github-com-jackc-pgx-v5