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

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.StrictNamedArgs 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.StrictNamedArgs

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:207571fb05f5ff49d4de0d8eb0d577bd565fd7a69f7fe0eff0ba864c29342e51","contract":["pgx.StrictNamedArgs satisfies pgx.QueryRewriter interface","StrictNamedArgs.RewriteQuery replaces named @ placeholders with ordinal $ placeholders and returns positional arguments in order of appearance","StrictNamedArgs.RewriteQuery maps multiple occurrences of the same named placeholder to a single ordinal position","StrictNamedArgs.RewriteQuery preserves @ characters inside string literals, quoted identifiers, and SQL comments","StrictNamedArgs.RewriteQuery returns an error when the SQL query references a parameter missing from StrictNamedArgs","StrictNamedArgs.RewriteQuery returns an error when StrictNamedArgs contains an extra parameter not referenced in the SQL query","StrictStructArgs produces a QueryRewriter enforcing StrictNamedArgs validation semantics across struct fields and db tags"],"goal":"verify github.com/jackc/pgx/v5.StrictNamedArgs 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.StrictNamedArgs"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","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.StrictNamedArgs"],"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/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/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=
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=

package sample

import (
	"context"
	"fmt"

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

// SearchFilter represents query filter parameters that can be rewritten with StrictStructArgs.
type SearchFilter struct {
	TenantID int64  `db:"tenant_id"`
	Status   string `db:"status"`
	Role     string `db:"role"`
	Internal string `db:"-"`
}

// RewriteStrictNamedQuery rewrites a SQL query containing named @placeholders using pgx.StrictNamedArgs.
// It verifies that all named arguments in the SQL are present in args and no unused arguments are provided.
func RewriteStrictNamedQuery(ctx context.Context, sql string, args pgx.StrictNamedArgs) (string, []any, error) {
	if args == nil {
		return "", nil, fmt.Errorf("args cannot be nil")
	}
	return args.RewriteQuery(ctx, nil, sql, nil)
}

// RewriteStrictStructQuery converts a struct into a QueryRewriter using pgx.StrictStructArgs and rewrites the query.
// It enforces StrictNamedArgs validation rules based on struct fields and db tags.
func RewriteStrictStructQuery(ctx context.Context, sql string, criteria any) (string, []any, error) {
	rewriter := pgx.StrictStructArgs(criteria)
	return rewriter.RewriteQuery(ctx, nil, sql, nil)
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/jackc/pgx/v5.StrictNamedArgs 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.StrictNamedArgs"
  ]
}

package main

import (
	"context"
	"fmt"
	"os"
	"reflect"

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

func main() {
	ctx := context.Background()

	// 1. pgx.StrictNamedArgs satisfies pgx.QueryRewriter interface
	var rewriter pgx.QueryRewriter = pgx.StrictNamedArgs{"test": 1}
	if rewriter == nil {
		fmt.Fprintf(os.Stderr, "FAIL [1]: StrictNamedArgs does not implement pgx.QueryRewriter\n")
		os.Exit(1)
	}

	// 2. StrictNamedArgs.RewriteQuery replaces named @ placeholders with ordinal $ placeholders and returns positional arguments in order of appearance
	sql := "SELECT id, status, role FROM users WHERE tenant_id = @tenant_id AND status = @status AND role = @role"
	args := pgx.StrictNamedArgs{
		"tenant_id": int64(42),
		"status":    "active",
		"role":      "admin",
	}
	newSQL, newArgs, err := sample.RewriteStrictNamedQuery(ctx, sql, args)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL [2]: RewriteStrictNamedQuery unexpected error: %v\n", err)
		os.Exit(1)
	}
	expectedSQL := "SELECT id, status, role FROM users WHERE tenant_id = $1 AND status = $2 AND role = $3"
	if newSQL != expectedSQL {
		fmt.Fprintf(os.Stderr, "FAIL [2]: SQL mismatch: expected %q, got %q\n", expectedSQL, newSQL)
		os.Exit(1)
	}
	expectedArgs := []any{int64(42), "active", "admin"}
	if !reflect.DeepEqual(newArgs, expectedArgs) {
		fmt.Fprintf(os.Stderr, "FAIL [2]: args mismatch: expected %v, got %v\n", expectedArgs, newArgs)
		os.Exit(1)
	}

	// 3. StrictNamedArgs.RewriteQuery maps multiple occurrences of the same named placeholder to a single ordinal position
	repeatSQL := "SELECT id FROM projects WHERE owner_id = @user_id OR creator_id = @user_id"
	repeatArgs := pgx.StrictNamedArgs{
		"user_id": int64(101),
	}
	newSQL, newArgs, err = sample.RewriteStrictNamedQuery(ctx, repeatSQL, repeatArgs)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL [3]: RewriteStrictNamedQuery repeat error: %v\n", err)
		os.Exit(1)
	}
	expectedRepeatSQL := "SELECT id FROM projects WHERE owner_id = $1 OR creator_id = $1"
	if newSQL != expectedRepeatSQL {
		fmt.Fprintf(os.Stderr, "FAIL [3]: repeat SQL mismatch: expected %q, got %q\n", expectedRepeatSQL, newSQL)
		os.Exit(1)
	}
	if len(newArgs) != 1 || newArgs[0] != int64(101) {
		fmt.Fprintf(os.Stderr, "FAIL [3]: repeat args mismatch: expected [101], got %v\n", newArgs)
		os.Exit(1)
	}

	// 4. StrictNamedArgs.RewriteQuery preserves @ characters inside string literals, quoted identifiers, and SQL comments
	literalSQL := `SELECT '@not_param', "@also_not_param", -- comment with @ignored
/* block comment with @ignored */ id FROM users WHERE tenant_id = @tenant_id`
	literalArgs := pgx.StrictNamedArgs{
		"tenant_id": int64(99),
	}
	newSQL, newArgs, err = sample.RewriteStrictNamedQuery(ctx, literalSQL, literalArgs)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL [4]: RewriteStrictNamedQuery literal/comment error: %v\n", err)
		os.Exit(1)
	}
	expectedLiteralSQL := `SELECT '@not_param', "@also_not_param", -- comment with @ignored
/* block comment with @ignored */ id FROM users WHERE tenant_id = $1`
	if newSQL != expectedLiteralSQL {
		fmt.Fprintf(os.Stderr, "FAIL [4]: literal SQL mismatch: expected %q, got %q\n", expectedLiteralSQL, newSQL)
		os.Exit(1)
	}
	if len(newArgs) != 1 || newArgs[0] != int64(99) {
		fmt.Fprintf(os.Stderr, "FAIL [4]: literal args mismatch: expected [99], got %v\n", newArgs)
		os.Exit(1)
	}

	// 5. StrictNamedArgs.RewriteQuery returns an error when the SQL query references a parameter missing from StrictNamedArgs
	missingArgs := pgx.StrictNamedArgs{
		"tenant_id": int64(42),
	}
	_, _, err = sample.RewriteStrictNamedQuery(ctx, "SELECT id FROM users WHERE tenant_id = @tenant_id AND status = @status", missingArgs)
	if err == nil {
		fmt.Fprintf(os.Stderr, "FAIL [5]: expected error for missing parameter in StrictNamedArgs, got nil\n")
		os.Exit(1)
	}

	// 6. StrictNamedArgs.RewriteQuery returns an error when StrictNamedArgs contains an extra parameter not referenced in the SQL query
	extraArgs := pgx.StrictNamedArgs{
		"tenant_id":   int64(42),
		"superfluous": "should_fail",
	}
	_, _, err = sample.RewriteStrictNamedQuery(ctx, "SELECT id FROM users WHERE tenant_id = @tenant_id", extraArgs)
	if err == nil {
		fmt.Fprintf(os.Stderr, "FAIL [6]: expected error for superfluous parameter in StrictNamedArgs, got nil\n")
		os.Exit(1)
	}

	// 7. StrictStructArgs produces a QueryRewriter enforcing StrictNamedArgs validation semantics across struct fields and db tags
	filter := sample.SearchFilter{
		TenantID: int64(500),
		Status:   "active",
		Role:     "viewer",
		Internal: "skip_me",
	}
	structSQL := "SELECT id FROM accounts WHERE tenant_id = @tenant_id AND status = @status AND role = @role"
	newSQL, newArgs, err = sample.RewriteStrictStructQuery(ctx, structSQL, filter)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL [7]: RewriteStrictStructQuery unexpected error: %v\n", err)
		os.Exit(1)
	}
	expectedStructArgs := []any{int64(500), "active", "viewer"}
	if !reflect.DeepEqual(newArgs, expectedStructArgs) {
		fmt.Fprintf(os.Stderr, "FAIL [7]: struct args mismatch: expected %v, got %v\n", expectedStructArgs, newArgs)
		os.Exit(1)
	}

	// StrictStructArgs must fail if SQL query omits one of the struct's exported fields
	partialSQL := "SELECT id FROM accounts WHERE tenant_id = @tenant_id"
	_, _, err = sample.RewriteStrictStructQuery(ctx, partialSQL, filter)
	if err == nil {
		fmt.Fprintf(os.Stderr, "FAIL [7]: expected error for omitted struct field in StrictStructArgs, got nil\n")
		os.Exit(1)
	}

	fmt.Println("PASS: all pgx.StrictNamedArgs contract assertions verified successfully.")
}