github.com/jackc/pgx/v5 v5.10.0: ScanArgError, ScanRow

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.ScanRow 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:
  - ScanArgError
  - ScanRow
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:e0d9d7a46fd225f07261619532de6354d7ff7a340649743c66ff69511af375aa","contract":["pgx.ScanRow decodes raw row data into destination variables in text format","pgx.ScanRow decodes raw row data into destination variables in binary format","pgx.ScanRow skips decoding columns when destination pointer is nil","pgx.ScanRow returns pgx.ScanArgError with column index and field name when scanning fails","pgx.ScanArgError implements Unwrap returning underlying error","pgx.ScanRow returns error when fieldDescriptions and values length differ","pgx.ScanRow returns error when fieldDescriptions and destinations length differ","sample helpers provide typed row decoding and scan error inspection utilities"],"goal":"verify github.com/jackc/pgx/v5.ScanRow 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":["ScanArgError","ScanRow"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","ecosystem":"golang","os":"windows","osVersionBucket":"11","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/jackc/pgx/v5@v5.10.0"],"schemaVersion":1,"symbols":["ScanArgError","ScanRow"],"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 (
	"errors"
	"fmt"

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

// DecodeRow decodes raw PostgreSQL column bytes into destination pointers using pgx.ScanRow.
func DecodeRow(typeMap *pgtype.Map, fields []pgconn.FieldDescription, values [][]byte, dest ...any) error {
	if typeMap == nil {
		typeMap = pgtype.NewMap()
	}
	return pgx.ScanRow(typeMap, fields, values, dest...)
}

// DecodeTextRow is a helper to decode text-format row data given column names, OIDs, and string values.
func DecodeTextRow(typeMap *pgtype.Map, colNames []string, oids []uint32, textValues []string, dest ...any) error {
	if len(colNames) != len(oids) || len(colNames) != len(textValues) {
		return fmt.Errorf("length mismatch between column names, OIDs, and text values")
	}
	if typeMap == nil {
		typeMap = pgtype.NewMap()
	}

	fields := make([]pgconn.FieldDescription, len(colNames))
	values := make([][]byte, len(textValues))
	for i := range colNames {
		fields[i] = pgconn.FieldDescription{
			Name:        colNames[i],
			DataTypeOID: oids[i],
			Format:      0, // TextFormat
		}
		values[i] = []byte(textValues[i])
	}

	return pgx.ScanRow(typeMap, fields, values, dest...)
}

// AsScanArgError attempts to extract a pgx.ScanArgError from the provided error.
func AsScanArgError(err error) (*pgx.ScanArgError, bool) {
	var scanErr pgx.ScanArgError
	if errors.As(err, &scanErr) {
		return &scanErr, true
	}
	return nil, false
}

// FormatScanError returns a human-readable description of a scan error, including column details if available.
func FormatScanError(err error) string {
	if err == nil {
		return ""
	}
	if scanErr, ok := AsScanArgError(err); ok {
		return fmt.Sprintf("scan error on column %d (%s): %v", scanErr.ColumnIndex, scanErr.FieldName, scanErr.Err)
	}
	return err.Error()
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/jackc/pgx/v5.ScanRow 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": [
    "ScanArgError",
    "ScanRow"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@11.8.0",
    "runtime": "node@24.13.1"
  }
}

package main

import (
	"encoding/binary"
	"errors"
	"fmt"
	"os"
	"strings"

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

func main() {
	tm := pgtype.NewMap()

	// 1. Verify ScanRow decodes text-format values into Go destinations
	textFields := []pgconn.FieldDescription{
		{Name: "id", DataTypeOID: pgtype.Int4OID, Format: 0},
		{Name: "username", DataTypeOID: pgtype.TextOID, Format: 0},
		{Name: "is_active", DataTypeOID: pgtype.BoolOID, Format: 0},
	}
	textValues := [][]byte{
		[]byte("123"),
		[]byte("alice"),
		[]byte("t"),
	}

	var id int32
	var username string
	var isActive bool

	err := pgx.ScanRow(tm, textFields, textValues, &id, &username, &isActive)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 1 ScanRow text failed: %v\n", err)
		os.Exit(1)
	}
	if id != 123 || username != "alice" || !isActive {
		fmt.Fprintf(os.Stderr, "Assertion 1 mismatch: got (%d, %q, %v)\n", id, username, isActive)
		os.Exit(1)
	}

	// 2. Verify ScanRow decodes binary-format values into Go destinations
	int4Bin := make([]byte, 4)
	binary.BigEndian.PutUint32(int4Bin, 456)

	binFields := []pgconn.FieldDescription{
		{Name: "id", DataTypeOID: pgtype.Int4OID, Format: 1}, // 1 = binary
		{Name: "username", DataTypeOID: pgtype.TextOID, Format: 1},
		{Name: "is_active", DataTypeOID: pgtype.BoolOID, Format: 1},
	}
	binValues := [][]byte{
		int4Bin,
		[]byte("bob"),
		{1}, // binary true
	}

	var binID int32
	var binUser string
	var binActive bool

	err = pgx.ScanRow(tm, binFields, binValues, &binID, &binUser, &binActive)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 2 ScanRow binary failed: %v\n", err)
		os.Exit(1)
	}
	if binID != 456 || binUser != "bob" || !binActive {
		fmt.Fprintf(os.Stderr, "Assertion 2 mismatch: got (%d, %q, %v)\n", binID, binUser, binActive)
		os.Exit(1)
	}

	// 3. Verify ScanRow skips columns with nil destinations
	var skippedUser string
	err = pgx.ScanRow(tm, textFields, textValues, nil, &skippedUser, nil)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 3 ScanRow nil dest failed: %v\n", err)
		os.Exit(1)
	}
	if skippedUser != "alice" {
		fmt.Fprintf(os.Stderr, "Assertion 3 mismatch: got %q\n", skippedUser)
		os.Exit(1)
	}

	// 4. Verify ScanRow returns ScanArgError with accurate ColumnIndex, FieldName, and unwrappable Err
	badValues := [][]byte{
		[]byte("123"),
		[]byte("not_a_number"), // should fail scanning into int32
		[]byte("t"),
	}
	badFields := []pgconn.FieldDescription{
		{Name: "id", DataTypeOID: pgtype.Int4OID, Format: 0},
		{Name: "age", DataTypeOID: pgtype.Int4OID, Format: 0},
		{Name: "is_active", DataTypeOID: pgtype.BoolOID, Format: 0},
	}

	var badID int32
	var badAge int32
	var badActive bool

	err = pgx.ScanRow(tm, badFields, badValues, &badID, &badAge, &badActive)
	if err == nil {
		fmt.Fprintf(os.Stderr, "Assertion 4 expected scan error, got nil\n")
		os.Exit(1)
	}

	var scanArgErr pgx.ScanArgError
	if !errors.As(err, &scanArgErr) {
		fmt.Fprintf(os.Stderr, "Assertion 4 expected pgx.ScanArgError, got %T: %v\n", err, err)
		os.Exit(1)
	}
	if scanArgErr.ColumnIndex != 1 {
		fmt.Fprintf(os.Stderr, "Assertion 4 expected ColumnIndex=1, got %d\n", scanArgErr.ColumnIndex)
		os.Exit(1)
	}
	if scanArgErr.FieldName != "age" {
		fmt.Fprintf(os.Stderr, "Assertion 4 expected FieldName='age', got %q\n", scanArgErr.FieldName)
		os.Exit(1)
	}
	if scanArgErr.Unwrap() == nil {
		fmt.Fprintf(os.Stderr, "Assertion 4 expected non-nil Unwrap() error\n")
		os.Exit(1)
	}

	// 5. Verify ScanRow returns error when fieldDescriptions and values lengths differ
	err = pgx.ScanRow(tm, textFields[:2], textValues, &id, &username)
	if err == nil {
		fmt.Fprintf(os.Stderr, "Assertion 5 expected error on field count mismatch\n")
		os.Exit(1)
	}

	// 6. Verify ScanRow returns error when fieldDescriptions and dest lengths differ
	err = pgx.ScanRow(tm, textFields, textValues, &id, &username)
	if err == nil {
		fmt.Fprintf(os.Stderr, "Assertion 6 expected error on dest count mismatch\n")
		os.Exit(1)
	}

	// 7. Verify helper DecodeRow and DecodeTextRow
	var hID int32
	var hUser string
	var hActive bool
	err = sample.DecodeTextRow(tm, []string{"id", "username", "is_active"}, []uint32{pgtype.Int4OID, pgtype.TextOID, pgtype.BoolOID}, []string{"789", "carol", "true"}, &hID, &hUser, &hActive)
	if err != nil || hID != 789 || hUser != "carol" || !hActive {
		fmt.Fprintf(os.Stderr, "Assertion 7 DecodeTextRow failed: err=%v, got (%d, %q, %v)\n", err, hID, hUser, hActive)
		os.Exit(1)
	}

	// 8. Verify helper AsScanArgError and FormatScanError
	scanErrPtr, ok := sample.AsScanArgError(err)
	if ok || scanErrPtr != nil {
		fmt.Fprintf(os.Stderr, "Assertion 8 expected false for nil error\n")
		os.Exit(1)
	}

	badErr := sample.DecodeTextRow(tm, []string{"id", "score"}, []uint32{pgtype.Int4OID, pgtype.Int4OID}, []string{"1", "invalid_int"}, &hID, &hID)
	scanErrPtr, ok = sample.AsScanArgError(badErr)
	if !ok || scanErrPtr == nil || scanErrPtr.ColumnIndex != 1 || scanErrPtr.FieldName != "score" {
		fmt.Fprintf(os.Stderr, "Assertion 8 AsScanArgError failed: ok=%v, scanErr=%+v\n", ok, scanErrPtr)
		os.Exit(1)
	}

	formatted := sample.FormatScanError(badErr)
	if !strings.Contains(formatted, "column 1") || !strings.Contains(formatted, "score") {
		fmt.Fprintf(os.Stderr, "Assertion 8 FormatScanError unexpected: %q\n", formatted)
		os.Exit(1)
	}

	fmt.Println("PASS: all pgx.ScanRow and pgx.ScanArgError contract assertions passed.")
}