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

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.ScanArgError 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:
  - github.com/jackc/pgx/v5.ScanArgError
Required runtime conditions:
  - ecosystem: golang
  - language: go
  - packageManager: go@1.26.5
  - runtime: go@1.26.5

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:78efbdf5cd3abac5df1197612cca215fdf6d486385af0caa8600f910defc44ed","contract":["pgx.ScanArgError encapsulates column index, field name, and underlying error for row scanning failures","pgx.ScanArgError.Error formats descriptive error string containing field name, column index, and underlying error","pgx.ScanArgError.Unwrap returns underlying error and supports standard errors.Is and errors.As unwrapping","sample helper functions construct, detect, extract details from, and format pgx.ScanArgError","sample.ValidateScannedField validates scanned column values and wraps failures into pgx.ScanArgError"],"goal":"verify github.com/jackc/pgx/v5.ScanArgError 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":["github.com/jackc/pgx/v5.ScanArgError"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","ecosystem":"golang","language":"go","os":"windows","osVersionBucket":"11","packageManager":"go","packageManagerVersion":"1.26.5","runtime":"go","runtimeVersion":"1.26.5","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/jackc/pgx/v5@v5.10.0"],"schemaVersion":1,"symbols":["github.com/jackc/pgx/v5.ScanArgError"],"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"
)

// NewScanArgError constructs a pgx.ScanArgError with the specified column index, field name, and underlying error.
func NewScanArgError(columnIndex int, fieldName string, err error) pgx.ScanArgError {
	return pgx.ScanArgError{
		ColumnIndex: columnIndex,
		FieldName:   fieldName,
		Err:         err,
	}
}

// IsScanArgError checks whether err is or wraps a pgx.ScanArgError.
func IsScanArgError(err error) bool {
	var scanErr pgx.ScanArgError
	return errors.As(err, &scanErr)
}

// AsScanArgError extracts a pgx.ScanArgError from err using errors.As.
func AsScanArgError(err error) (pgx.ScanArgError, bool) {
	var scanErr pgx.ScanArgError
	if errors.As(err, &scanErr) {
		return scanErr, true
	}
	return pgx.ScanArgError{}, false
}

// ExtractScanFailureDetails returns column index, field name, and root error from an error if it is a pgx.ScanArgError.
func ExtractScanFailureDetails(err error) (int, string, error, bool) {
	scanErr, ok := AsScanArgError(err)
	if !ok {
		return -1, "", nil, false
	}
	return scanErr.ColumnIndex, scanErr.FieldName, scanErr.Err, true
}

// ValidateScannedField validates a field value using a provided validator and wraps any failure in a pgx.ScanArgError.
func ValidateScannedField[T any](columnIndex int, fieldName string, val T, validate func(T) error) error {
	if validate == nil {
		return nil
	}
	if err := validate(val); err != nil {
		return pgx.ScanArgError{
			ColumnIndex: columnIndex,
			FieldName:   fieldName,
			Err:         err,
		}
	}
	return nil
}

// FormatScanArgSummary formats a concise human-readable diagnostic message for a pgx.ScanArgError.
func FormatScanArgSummary(e pgx.ScanArgError) string {
	return fmt.Sprintf("field '%s' at column index %d failed to scan: %v", e.FieldName, e.ColumnIndex, e.Err)
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/jackc/pgx/v5.ScanArgError 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": [
    "github.com/jackc/pgx/v5.ScanArgError"
  ],
  "runtimeConditions": {
    "ecosystem": "golang",
    "language": "go",
    "packageManager": "go@1.26.5",
    "runtime": "go@1.26.5"
  }
}

package main

import (
	"errors"
	"fmt"
	"os"
	"reflect"
	"strings"

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

func main() {
	// 1. Verify ScanArgError struct fields via reflection
	errType := reflect.TypeOf(pgx.ScanArgError{})
	expectedFields := []string{"ColumnIndex", "FieldName", "Err"}
	for _, fieldName := range expectedFields {
		field, found := errType.FieldByName(fieldName)
		if !found {
			fmt.Fprintf(os.Stderr, "expected struct field %q in pgx.ScanArgError\n", fieldName)
			os.Exit(1)
		}
		if !field.IsExported() {
			fmt.Fprintf(os.Stderr, "field %q must be exported in pgx.ScanArgError\n", fieldName)
			os.Exit(1)
		}
	}

	// 2. Verify ScanArgError creation and field assignments
	baseErr := errors.New("invalid integer syntax")
	scanErr := pgx.ScanArgError{
		ColumnIndex: 2,
		FieldName:   "user_id",
		Err:         baseErr,
	}
	if scanErr.ColumnIndex != 2 || scanErr.FieldName != "user_id" || scanErr.Err != baseErr {
		fmt.Fprintf(os.Stderr, "ScanArgError fields mismatch: got %+v\n", scanErr)
		os.Exit(1)
	}

	// 3. Verify Error() method output contains field name, column index, and root error message
	errMsg := scanErr.Error()
	if !strings.Contains(errMsg, "user_id") {
		fmt.Fprintf(os.Stderr, "Error() message missing field name: got %q\n", errMsg)
		os.Exit(1)
	}
	if !strings.Contains(errMsg, "2") {
		fmt.Fprintf(os.Stderr, "Error() message missing column index: got %q\n", errMsg)
		os.Exit(1)
	}
	if !strings.Contains(errMsg, "invalid integer syntax") {
		fmt.Fprintf(os.Stderr, "Error() message missing underlying error: got %q\n", errMsg)
		os.Exit(1)
	}

	// 4. Verify Unwrap() method and errors.Is / errors.As support
	unwrapped := scanErr.Unwrap()
	if unwrapped != baseErr {
		fmt.Fprintf(os.Stderr, "Unwrap() mismatch: got %v, want %v\n", unwrapped, baseErr)
		os.Exit(1)
	}

	if !errors.Is(scanErr, baseErr) {
		fmt.Fprintf(os.Stderr, "errors.Is(scanErr, baseErr) should be true\n")
		os.Exit(1)
	}

	// Wrapped in outer context error
	wrappedErr := fmt.Errorf("query execution failed: %w", scanErr)
	if !errors.Is(wrappedErr, baseErr) {
		fmt.Fprintf(os.Stderr, "errors.Is(wrappedErr, baseErr) should be true across chain\n")
		os.Exit(1)
	}

	var extracted pgx.ScanArgError
	if !errors.As(wrappedErr, &extracted) {
		fmt.Fprintf(os.Stderr, "errors.As(wrappedErr, &extracted) should find ScanArgError\n")
		os.Exit(1)
	}
	if extracted.ColumnIndex != 2 || extracted.FieldName != "user_id" {
		fmt.Fprintf(os.Stderr, "extracted ScanArgError fields mismatch: got %+v\n", extracted)
		os.Exit(1)
	}

	// 5. Verify sample helper constructors and checkers
	helperErr := sample.NewScanArgError(1, "email", errors.New("empty string"))
	if helperErr.ColumnIndex != 1 || helperErr.FieldName != "email" {
		fmt.Fprintf(os.Stderr, "NewScanArgError failed: got %+v\n", helperErr)
		os.Exit(1)
	}

	if !sample.IsScanArgError(helperErr) {
		fmt.Fprintf(os.Stderr, "IsScanArgError(helperErr) should be true\n")
		os.Exit(1)
	}
	if sample.IsScanArgError(errors.New("plain error")) {
		fmt.Fprintf(os.Stderr, "IsScanArgError(plain error) should be false\n")
		os.Exit(1)
	}

	asErr, ok := sample.AsScanArgError(fmt.Errorf("wrap: %w", helperErr))
	if !ok || asErr.FieldName != "email" || asErr.ColumnIndex != 1 {
		fmt.Fprintf(os.Stderr, "AsScanArgError failed: ok=%v, err=%+v\n", ok, asErr)
		os.Exit(1)
	}

	idx, field, rootErr, ok := sample.ExtractScanFailureDetails(fmt.Errorf("wrap: %w", helperErr))
	if !ok || idx != 1 || field != "email" || rootErr.Error() != "empty string" {
		fmt.Fprintf(os.Stderr, "ExtractScanFailureDetails failed: ok=%v, idx=%d, field=%s, rootErr=%v\n", ok, idx, field, rootErr)
		os.Exit(1)
	}

	// 6. Verify ValidateScannedField helper
	customValidationErr := errors.New("must be positive")
	valErr := sample.ValidateScannedField(3, "age", -5, func(val int) error {
		if val < 0 {
			return customValidationErr
		}
		return nil
	})
	if valErr == nil {
		fmt.Fprintf(os.Stderr, "ValidateScannedField expected error for negative value\n")
		os.Exit(1)
	}
	valScanErr, ok := sample.AsScanArgError(valErr)
	if !ok || valScanErr.ColumnIndex != 3 || valScanErr.FieldName != "age" || !errors.Is(valScanErr, customValidationErr) {
		fmt.Fprintf(os.Stderr, "ValidateScannedField error structure mismatch: got %+v\n", valScanErr)
		os.Exit(1)
	}

	successErr := sample.ValidateScannedField(3, "age", 25, func(val int) error {
		if val < 0 {
			return customValidationErr
		}
		return nil
	})
	if successErr != nil {
		fmt.Fprintf(os.Stderr, "ValidateScannedField expected nil on valid value, got: %v\n", successErr)
		os.Exit(1)
	}

	// 7. Verify FormatScanArgSummary helper
	summary := sample.FormatScanArgSummary(scanErr)
	if !strings.Contains(summary, "user_id") || !strings.Contains(summary, "column index 2") {
		fmt.Fprintf(os.Stderr, "FormatScanArgSummary mismatch: got %q\n", summary)
		os.Exit(1)
	}

	fmt.Println("All pgx.ScanArgError contract assertions passed.")
}