github.com/jackc/pgx/v5 v5.10.0: Identifier, 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 pgx.Identifier and pgx.NamedArgs 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:
  - Identifier
  - NamedArgs
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@11.8.0
  - runtime: node@24.13.1

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:3eb4123a318955bea5e9e6c3b5bfda5ef678ccadbc6824e7b5e5ee75ff7ce52d","constraints":{"executionContext":"go"},"contract":["pgx.Identifier sanitizes single and qualified multi-part database identifiers with proper quoting","pgx.Identifier escapes embedded double quotes in table and column identifiers","FormatQualifiedTable and FormatQualifiedColumn sanitize database hierarchy elements into safe SQL identifiers","pgx.NamedArgs stores and retrieves query parameters by name","BuildNamedArgs and MergeNamedArgs construct and combine named query parameter mappings","BuildNamedInsertQuery builds parameterized SQL INSERT statements using sanitized identifiers and named placeholders","BuildNamedInsertQuery returns an error when required column arguments are missing or columns list is empty"],"goal":"verify pgx.Identifier and pgx.NamedArgs 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":["Identifier","NamedArgs"]},"contractCommand":["go","run","test/contract.go"],"environment":{"arch":"x64","ecosystem":"golang","executionContext":"go","language":"go","os":"windows","osVersionBucket":"11","packageManager":"go","packageManagerVersion":"1.26.5","runtime":"go","runtimeVersion":"1.26","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/jackc/pgx/v5@v5.10.0"],"schemaVersion":1,"symbols":["Identifier","NamedArgs"],"verifierAdapter":"golang@1"}

module sample

go 1.26.5

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
	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 sample

import (
	"fmt"
	"strings"

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

// FormatQualifiedTable sanitizes schema and table names into a qualified SQL identifier.
func FormatQualifiedTable(schema, table string) string {
	ident := pgx.Identifier{schema, table}
	return ident.Sanitize()
}

// FormatQualifiedColumn sanitizes schema, table, and column names into a qualified SQL identifier.
func FormatQualifiedColumn(schema, table, column string) string {
	ident := pgx.Identifier{schema, table, column}
	return ident.Sanitize()
}

// SanitizeIdentifier returns the sanitized SQL string for a given pgx.Identifier.
func SanitizeIdentifier(parts ...string) string {
	ident := pgx.Identifier(parts)
	return ident.Sanitize()
}

// BuildNamedArgs creates a pgx.NamedArgs map from a key-value mapping.
func BuildNamedArgs(entries map[string]any) pgx.NamedArgs {
	args := make(pgx.NamedArgs, len(entries))
	for k, v := range entries {
		args[k] = v
	}
	return args
}

// MergeNamedArgs combines multiple pgx.NamedArgs into a single pgx.NamedArgs map.
func MergeNamedArgs(sets ...pgx.NamedArgs) pgx.NamedArgs {
	merged := make(pgx.NamedArgs)
	for _, set := range sets {
		for k, v := range set {
			merged[k] = v
		}
	}
	return merged
}

// BuildNamedInsertQuery generates a parameterized INSERT query with named placeholders and returns the SQL along with the pgx.NamedArgs.
func BuildNamedInsertQuery(table pgx.Identifier, columns []string, args pgx.NamedArgs) (string, error) {
	if len(columns) == 0 {
		return "", fmt.Errorf("columns slice cannot be empty")
	}

	sanitizedTable := table.Sanitize()
	sanitizedCols := make([]string, len(columns))
	placeholders := make([]string, len(columns))

	for i, col := range columns {
		if _, ok := args[col]; !ok {
			return "", fmt.Errorf("missing argument for column: %s", col)
		}
		sanitizedCols[i] = pgx.Identifier{col}.Sanitize()
		placeholders[i] = "@" + col
	}

	query := fmt.Sprintf(
		"INSERT INTO %s (%s) VALUES (%s)",
		sanitizedTable,
		strings.Join(sanitizedCols, ", "),
		strings.Join(placeholders, ", "),
	)

	return query, nil
}

{
  "schemaVersion": 1,
  "goal": "verify pgx.Identifier and pgx.NamedArgs 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": [
    "Identifier",
    "NamedArgs"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@11.8.0",
    "runtime": "node@24.13.1"
  }
}

package main

import (
	"fmt"
	"os"

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

func main() {
	// 1. Verify pgx.Identifier basic sanitization
	singleIdent := pgx.Identifier{"users"}
	if got := singleIdent.Sanitize(); got != `"users"` {
		fmt.Fprintf(os.Stderr, "expected %q, got %q\n", `"users"`, got)
		os.Exit(1)
	}

	multiIdent := pgx.Identifier{"my_schema", "my_table"}
	if got := multiIdent.Sanitize(); got != `"my_schema"."my_table"` {
		fmt.Fprintf(os.Stderr, "expected %q, got %q\n", `"my_schema"."my_table"`, got)
		os.Exit(1)
	}

	// 2. Verify pgx.Identifier quotes escaping
	escapeIdent := pgx.Identifier{`table"name`}
	if got := escapeIdent.Sanitize(); got != `"table""name"` {
		fmt.Fprintf(os.Stderr, "expected %q, got %q\n", `"table""name"`, got)
		os.Exit(1)
	}

	// 3. Verify helper identifier functions
	if got := sample.FormatQualifiedTable("app_data", "accounts"); got != `"app_data"."accounts"` {
		fmt.Fprintf(os.Stderr, "expected %q, got %q\n", `"app_data"."accounts"`, got)
		os.Exit(1)
	}

	if got := sample.FormatQualifiedColumn("app_data", "accounts", "balance"); got != `"app_data"."accounts"."balance"` {
		fmt.Fprintf(os.Stderr, "expected %q, got %q\n", `"app_data"."accounts"."balance"`, got)
		os.Exit(1)
	}

	// 4. Verify pgx.NamedArgs map instantiation and value retrieval
	rawNamed := pgx.NamedArgs{
		"user_id": 101,
		"status":  "active",
	}
	if rawNamed["user_id"] != 101 || rawNamed["status"] != "active" {
		fmt.Fprintf(os.Stderr, "unexpected NamedArgs contents: %+v\n", rawNamed)
		os.Exit(1)
	}

	// 5. Verify BuildNamedArgs and MergeNamedArgs helpers
	builtArgs := sample.BuildNamedArgs(map[string]any{
		"first_name": "Alice",
		"age":        30,
	})
	if builtArgs["first_name"] != "Alice" || builtArgs["age"] != 30 {
		fmt.Fprintf(os.Stderr, "BuildNamedArgs failed: %+v\n", builtArgs)
		os.Exit(1)
	}

	extraArgs := pgx.NamedArgs{"role": "admin"}
	mergedArgs := sample.MergeNamedArgs(builtArgs, extraArgs)
	if len(mergedArgs) != 3 || mergedArgs["role"] != "admin" || mergedArgs["first_name"] != "Alice" {
		fmt.Fprintf(os.Stderr, "MergeNamedArgs failed: %+v\n", mergedArgs)
		os.Exit(1)
	}

	// 6. Verify BuildNamedInsertQuery generates sanitized SQL with named placeholders
	table := pgx.Identifier{"public", "users"}
	cols := []string{"first_name", "age"}
	query, err := sample.BuildNamedInsertQuery(table, cols, mergedArgs)
	if err != nil {
		fmt.Fprintf(os.Stderr, "BuildNamedInsertQuery error: %v\n", err)
		os.Exit(1)
	}
	expectedQuery := `INSERT INTO "public"."users" ("first_name", "age") VALUES (@first_name, @age)`
	if query != expectedQuery {
		fmt.Fprintf(os.Stderr, "expected query %q, got %q\n", expectedQuery, query)
		os.Exit(1)
	}

	// 7. Verify BuildNamedInsertQuery error handling
	_, err = sample.BuildNamedInsertQuery(table, nil, mergedArgs)
	if err == nil {
		fmt.Fprintf(os.Stderr, "expected error for empty columns, got nil\n")
		os.Exit(1)
	}

	_, err = sample.BuildNamedInsertQuery(table, []string{"non_existent_column"}, mergedArgs)
	if err == nil {
		fmt.Fprintf(os.Stderr, "expected error for missing column arg, got nil\n")
		os.Exit(1)
	}

	fmt.Println("All pgx.Identifier and pgx.NamedArgs contract assertions passed.")
}