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

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.RowToStructByPos 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:
  - RowToStructByPos
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:22dd9cbfec1b93d2781c8f2518a678477a442bc064968ac88bdcda6ace083abc","contract":["pgx.RowToStructByPos maps row columns to struct fields positionally in declaration order","pgx.RowToStructByPos ignores unexported struct fields when mapping positionally","pgx.RowToAddrOfStructByPos returns a pointer to struct with positionally mapped field values","pgx.CollectRows with RowToStructByPos collects multiple rows into struct slices and closes rows upon completion","pgx.CollectOneRow and pgx.CollectExactlyOneRow work with RowToStructByPos and return ErrNoRows and ErrTooManyRows as expected","sample helper functions provide positional struct row scanning and collection utilities"],"goal":"verify github.com/jackc/pgx/v5.RowToStructByPos 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":["RowToStructByPos"]},"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":["RowToStructByPos"],"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 (
	"github.com/jackc/pgx/v5"
)

// CollectStructsByPos collects all rows by mapping columns positionally into structs of type T.
func CollectStructsByPos[T any](rows pgx.Rows) ([]T, error) {
	return pgx.CollectRows(rows, pgx.RowToStructByPos[T])
}

// CollectAddrOfStructsByPos collects all rows by mapping columns positionally into struct pointers of type *T.
func CollectAddrOfStructsByPos[T any](rows pgx.Rows) ([]*T, error) {
	return pgx.CollectRows(rows, pgx.RowToAddrOfStructByPos[T])
}

// CollectOneStructByPos collects exactly the first row into a struct of type T.
// Returns pgx.ErrNoRows if rows is empty.
func CollectOneStructByPos[T any](rows pgx.Rows) (T, error) {
	return pgx.CollectOneRow(rows, pgx.RowToStructByPos[T])
}

// CollectExactlyOneStructByPos collects exactly one row into a struct of type T.
// Returns pgx.ErrNoRows if rows is empty or pgx.ErrTooManyRows if more than one row exists.
func CollectExactlyOneStructByPos[T any](rows pgx.Rows) (T, error) {
	return pgx.CollectExactlyOneRow(rows, pgx.RowToStructByPos[T])
}

// ScanStructByPos scans a single collectable row into a struct of type T using positional mapping.
func ScanStructByPos[T any](row pgx.CollectableRow) (T, error) {
	return pgx.RowToStructByPos[T](row)
}

// ScanAddrOfStructByPos scans a single collectable row into a struct pointer of type *T using positional mapping.
func ScanAddrOfStructByPos[T any](row pgx.CollectableRow) (*T, error) {
	return pgx.RowToAddrOfStructByPos[T](row)
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/jackc/pgx/v5.RowToStructByPos 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": [
    "RowToStructByPos"
  ],
  "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"
	"sample"
)

// MockRows implements pgx.Rows for in-memory offline testing of RowToStructByPos contracts.
type MockRows struct {
	fields []pgconn.FieldDescription
	rows   [][]any
	idx    int
	err    error
	closed bool
}

func NewMockRows(colNames []string, rows [][]any) *MockRows {
	fields := make([]pgconn.FieldDescription, len(colNames))
	for i, name := range colNames {
		fields[i] = pgconn.FieldDescription{Name: name}
	}
	return &MockRows{
		fields: fields,
		rows:   rows,
		idx:    0,
	}
}

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 {
	if m.err != nil || m.closed {
		return false
	}
	if m.idx < len(m.rows) {
		m.idx++
		return true
	}
	m.closed = true
	return false
}

func (m *MockRows) Scan(dest ...any) error {
	if m.idx <= 0 || m.idx > len(m.rows) {
		return fmt.Errorf("scan called without valid current row")
	}
	if len(dest) == 1 {
		if rs, ok := dest[0].(pgx.RowScanner); ok {
			return rs.ScanRow(m)
		}
	}
	row := m.rows[m.idx-1]
	if len(dest) != len(row) {
		return fmt.Errorf("expected %d scan destinations, got %d", len(row), len(dest))
	}
	for i, val := range row {
		if dest[i] == nil {
			continue
		}
		target := reflect.ValueOf(dest[i])
		if target.Kind() != reflect.Pointer || target.IsNil() {
			return fmt.Errorf("dest[%d] must be a non-nil pointer", i)
		}
		elem := target.Elem()
		if val == nil {
			elem.Set(reflect.Zero(elem.Type()))
		} else {
			srcVal := reflect.ValueOf(val)
			if srcVal.Type().AssignableTo(elem.Type()) {
				elem.Set(srcVal)
			} else if srcVal.Type().ConvertibleTo(elem.Type()) {
				elem.Set(srcVal.Convert(elem.Type()))
			} else {
				return fmt.Errorf("cannot assign %T to %s", val, elem.Type())
			}
		}
	}
	return nil
}

func (m *MockRows) Values() ([]any, error) {
	if m.idx <= 0 || m.idx > len(m.rows) {
		return nil, fmt.Errorf("values called without valid current row")
	}
	return m.rows[m.idx-1], nil
}

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

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

type User struct {
	ID    int
	Name  string
	Score int
}

type UserWithPrivate struct {
	ID         int
	secret     string
	Name       string
	Score      int
}

func main() {
	cols := []string{"col1", "col2", "col3"}
	data := [][]any{
		{1, "Alice", 100},
		{2, "Bob", 85},
		{3, "Charlie", 92},
	}

	// 1. Verify pgx.RowToStructByPos directly on CollectableRow
	rows1 := NewMockRows(cols, data)
	if !rows1.Next() {
		fmt.Fprintf(os.Stderr, "failed to advance rows1\n")
		os.Exit(1)
	}
	user1, err := pgx.RowToStructByPos[User](rows1)
	if err != nil {
		fmt.Fprintf(os.Stderr, "pgx.RowToStructByPos failed: %v\n", err)
		os.Exit(1)
	}
	if user1.ID != 1 || user1.Name != "Alice" || user1.Score != 100 {
		fmt.Fprintf(os.Stderr, "user1 mismatch: %+v\n", user1)
		os.Exit(1)
	}

	// 2. Verify pgx.RowToStructByPos ignores unexported struct fields
	rowsPrivate := NewMockRows(cols, data)
	if !rowsPrivate.Next() {
		fmt.Fprintf(os.Stderr, "failed to advance rowsPrivate\n")
		os.Exit(1)
	}
	userPriv, err := pgx.RowToStructByPos[UserWithPrivate](rowsPrivate)
	if err != nil {
		fmt.Fprintf(os.Stderr, "pgx.RowToStructByPos with unexported field failed: %v\n", err)
		os.Exit(1)
	}
	if userPriv.ID != 1 || userPriv.secret != "" || userPriv.Name != "Alice" || userPriv.Score != 100 {
		fmt.Fprintf(os.Stderr, "userPriv mismatch: %+v\n", userPriv)
		os.Exit(1)
	}

	// 3. Verify pgx.RowToAddrOfStructByPos returns pointer to struct
	rowsAddr := NewMockRows(cols, data)
	if !rowsAddr.Next() {
		fmt.Fprintf(os.Stderr, "failed to advance rowsAddr\n")
		os.Exit(1)
	}
	userAddr, err := pgx.RowToAddrOfStructByPos[User](rowsAddr)
	if err != nil {
		fmt.Fprintf(os.Stderr, "pgx.RowToAddrOfStructByPos failed: %v\n", err)
		os.Exit(1)
	}
	if userAddr == nil || userAddr.ID != 1 || userAddr.Name != "Alice" || userAddr.Score != 100 {
		fmt.Fprintf(os.Stderr, "userAddr mismatch: %+v\n", userAddr)
		os.Exit(1)
	}

	// 4. Verify pgx.CollectRows with RowToStructByPos
	rowsCollect := NewMockRows(cols, data)
	users, err := pgx.CollectRows(rowsCollect, pgx.RowToStructByPos[User])
	if err != nil {
		fmt.Fprintf(os.Stderr, "CollectRows with RowToStructByPos failed: %v\n", err)
		os.Exit(1)
	}
	expectedUsers := []User{
		{ID: 1, Name: "Alice", Score: 100},
		{ID: 2, Name: "Bob", Score: 85},
		{ID: 3, Name: "Charlie", Score: 92},
	}
	if !reflect.DeepEqual(users, expectedUsers) {
		fmt.Fprintf(os.Stderr, "users mismatch: got %+v, want %+v\n", users, expectedUsers)
		os.Exit(1)
	}
	if !rowsCollect.closed {
		fmt.Fprintf(os.Stderr, "expected rowsCollect to be automatically closed\n")
		os.Exit(1)
	}

	// 5. Verify pgx.CollectOneRow with RowToStructByPos
	rowsOne := NewMockRows(cols, [][]any{{10, "Dave", 77}})
	userOne, err := pgx.CollectOneRow(rowsOne, pgx.RowToStructByPos[User])
	if err != nil {
		fmt.Fprintf(os.Stderr, "CollectOneRow failed: %v\n", err)
		os.Exit(1)
	}
	if userOne.ID != 10 || userOne.Name != "Dave" || userOne.Score != 77 {
		fmt.Fprintf(os.Stderr, "userOne mismatch: %+v\n", userOne)
		os.Exit(1)
	}

	// 6. Verify pgx.CollectOneRow returns pgx.ErrNoRows on empty rows
	rowsEmpty := NewMockRows(cols, [][]any{})
	_, err = pgx.CollectOneRow(rowsEmpty, pgx.RowToStructByPos[User])
	if !errors.Is(err, pgx.ErrNoRows) {
		fmt.Fprintf(os.Stderr, "expected ErrNoRows, got %v\n", err)
		os.Exit(1)
	}

	// 7. Verify pgx.CollectExactlyOneRow returns pgx.ErrTooManyRows on multiple rows
	rowsMultiple := NewMockRows(cols, data)
	_, err = pgx.CollectExactlyOneRow(rowsMultiple, pgx.RowToStructByPos[User])
	if !errors.Is(err, pgx.ErrTooManyRows) {
		fmt.Fprintf(os.Stderr, "expected ErrTooManyRows, got %v\n", err)
		os.Exit(1)
	}

	// 8. Verify sample helper functions
	hRows := NewMockRows(cols, data)
	hUsers, err := sample.CollectStructsByPos[User](hRows)
	if err != nil || !reflect.DeepEqual(hUsers, expectedUsers) {
		fmt.Fprintf(os.Stderr, "sample.CollectStructsByPos failed: %v\n", err)
		os.Exit(1)
	}

	hRowsAddr := NewMockRows(cols, data)
	hAddrs, err := sample.CollectAddrOfStructsByPos[User](hRowsAddr)
	if err != nil || len(hAddrs) != 3 || hAddrs[0].Name != "Alice" || hAddrs[1].Score != 85 {
		fmt.Fprintf(os.Stderr, "sample.CollectAddrOfStructsByPos failed: %v\n", err)
		os.Exit(1)
	}

	hRowsOne := NewMockRows(cols, [][]any{{99, "Single", 50}})
	hSingle, err := sample.CollectOneStructByPos[User](hRowsOne)
	if err != nil || hSingle.ID != 99 || hSingle.Name != "Single" {
		fmt.Fprintf(os.Stderr, "sample.CollectOneStructByPos failed: %v\n", err)
		os.Exit(1)
	}

	hRowsExact := NewMockRows(cols, [][]any{{99, "Exact", 50}})
	hExact, err := sample.CollectExactlyOneStructByPos[User](hRowsExact)
	if err != nil || hExact.ID != 99 || hExact.Name != "Exact" {
		fmt.Fprintf(os.Stderr, "sample.CollectExactlyOneStructByPos failed: %v\n", err)
		os.Exit(1)
	}

	hRowScan := NewMockRows(cols, data)
	if !hRowScan.Next() {
		fmt.Fprintf(os.Stderr, "failed to advance hRowScan\n")
		os.Exit(1)
	}
	hScanned, err := sample.ScanStructByPos[User](hRowScan)
	if err != nil || hScanned.Name != "Alice" {
		fmt.Fprintf(os.Stderr, "sample.ScanStructByPos failed: %v\n", err)
		os.Exit(1)
	}

	hRowScanAddr := NewMockRows(cols, data)
	if !hRowScanAddr.Next() {
		fmt.Fprintf(os.Stderr, "failed to advance hRowScanAddr\n")
		os.Exit(1)
	}
	hScannedAddr, err := sample.ScanAddrOfStructByPos[User](hRowScanAddr)
	if err != nil || hScannedAddr == nil || hScannedAddr.Name != "Alice" {
		fmt.Fprintf(os.Stderr, "sample.ScanAddrOfStructByPos failed: %v\n", err)
		os.Exit(1)
	}

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