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

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:0cd9bdfb745f54c427aa0bfd3e16bd96a8de5fd2870cde4b90a511620cd6ed26","contract":["pgx.RowToStructByPos maps positional row columns to public struct fields in sequential order","pgx.RowToAddrOfStructByPos scans and returns pointers to allocated structs","pgx.RowToStructByPos ignores struct fields tagged with db:\"-\"","pgx.RowToStructByPos ignores unexported struct fields when matching column positions","pgx.AppendRows appends scanned rows into an existing pre-allocated slice","pgx.AppendRows automatically closes rows upon completion","pgx.RowToStructByPos returns an error when column count does not match exported struct field count","pgx.AppendRows returns an error when row iteration encounters an error"],"goal":"verify pgx.RowToStructByPos and pgx.AppendRows 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":["pgx.AppendRows","pgx.RowToAddrOfStructByPos","pgx.RowToStructByPos"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1,"virtualization":"wsl"},"license":"MIT-0","packages":["pkg:golang/github.com/jackc/pgx/v5@v5.10.0"],"schemaVersion":1,"symbols":["pgx.AppendRows","pgx.RowToAddrOfStructByPos","pgx.RowToStructByPos"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

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 (
	"context"
	"fmt"

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

type InventoryItem struct {
	ID    int64
	SKU   string
	Qty   int
	Price float64
}

func main() {
	ctx := context.Background()
	_ = ctx

	fmt.Println("pgx v5 positional row scanning and appending demonstrated:")
	fmt.Println(" - pgx.RowToStructByPos[InventoryItem]")
	fmt.Println(" - pgx.RowToAddrOfStructByPos[InventoryItem]")
	fmt.Println(" - pgx.AppendRows")

	// Ensure symbols are referenced
	var _ pgx.RowToFunc[InventoryItem] = pgx.RowToStructByPos[InventoryItem]
	var _ pgx.RowToFunc[*InventoryItem] = pgx.RowToAddrOfStructByPos[InventoryItem]
}

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

package main

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

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

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

func newMockRows(fieldNames []string, rows [][]any) *mockRows {
	fields := make([]pgconn.FieldDescription, len(fieldNames))
	for i, name := range fieldNames {
		fields[i] = pgconn.FieldDescription{Name: name}
	}
	return &mockRows{
		fields: fields,
		rows:   rows,
		idx:    -1,
	}
}

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

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

func (m *mockRows) CommandTag() pgconn.CommandTag {
	return pgconn.NewCommandTag(fmt.Sprintf("SELECT %d", len(m.rows)))
}

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

func (m *mockRows) Next() bool {
	if m.closed || m.err != nil {
		return false
	}
	m.idx++
	if m.idx < len(m.rows) {
		return true
	}
	m.Close()
	return false
}

func (m *mockRows) Scan(dest ...any) error {
	if m.idx < 0 || m.idx >= len(m.rows) {
		return errors.New("scan called outside row iteration")
	}
	if len(dest) == 1 {
		if rs, ok := dest[0].(pgx.RowScanner); ok {
			return rs.ScanRow(m)
		}
	}
	row := m.rows[m.idx]
	if len(dest) != len(row) {
		return fmt.Errorf("expected %d destination arguments, 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.Ptr || target.IsNil() {
			return fmt.Errorf("destination argument %d is not a non-nil pointer", i)
		}
		elem := target.Elem()
		if val == nil {
			elem.Set(reflect.Zero(elem.Type()))
			continue
		}
		v := reflect.ValueOf(val)
		if v.Type().AssignableTo(elem.Type()) {
			elem.Set(v)
		} else if v.Type().ConvertibleTo(elem.Type()) {
			elem.Set(v.Convert(elem.Type()))
		} else {
			return fmt.Errorf("cannot assign %v (%T) to %s", val, val, elem.Type())
		}
	}
	return nil
}

func (m *mockRows) Values() ([]any, error) {
	if m.idx < 0 || m.idx >= len(m.rows) {
		return nil, errors.New("values called outside row iteration")
	}
	row := m.rows[m.idx]
	res := make([]any, len(row))
	copy(res, row)
	return res, nil
}

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

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

type Product struct {
	ID     int64
	Name   string
	Price  float64
	Active bool
}

type ProductWithIgnored struct {
	ID      int64
	Name    string
	Ignored string `db:"-"`
	Price   float64
}

type ProductWithPrivate struct {
	ID         int64
	Name       string
	unexported string
	Price      float64
}

func main() {
	// 1. assert pgx.RowToStructByPos maps positional row columns to public struct fields in sequential order
	r1 := newMockRows([]string{"c1", "c2", "c3", "c4"}, [][]any{
		{int64(101), "Alpha", 12.50, true},
		{int64(102), "Beta", 45.00, false},
	})
	products, err1 := pgx.CollectRows(r1, pgx.RowToStructByPos[Product])
	if err1 != nil {
		fmt.Fprintf(os.Stderr, "FAIL: RowToStructByPos failed: %v\n", err1)
		os.Exit(1)
	}
	if len(products) != 2 || products[0].ID != 101 || products[0].Name != "Alpha" || products[0].Price != 12.50 || !products[0].Active ||
		products[1].ID != 102 || products[1].Name != "Beta" || products[1].Price != 45.00 || products[1].Active {
		fmt.Fprintf(os.Stderr, "FAIL: RowToStructByPos output mismatch: %+v\n", products)
		os.Exit(1)
	}

	// 2. assert pgx.RowToAddrOfStructByPos scans and returns pointers to allocated structs
	r2 := newMockRows([]string{"c1", "c2", "c3", "c4"}, [][]any{
		{int64(201), "Gamma", 99.99, true},
	})
	productPtrs, err2 := pgx.CollectRows(r2, pgx.RowToAddrOfStructByPos[Product])
	if err2 != nil {
		fmt.Fprintf(os.Stderr, "FAIL: RowToAddrOfStructByPos failed: %v\n", err2)
		os.Exit(1)
	}
	if len(productPtrs) != 1 || productPtrs[0] == nil || productPtrs[0].ID != 201 || productPtrs[0].Name != "Gamma" || productPtrs[0].Price != 99.99 || !productPtrs[0].Active {
		fmt.Fprintf(os.Stderr, "FAIL: RowToAddrOfStructByPos output mismatch: %+v\n", productPtrs)
		os.Exit(1)
	}

	// 3. assert pgx.RowToStructByPos ignores struct fields tagged with db:"-"
	r3 := newMockRows([]string{"c1", "c2", "c3"}, [][]any{
		{int64(301), "Delta", 7.25},
	})
	ignoredItems, err3 := pgx.CollectRows(r3, pgx.RowToStructByPos[ProductWithIgnored])
	if err3 != nil {
		fmt.Fprintf(os.Stderr, "FAIL: RowToStructByPos with db:\"-\" failed: %v\n", err3)
		os.Exit(1)
	}
	if len(ignoredItems) != 1 || ignoredItems[0].ID != 301 || ignoredItems[0].Name != "Delta" || ignoredItems[0].Ignored != "" || ignoredItems[0].Price != 7.25 {
		fmt.Fprintf(os.Stderr, "FAIL: RowToStructByPos with db:\"-\" mismatch: %+v\n", ignoredItems)
		os.Exit(1)
	}

	// 4. assert pgx.RowToStructByPos ignores unexported struct fields when matching column positions
	r4 := newMockRows([]string{"c1", "c2", "c3"}, [][]any{
		{int64(401), "Epsilon", 18.00},
	})
	privateItems, err4 := pgx.CollectRows(r4, pgx.RowToStructByPos[ProductWithPrivate])
	if err4 != nil {
		fmt.Fprintf(os.Stderr, "FAIL: RowToStructByPos with unexported field failed: %v\n", err4)
		os.Exit(1)
	}
	if len(privateItems) != 1 || privateItems[0].ID != 401 || privateItems[0].Name != "Epsilon" || privateItems[0].Price != 18.00 || privateItems[0].unexported != "" {
		fmt.Fprintf(os.Stderr, "FAIL: RowToStructByPos with unexported field mismatch: %+v\n", privateItems)
		os.Exit(1)
	}

	// 5. assert pgx.AppendRows appends scanned rows into an existing pre-allocated slice
	initialList := []Product{
		{ID: 1, Name: "Base", Price: 5.00, Active: true},
	}
	r5 := newMockRows([]string{"c1", "c2", "c3", "c4"}, [][]any{
		{int64(2), "Appended1", 15.00, true},
		{int64(3), "Appended2", 25.00, false},
	})
	appendedList, err5 := pgx.AppendRows(initialList, r5, pgx.RowToStructByPos[Product])
	if err5 != nil {
		fmt.Fprintf(os.Stderr, "FAIL: AppendRows failed: %v\n", err5)
		os.Exit(1)
	}
	if len(appendedList) != 3 || appendedList[0].ID != 1 || appendedList[1].ID != 2 || appendedList[2].ID != 3 {
		fmt.Fprintf(os.Stderr, "FAIL: AppendRows output mismatch: %+v\n", appendedList)
		os.Exit(1)
	}

	// 6. assert pgx.AppendRows automatically closes rows upon completion
	if !r5.closed {
		fmt.Fprintf(os.Stderr, "FAIL: AppendRows did not close rows on completion\n")
		os.Exit(1)
	}

	// 7. assert pgx.RowToStructByPos returns an error when column count does not match exported struct field count
	r7 := newMockRows([]string{"c1", "c2"}, [][]any{
		{int64(501), "TooFewCols"},
	})
	_, err7 := pgx.CollectRows(r7, pgx.RowToStructByPos[Product])
	if err7 == nil {
		fmt.Fprintf(os.Stderr, "FAIL: expected error for column count mismatch, got nil\n")
		os.Exit(1)
	}

	// 8. assert pgx.AppendRows returns an error when row iteration encounters an error
	simulatedErr := errors.New("simulated database read failure")
	r8 := &mockRows{
		fields: []pgconn.FieldDescription{{Name: "c1"}, {Name: "c2"}, {Name: "c3"}, {Name: "c4"}},
		rows:   [][]any{{int64(601), "FailRow", 50.00, true}},
		idx:    -1,
		err:    simulatedErr,
	}
	_, err8 := pgx.AppendRows([]Product{}, r8, pgx.RowToStructByPos[Product])
	if !errors.Is(err8, simulatedErr) {
		fmt.Fprintf(os.Stderr, "FAIL: expected AppendRows to return simulated error, got: %v\n", err8)
		os.Exit(1)
	}

	// Type assertion check for interface compliance
	var _ pgx.RowToFunc[Product] = pgx.RowToStructByPos[Product]
	var _ pgx.RowToFunc[*Product] = pgx.RowToAddrOfStructByPos[Product]

	fmt.Println("PASS: all pgx.RowToStructByPos and pgx.AppendRows contract assertions satisfied")
}