github.com/jackc/pgx/v5 v5.10.0: RowToStructByPos, RowToAddrOfStructByPos

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 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
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:9b8b93e903ec467a1503d36910efa3e8d8f7290d5bd0847596e07477fd612452","contract":["pgx.RowToStructByPos scans row columns into struct fields by ordinal position","pgx.RowToAddrOfStructByPos scans columns into pointer to struct by ordinal position","pgx.CollectOneRow with RowToStructByPos returns pgx.ErrNoRows when empty","pgx.CollectExactlyOneRow with RowToStructByPos returns pgx.ErrTooManyRows when multiple rows are present","pgx.RowToStructByPos maps columns regardless of column header names"],"goal":"verify pgx.RowToStructByPos and pgx.RowToAddrOfStructByPos 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.RowToStructByPos","github.com/jackc/pgx/v5.RowToAddrOfStructByPos"]},"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":["github.com/jackc/pgx/v5.RowToStructByPos","github.com/jackc/pgx/v5.RowToAddrOfStructByPos"],"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 main

import (
	"fmt"

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

// Person represents a data structure mapped by column position.
type Person struct {
	ID   int64
	Name string
	Age  int
}

func main() {
	// RowToStructByPos creates a RowToFunc that scans columns in ordinal order into struct fields.
	rowToPerson := pgx.RowToStructByPos[Person]
	rowToAddrOfPerson := pgx.RowToAddrOfStructByPos[Person]

	fmt.Printf("Configured RowToStructByPos: %T\n", rowToPerson)
	fmt.Printf("Configured RowToAddrOfStructByPos: %T\n", rowToAddrOfPerson)
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/github.com/jackc/pgx/v5@v5.10.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/jackc/pgx/v5@v5.10.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@11.8.0",
    "runtime": "node@24.13.1"
  }
}

package main

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

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

func assertTrue(name string, condition bool) {
	if !condition {
		fmt.Fprintf(os.Stderr, "Assertion failed for %s: expected true, got false\n", name)
		os.Exit(1)
	}
}

func assertEqualInt(name string, actual, expected int) {
	if actual != expected {
		fmt.Fprintf(os.Stderr, "Assertion failed for %s: got %d, expected %d\n", name, actual, expected)
		os.Exit(1)
	}
}

func assertEqualInt64(name string, actual, expected int64) {
	if actual != expected {
		fmt.Fprintf(os.Stderr, "Assertion failed for %s: got %d, expected %d\n", name, actual, expected)
		os.Exit(1)
	}
}

func assertEqualString(name, actual, expected string) {
	if actual != expected {
		fmt.Fprintf(os.Stderr, "Assertion failed for %s: got %q, expected %q\n", name, actual, expected)
		os.Exit(1)
	}
}

type mockRows struct {
	fields []pgconn.FieldDescription
	rows   [][]any
	idx    int
	closed bool
	err    error
}

func (m *mockRows) Close() {
	m.closed = true
}

func (m *mockRows) Err() error {
	return m.err
}

func (m *mockRows) CommandTag() pgconn.CommandTag {
	return pgconn.CommandTag{}
}

func (m *mockRows) FieldDescriptions() []pgconn.FieldDescription {
	return m.fields
}

func (m *mockRows) Next() bool {
	m.idx++
	return m.idx <= len(m.rows)
}

func (m *mockRows) Scan(dest ...any) error {
	if m.idx < 1 || m.idx > len(m.rows) {
		return errors.New("scan called out of range")
	}
	row := m.rows[m.idx-1]
	if len(dest) != len(row) {
		return fmt.Errorf("expected %d dests, got %d", len(row), len(dest))
	}
	for i, d := range dest {
		val := row[i]
		if d == nil {
			continue
		}
		dv := reflect.ValueOf(d)
		if dv.Kind() != reflect.Ptr || dv.IsNil() {
			return fmt.Errorf("dest[%d] must be a non-nil pointer", i)
		}
		elem := dv.Elem()
		if val == nil {
			elem.Set(reflect.Zero(elem.Type()))
		} else {
			rv := reflect.ValueOf(val)
			if rv.Type().AssignableTo(elem.Type()) {
				elem.Set(rv)
			} else if rv.Type().ConvertibleTo(elem.Type()) {
				elem.Set(rv.Convert(elem.Type()))
			} else {
				return fmt.Errorf("cannot assign %v to %v", rv.Type(), elem.Type())
			}
		}
	}
	return nil
}

func (m *mockRows) Values() ([]any, error) {
	if m.idx < 1 || m.idx > len(m.rows) {
		return nil, errors.New("values called out of range")
	}
	return m.rows[m.idx-1], nil
}

func (m *mockRows) RawValues() [][]byte {
	return nil
}

func (m *mockRows) Conn() *pgx.Conn {
	return nil
}

type Person struct {
	ID   int64
	Name string
	Age  int
}

func main() {
	fields := []pgconn.FieldDescription{
		{Name: "c0"},
		{Name: "c1"},
		{Name: "c2"},
	}
	rowsData := [][]any{
		{int64(1), "Alice", 30},
		{int64(2), "Bob", 25},
	}

	// Contract: pgx.RowToStructByPos scans row columns into struct fields by ordinal position
	rowsMulti := &mockRows{fields: fields, rows: rowsData}
	people, err := pgx.CollectRows(rowsMulti, pgx.RowToStructByPos[Person])
	assertTrue("CollectRows with RowToStructByPos returns nil error", err == nil)
	assertEqualInt("CollectRows returns 2 items", len(people), 2)
	assertEqualInt64("First person ID matches", people[0].ID, 1)
	assertEqualString("First person Name matches", people[0].Name, "Alice")
	assertEqualInt("First person Age matches", people[0].Age, 30)
	assertEqualInt64("Second person ID matches", people[1].ID, 2)
	assertEqualString("Second person Name matches", people[1].Name, "Bob")
	assertEqualInt("Second person Age matches", people[1].Age, 25)

	// Contract: pgx.RowToAddrOfStructByPos scans columns into pointer to struct by ordinal position
	rowsPtr := &mockRows{fields: fields, rows: rowsData[:1]}
	ptrPerson, err := pgx.CollectOneRow(rowsPtr, pgx.RowToAddrOfStructByPos[Person])
	assertTrue("CollectOneRow with RowToAddrOfStructByPos returns nil error", err == nil)
	assertTrue("Returned pointer is non-nil", ptrPerson != nil)
	assertEqualInt64("Pointer person ID matches", ptrPerson.ID, 1)
	assertEqualString("Pointer person Name matches", ptrPerson.Name, "Alice")
	assertEqualInt("Pointer person Age matches", ptrPerson.Age, 30)

	// Contract: pgx.CollectOneRow with RowToStructByPos returns pgx.ErrNoRows when empty
	rowsEmpty := &mockRows{fields: fields, rows: nil}
	_, errEmpty := pgx.CollectOneRow(rowsEmpty, pgx.RowToStructByPos[Person])
	assertTrue("CollectOneRow on empty rows returns ErrNoRows", errors.Is(errEmpty, pgx.ErrNoRows))

	// Contract: pgx.CollectExactlyOneRow with RowToStructByPos returns pgx.ErrTooManyRows when multiple rows are present
	rowsTooMany := &mockRows{fields: fields, rows: rowsData}
	_, errTooMany := pgx.CollectExactlyOneRow(rowsTooMany, pgx.RowToStructByPos[Person])
	assertTrue("CollectExactlyOneRow on multiple rows returns ErrTooManyRows", errors.Is(errTooMany, pgx.ErrTooManyRows))

	// Contract: pgx.RowToStructByPos maps columns regardless of column header names
	unnamedFields := []pgconn.FieldDescription{
		{Name: "random_col_1"},
		{Name: "another_col"},
		{Name: "xyz"},
	}
	rowsArbitraryNames := &mockRows{fields: unnamedFields, rows: rowsData[:1]}
	personArbitrary, errArbitrary := pgx.CollectOneRow(rowsArbitraryNames, pgx.RowToStructByPos[Person])
	assertTrue("RowToStructByPos succeeds with arbitrary column names", errArbitrary == nil)
	assertEqualInt64("Arbitrary column name ID matches", personArbitrary.ID, 1)
	assertEqualString("Arbitrary column name Name matches", personArbitrary.Name, "Alice")
	assertEqualInt("Arbitrary column name Age matches", personArbitrary.Age, 30)

	fmt.Println("All pgx.RowToStructByPos and pgx.RowToAddrOfStructByPos contract assertions passed.")
}