github.com/jackc/pgx/v5 v5.11.0: QueryRewriter

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.QueryRewriter in pkg:golang/github.com/jackc/pgx/v5@v5.11.0
Kind: HOW

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

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:4d98fcd05f6fe84e0feb5bba485e57a414bfc6c40ecbf908347ec79ce73a667e","contract":["QueryRewriter interface allows custom types to rewrite SQL strings","QueryRewriter implementation can inspect and replace query arguments","QueryRewriter returning an error propagates the failure to the caller","NamedArgs implements QueryRewriter to transform named placeholders into ordinal parameters","StrictNamedArgs implements QueryRewriter and rejects queries with mismatched parameters","StructArgs converts exported struct fields into a QueryRewriter"],"goal":"verify github.com/jackc/pgx/v5.QueryRewriter in pkg:golang/github.com/jackc/pgx/v5@v5.11.0","kind":"HOW","packages":["pkg:golang/github.com/jackc/pgx/v5@v5.11.0"],"schemaVersion":1,"symbols":["github.com/jackc/pgx/v5.QueryRewriter"]},"contractCommand":["go","run","./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.11.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/jackc/pgx/v5@v5.11.0","symbols":["github.com/jackc/pgx/v5.QueryRewriter"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

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

require (
	github.com/jackc/pgpassfile v1.0.0 // indirect
	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // 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.11.0 h1:IzBBtyK9AHqf98cctWFifYSci2hgQR/cd56wB4p+ogg=
github.com/jackc/pgx/v5 v5.11.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=

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

package main

import (
	"context"
	"errors"
	"fmt"
	"os"
	"strings"

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

func main() {
	if err := runTests(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract test failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("All contract tests passed successfully.")
}

// 1. QueryRewriter interface allows custom types to rewrite SQL strings
type prefixRewriter struct {
	prefix string
}

func (r prefixRewriter) RewriteQuery(ctx context.Context, conn *pgx.Conn, sql string, args []any) (newSQL string, newArgs []any, err error) {
	return r.prefix + sql, args, nil
}

// 2. QueryRewriter implementation can inspect and replace query arguments
type upperArgsRewriter struct{}

func (r upperArgsRewriter) RewriteQuery(ctx context.Context, conn *pgx.Conn, sql string, args []any) (newSQL string, newArgs []any, err error) {
	transformed := make([]any, len(args))
	for i, a := range args {
		if s, ok := a.(string); ok {
			transformed[i] = strings.ToUpper(s)
		} else {
			transformed[i] = a
		}
	}
	return sql, transformed, nil
}

// 3. QueryRewriter returning an error propagates the failure to the caller
type errorRewriter struct {
	err error
}

func (r errorRewriter) RewriteQuery(ctx context.Context, conn *pgx.Conn, sql string, args []any) (newSQL string, newArgs []any, err error) {
	return "", nil, r.err
}

type sampleFilter struct {
	Active bool   `db:"active"`
	Limit  int    `db:"limit"`
	Role   string `db:"role"`
}

func runTests() error {
	ctx := context.Background()

	// 1. QueryRewriter interface allows custom types to rewrite SQL strings
	var pr pgx.QueryRewriter = prefixRewriter{prefix: "/* comment */ "}
	newSQL, newArgs, err := pr.RewriteQuery(ctx, nil, "SELECT 1", []any{10})
	if err != nil {
		return fmt.Errorf("prefixRewriter failed: %w", err)
	}
	if newSQL != "/* comment */ SELECT 1" {
		return fmt.Errorf("unexpected rewritten sql: %q", newSQL)
	}
	if len(newArgs) != 1 || newArgs[0] != 10 {
		return fmt.Errorf("unexpected rewritten args: %+v", newArgs)
	}

	// 2. QueryRewriter implementation can inspect and replace query arguments
	var ar pgx.QueryRewriter = upperArgsRewriter{}
	sql2, args2, err := ar.RewriteQuery(ctx, nil, "SELECT $1, $2", []any{"alpha", 42})
	if err != nil {
		return fmt.Errorf("upperArgsRewriter failed: %w", err)
	}
	if sql2 != "SELECT $1, $2" {
		return fmt.Errorf("unexpected sql from upperArgsRewriter: %q", sql2)
	}
	if len(args2) != 2 || args2[0] != "ALPHA" || args2[1] != 42 {
		return fmt.Errorf("unexpected args from upperArgsRewriter: %+v", args2)
	}

	// 3. QueryRewriter returning an error propagates the failure to the caller
	expectedErr := errors.New("query rewrite failed intentional")
	var er pgx.QueryRewriter = errorRewriter{err: expectedErr}
	_, _, err = er.RewriteQuery(ctx, nil, "SELECT 1", nil)
	if !errors.Is(err, expectedErr) {
		return fmt.Errorf("expected error %v, got %v", expectedErr, err)
	}

	// 4. NamedArgs implements QueryRewriter to transform named placeholders into ordinal parameters
	var na pgx.QueryRewriter = pgx.NamedArgs{
		"userId": 12345,
		"status": "active",
	}
	sql4, args4, err := na.RewriteQuery(ctx, nil, "SELECT * FROM accounts WHERE id = @userId AND status = @status", nil)
	if err != nil {
		return fmt.Errorf("NamedArgs.RewriteQuery failed: %w", err)
	}
	if sql4 != "SELECT * FROM accounts WHERE id = $1 AND status = $2" {
		return fmt.Errorf("unexpected sql from NamedArgs: %q", sql4)
	}
	if len(args4) != 2 || args4[0] != 12345 || args4[1] != "active" {
		return fmt.Errorf("unexpected args from NamedArgs: %+v", args4)
	}

	// 5. StrictNamedArgs implements QueryRewriter and rejects queries with mismatched parameters
	var sna pgx.QueryRewriter = pgx.StrictNamedArgs{
		"userId": 12345,
	}
	_, _, err = sna.RewriteQuery(ctx, nil, "SELECT * FROM accounts WHERE id = @userId AND status = @status", nil)
	if err == nil {
		return fmt.Errorf("expected StrictNamedArgs to fail for missing argument, but got nil")
	}
	var snaExtra pgx.QueryRewriter = pgx.StrictNamedArgs{
		"userId": 12345,
		"extra":  "unused",
	}
	_, _, err = snaExtra.RewriteQuery(ctx, nil, "SELECT * FROM accounts WHERE id = @userId", nil)
	if err == nil {
		return fmt.Errorf("expected StrictNamedArgs to fail for extra argument, but got nil")
	}

	// 6. StructArgs converts exported struct fields into a QueryRewriter
	filter := sampleFilter{
		Active: true,
		Limit:  25,
		Role:   "admin",
	}
	structRewriter := pgx.StructArgs(filter)
	sql6, args6, err := structRewriter.RewriteQuery(ctx, nil, "SELECT * FROM users WHERE active = @active AND role = @role LIMIT @limit", nil)
	if err != nil {
		return fmt.Errorf("StructArgs.RewriteQuery failed: %w", err)
	}
	if sql6 != "SELECT * FROM users WHERE active = $1 AND role = $2 LIMIT $3" {
		return fmt.Errorf("unexpected sql from StructArgs: %q", sql6)
	}
	if len(args6) != 3 || args6[0] != true || args6[1] != "admin" || args6[2] != 25 {
		return fmt.Errorf("unexpected args from StructArgs: %+v", args6)
	}

	invalidRewriter := pgx.StructArgs(nil)
	_, _, err = invalidRewriter.RewriteQuery(ctx, nil, "SELECT 1", nil)
	if err == nil {
		return fmt.Errorf("expected StructArgs(nil) to return error on RewriteQuery, got nil")
	}

	return nil
}