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

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

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:60053f905631551997a79f5cdbd5ebe03f67dc9b19f1e5d8eb542437d5206f9e","contract":["pgx.NamedArgs satisfies pgx.QueryRewriter interface","NamedArgs.RewriteQuery replaces named @ placeholders with ordinal $ placeholders and returns positional arguments","NamedArgs.RewriteQuery binds repeated occurrences of the same named placeholder to a single ordinal argument","NamedArgs.RewriteQuery preserves @ symbols within string literals, quoted identifiers, and SQL comments","NamedArgs.RewriteQuery permits unreferenced extra keys in the arguments map","StrictNamedArgs.RewriteQuery returns an error when SQL query references missing named parameters","StrictNamedArgs.RewriteQuery returns an error when arguments map contains unused extra parameters","StructArgs and StrictStructArgs map exported struct fields and db tags into QueryRewriter"],"goal":"verify github.com/jackc/pgx/v5.NamedArgs 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.NamedArgs"]},"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.NamedArgs"],"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"
)

// UserQueryCriteria represents query filter criteria convertible to pgx.QueryRewriter via StructArgs.
type UserQueryCriteria struct {
	TenantID int64  `db:"tenant_id"`
	Email    string `db:"email"`
	Status   string `db:"status"`
	Internal string `db:"-"`
}

// RewriteNamedQuery rewrites a SQL query containing named @placeholders using pgx.NamedArgs into $ordinals.
func RewriteNamedQuery(ctx context.Context, sql string, args pgx.NamedArgs) (string, []any, error) {
	if args == nil {
		return "", nil, fmt.Errorf("args cannot be nil")
	}
	return args.RewriteQuery(ctx, nil, sql, nil)
}

// RewriteStrictNamedQuery rewrites SQL query using pgx.StrictNamedArgs, validating all parameters.
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)
}

// RewriteStructQuery converts a struct into a QueryRewriter using pgx.StructArgs and rewrites the query.
func RewriteStructQuery(ctx context.Context, sql string, criteria any) (string, []any, error) {
	rewriter := pgx.StructArgs(criteria)
	return rewriter.RewriteQuery(ctx, nil, sql, nil)
}

// RewriteStrictStructQuery converts a struct into a QueryRewriter using pgx.StrictStructArgs and rewrites the query.
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.NamedArgs 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.NamedArgs"
  ]
}

package main

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

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

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

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

	// 2. NamedArgs.RewriteQuery replaces named @ placeholders with ordinal $ placeholders and returns positional arguments
	sql := "SELECT id, email, status FROM users WHERE tenant_id = @tenant_id AND status = @status"
	args := pgx.NamedArgs{
		"tenant_id": int64(1001),
		"status":    "active",
	}
	newSQL, newArgs, err := sample.RewriteNamedQuery(ctx, sql, args)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL [2]: RewriteNamedQuery error: %v\n", err)
		os.Exit(1)
	}
	expectedSQL := "SELECT id, email, status FROM users WHERE tenant_id = $1 AND status = $2"
	if newSQL != expectedSQL {
		fmt.Fprintf(os.Stderr, "FAIL [2]: SQL mismatch: expected %q, got %q\n", expectedSQL, newSQL)
		os.Exit(1)
	}
	if len(newArgs) != 2 || newArgs[0] != int64(1001) || newArgs[1] != "active" {
		fmt.Fprintf(os.Stderr, "FAIL [2]: args mismatch: got %v\n", newArgs)
		os.Exit(1)
	}

	// 3. NamedArgs.RewriteQuery binds repeated occurrences of the same named placeholder to a single ordinal argument
	repeatSQL := "SELECT id FROM accounts WHERE user_id = @user_id OR owner_id = @user_id"
	repeatArgs := pgx.NamedArgs{"user_id": int64(42)}
	newSQL, newArgs, err = sample.RewriteNamedQuery(ctx, repeatSQL, repeatArgs)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL [3]: RewriteNamedQuery repeated placeholder error: %v\n", err)
		os.Exit(1)
	}
	expectedRepeatSQL := "SELECT id FROM accounts WHERE user_id = $1 OR owner_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(42) {
		fmt.Fprintf(os.Stderr, "FAIL [3]: repeat args mismatch: got %v\n", newArgs)
		os.Exit(1)
	}

	// 4. NamedArgs.RewriteQuery preserves @ symbols within string literals, quoted identifiers, and SQL comments
	complexSQL := "SELECT '@not_a_param', \"@not_a_col\", -- comment with @ignored\n/* multiline @ignored */ id FROM users WHERE tenant_id = @tenant_id"
	complexArgs := pgx.NamedArgs{"tenant_id": int64(5)}
	newSQL, newArgs, err = sample.RewriteNamedQuery(ctx, complexSQL, complexArgs)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL [4]: complex RewriteNamedQuery error: %v\n", err)
		os.Exit(1)
	}
	expectedComplexSQL := "SELECT '@not_a_param', \"@not_a_col\", -- comment with @ignored\n/* multiline @ignored */ id FROM users WHERE tenant_id = $1"
	if newSQL != expectedComplexSQL {
		fmt.Fprintf(os.Stderr, "FAIL [4]: complex SQL mismatch: expected %q, got %q\n", expectedComplexSQL, newSQL)
		os.Exit(1)
	}
	if len(newArgs) != 1 || newArgs[0] != int64(5) {
		fmt.Fprintf(os.Stderr, "FAIL [4]: complex args mismatch: got %v\n", newArgs)
		os.Exit(1)
	}

	// 5. NamedArgs.RewriteQuery permits unreferenced extra keys in the arguments map
	extraArgs := pgx.NamedArgs{
		"tenant_id": int64(7),
		"unused":    "extra_data",
	}
	newSQL, newArgs, err = sample.RewriteNamedQuery(ctx, "SELECT id FROM users WHERE tenant_id = @tenant_id", extraArgs)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL [5]: extra keys error: %v\n", err)
		os.Exit(1)
	}
	if len(newArgs) != 1 || newArgs[0] != int64(7) {
		fmt.Fprintf(os.Stderr, "FAIL [5]: extra keys args mismatch: got %v\n", newArgs)
		os.Exit(1)
	}

	// 6. StrictNamedArgs.RewriteQuery returns an error when SQL query references missing named parameters
	missingArgs := pgx.StrictNamedArgs{
		"tenant_id": int64(10),
	}
	_, _, 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 [6]: expected error for missing parameter in StrictNamedArgs, got nil\n")
		os.Exit(1)
	}

	// 7. StrictNamedArgs.RewriteQuery returns an error when arguments map contains unused extra parameters
	unusedStrictArgs := pgx.StrictNamedArgs{
		"tenant_id": int64(10),
		"extra_arg": "invalid",
	}
	_, _, err = sample.RewriteStrictNamedQuery(ctx, "SELECT id FROM users WHERE tenant_id = @tenant_id", unusedStrictArgs)
	if err == nil {
		fmt.Fprintf(os.Stderr, "FAIL [7]: expected error for unused parameter in StrictNamedArgs, got nil\n")
		os.Exit(1)
	}

	// 8. StructArgs and StrictStructArgs map exported struct fields and db tags into QueryRewriter
	criteria := sample.UserQueryCriteria{
		TenantID: int64(88),
		Email:    "test@example.com",
		Status:   "active",
		Internal: "secret",
	}
	structSQL := "SELECT id FROM users WHERE tenant_id = @tenant_id AND email = @email AND status = @status"
	newSQL, newArgs, err = sample.RewriteStructQuery(ctx, structSQL, criteria)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL [8]: RewriteStructQuery error: %v\n", err)
		os.Exit(1)
	}
	expectedStructArgs := []any{int64(88), "test@example.com", "active"}
	if !reflect.DeepEqual(newArgs, expectedStructArgs) {
		fmt.Fprintf(os.Stderr, "FAIL [8]: StructArgs args mismatch: expected %v, got %v\n", expectedStructArgs, newArgs)
		os.Exit(1)
	}

	// Also verify StrictStructArgs fails if a field is omitted from the SQL query
	partialSQL := "SELECT id FROM users WHERE tenant_id = @tenant_id"
	_, _, err = sample.RewriteStrictStructQuery(ctx, partialSQL, criteria)
	if err == nil {
		fmt.Fprintf(os.Stderr, "FAIL [8]: expected error for StrictStructArgs with unused struct fields\n")
		os.Exit(1)
	}

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