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

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.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:
  - AppendRows
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:c95182d58b82c18b10a8cf56e0b903792a814107a624552398c0dc87cf75bb3b","contract":["pgx.AppendRows appends mapped elements to existing non-empty slice using RowToFunc","pgx.AppendRows appends elements to nil or empty slice producing a new populated slice","pgx.AppendRows automatically closes rows upon completion","pgx.AppendRows supports pgx.RowTo for scanning single scalar column types","pgx.AppendRows supports pgx.RowToStructByName and pgx.RowToAddrOfStructByName for struct mapping","pgx.AppendRows aborts and closes rows when row scanning or iteration returns an error","sample helpers provide typed row appending utilities for slices, scalars, and structs"],"goal":"verify github.com/jackc/pgx/v5.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":["AppendRows"]},"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":["AppendRows"],"verifierAdapter":"golang@1"}

module sample

go 1.26.5

require (
	github.com/jackc/pgpassfile v1.0.0 // indirect
	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
	github.com/jackc/pgx/v5 v5.10.0 // 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/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/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=
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=

package sample

import (
	"errors"
	"fmt"
	"reflect"

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

// CollectAppendedValues appends rows converted by the supplied RowToFunc into the existing slice.
// It closes the rows automatically on return.
func CollectAppendedValues[T any, S ~[]T](slice S, rows pgx.Rows, fn pgx.RowToFunc[T]) (S, error) {
	return pgx.AppendRows(slice, rows, fn)
}

// CollectAppendedScalars appends single scalar column values into the existing slice using pgx.RowTo.
// It closes the rows automatically on return.
func CollectAppendedScalars[T any, S ~[]T](slice S, rows pgx.Rows) (S, error) {
	return pgx.AppendRows(slice, rows, pgx.RowTo[T])
}

// CollectAppendedStructs appends mapped struct instances into the existing slice using pgx.RowToStructByName.
// It closes the rows automatically on return.
func CollectAppendedStructs[T any, S ~[]T](slice S, rows pgx.Rows) (S, error) {
	return pgx.AppendRows(slice, rows, pgx.RowToStructByName[T])
}

// CollectAppendedStructPointers appends mapped struct pointers into the existing slice using pgx.RowToAddrOfStructByName.
// It closes the rows automatically on return.
func CollectAppendedStructPointers[T any, S ~[]*T](slice S, rows pgx.Rows) (S, error) {
	return pgx.AppendRows(slice, rows, pgx.RowToAddrOfStructByName[T])
}

// MockRows is an in-memory implementation of pgx.Rows for offline testing and verification.
type MockRows struct {
	fieldDescriptions []pgconn.FieldDescription
	data              [][]any
	idx               int
	closed            bool
	err               error
	commandTag        pgconn.CommandTag
	failAtIndex       int
	failErr           error
}

// NewMockRows constructs a MockRows instance with field names and 2D row values.
func NewMockRows(fields []string, rows [][]any) *MockRows {
	fds := make([]pgconn.FieldDescription, len(fields))
	for i, f := range fields {
		fds[i] = pgconn.FieldDescription{Name: f}
	}
	return &MockRows{
		fieldDescriptions: fds,
		data:              rows,
		idx:               -1,
		closed:            false,
		failAtIndex:       -1,
	}
}

// NewErrorMockRows constructs a MockRows instance that injects an error during iteration.
func NewErrorMockRows(fields []string, rows [][]any, failAtIndex int, failErr error) *MockRows {
	m := NewMockRows(fields, rows)
	m.failAtIndex = failAtIndex
	m.failErr = failErr
	return m
}

// Close marks the rows as closed.
func (m *MockRows) Close() {
	m.closed = true
}

// IsClosed reports whether Close has been called.
func (m *MockRows) IsClosed() bool {
	return m.closed
}

// Err returns any error encountered during iteration.
func (m *MockRows) Err() error {
	return m.err
}

// CommandTag returns the command tag for the query.
func (m *MockRows) CommandTag() pgconn.CommandTag {
	return m.commandTag
}

// FieldDescriptions returns descriptions of the columns.
func (m *MockRows) FieldDescriptions() []pgconn.FieldDescription {
	return m.fieldDescriptions
}

// Next advances to the next row.
func (m *MockRows) Next() bool {
	if m.closed {
		return false
	}
	m.idx++
	if m.failAtIndex >= 0 && m.idx == m.failAtIndex {
		m.err = m.failErr
		return false
	}
	if m.idx < len(m.data) {
		return true
	}
	return false
}

// Scan assigns column values of the current row to dest pointers.
func (m *MockRows) Scan(dest ...any) error {
	if m.idx < 0 || m.idx >= len(m.data) {
		return errors.New("scan called out of range")
	}
	row := m.data[m.idx]
	if len(dest) != len(row) {
		return fmt.Errorf("scan target count %d mismatch row value count %d", len(dest), len(row))
	}
	for i, d := range dest {
		val := row[i]
		if err := assignValue(d, val); err != nil {
			return err
		}
	}
	return nil
}

// Values returns the current row values.
func (m *MockRows) Values() ([]any, error) {
	if m.idx < 0 || m.idx >= len(m.data) {
		return nil, errors.New("values called out of range")
	}
	return m.data[m.idx], nil
}

// RawValues returns nil raw values.
func (m *MockRows) RawValues() [][]byte {
	return nil
}

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

func assignValue(dest any, src any) error {
	if dest == nil {
		return errors.New("cannot scan into nil target")
	}
	dv := reflect.ValueOf(dest)
	if dv.Kind() != reflect.Ptr || dv.IsNil() {
		return fmt.Errorf("dest must be a non-nil pointer, got %T", dest)
	}
	elem := dv.Elem()
	if src == nil {
		elem.Set(reflect.Zero(elem.Type()))
		return nil
	}
	sv := reflect.ValueOf(src)
	if sv.Type().AssignableTo(elem.Type()) {
		elem.Set(sv)
		return nil
	}
	if sv.Type().ConvertibleTo(elem.Type()) {
		elem.Set(sv.Convert(elem.Type()))
		return nil
	}
	return fmt.Errorf("cannot assign %T to %s", src, elem.Type())
}

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

type Account struct {
	ID     int    `db:"id"`
	Name   string `db:"name"`
	Active bool   `db:"active"`
}

func main() {
	// 1. Verify pgx.AppendRows appends to existing non-empty slice using RowToFunc
	existingStrings := []string{"first", "second"}
	rows1 := sample.NewMockRows([]string{"val"}, [][]any{{"third"}, {"fourth"}})
	result1, err := pgx.AppendRows(existingStrings, rows1, pgx.RowTo[string])
	if err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 1 failed: AppendRows returned error: %v\n", err)
		os.Exit(1)
	}
	expectedStrings := []string{"first", "second", "third", "fourth"}
	if !reflect.DeepEqual(result1, expectedStrings) {
		fmt.Fprintf(os.Stderr, "Assertion 1 failed: got %v, want %v\n", result1, expectedStrings)
		os.Exit(1)
	}
	if !rows1.IsClosed() {
		fmt.Fprintf(os.Stderr, "Assertion 1 failed: rows were not closed\n")
		os.Exit(1)
	}

	// 2. Verify pgx.AppendRows appends to nil or empty slice producing populated slice
	var nilInts []int
	rows2 := sample.NewMockRows([]string{"num"}, [][]any{{100}, {200}, {300}})
	result2, err := pgx.AppendRows(nilInts, rows2, pgx.RowTo[int])
	if err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 2 failed: AppendRows returned error: %v\n", err)
		os.Exit(1)
	}
	expectedInts := []int{100, 200, 300}
	if !reflect.DeepEqual(result2, expectedInts) {
		fmt.Fprintf(os.Stderr, "Assertion 2 failed: got %v, want %v\n", result2, expectedInts)
		os.Exit(1)
	}
	if !rows2.IsClosed() {
		fmt.Fprintf(os.Stderr, "Assertion 2 failed: rows were not closed\n")
		os.Exit(1)
	}

	// 3. Verify pgx.AppendRows automatically closes rows upon completion
	emptyRows := sample.NewMockRows([]string{"val"}, [][]any{})
	emptyResult, err := pgx.AppendRows([]string{"init"}, emptyRows, pgx.RowTo[string])
	if err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 3 failed: unexpected error on empty rows: %v\n", err)
		os.Exit(1)
	}
	if len(emptyResult) != 1 || emptyResult[0] != "init" {
		fmt.Fprintf(os.Stderr, "Assertion 3 failed: expected slice untouched: got %v\n", emptyResult)
		os.Exit(1)
	}
	if !emptyRows.IsClosed() {
		fmt.Fprintf(os.Stderr, "Assertion 3 failed: empty rows were not closed\n")
		os.Exit(1)
	}

	// 4. Verify pgx.AppendRows supports pgx.RowTo for scanning single scalar column types
	scalarRows := sample.NewMockRows([]string{"price"}, [][]any{{19.99}, {42.50}})
	initialFloats := []float64{5.00}
	floatResult, err := sample.CollectAppendedScalars(initialFloats, scalarRows)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 4 failed: CollectAppendedScalars returned error: %v\n", err)
		os.Exit(1)
	}
	expectedFloats := []float64{5.00, 19.99, 42.50}
	if !reflect.DeepEqual(floatResult, expectedFloats) {
		fmt.Fprintf(os.Stderr, "Assertion 4 failed: got %v, want %v\n", floatResult, expectedFloats)
		os.Exit(1)
	}

	// 5. Verify pgx.AppendRows supports pgx.RowToStructByName and pgx.RowToAddrOfStructByName for struct mapping
	structRows := sample.NewMockRows(
		[]string{"id", "name", "active"},
		[][]any{
			{2, "Bob", true},
			{3, "Charlie", false},
		},
	)
	initialAccounts := []Account{
		{ID: 1, Name: "Alice", Active: true},
	}
	accountResult, err := sample.CollectAppendedStructs(initialAccounts, structRows)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 5 failed: CollectAppendedStructs returned error: %v\n", err)
		os.Exit(1)
	}
	expectedAccounts := []Account{
		{ID: 1, Name: "Alice", Active: true},
		{ID: 2, Name: "Bob", Active: true},
		{ID: 3, Name: "Charlie", Active: false},
	}
	if !reflect.DeepEqual(accountResult, expectedAccounts) {
		fmt.Fprintf(os.Stderr, "Assertion 5 failed: got %+v, want %+v\n", accountResult, expectedAccounts)
		os.Exit(1)
	}

	// Struct pointer mapping
	ptrRows := sample.NewMockRows(
		[]string{"id", "name", "active"},
		[][]any{
			{20, "Eva", true},
		},
	)
	initialPtrs := []*Account{
		{ID: 10, Name: "Dan", Active: false},
	}
	ptrResult, err := sample.CollectAppendedStructPointers(initialPtrs, ptrRows)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 5 (ptrs) failed: CollectAppendedStructPointers returned error: %v\n", err)
		os.Exit(1)
	}
	if len(ptrResult) != 2 || ptrResult[0].Name != "Dan" || ptrResult[1].Name != "Eva" || ptrResult[1].ID != 20 {
		fmt.Fprintf(os.Stderr, "Assertion 5 (ptrs) failed: got %+v, %+v\n", ptrResult[0], ptrResult[1])
		os.Exit(1)
	}

	// 6. Verify pgx.AppendRows aborts and closes rows when row scanning or iteration returns an error
	simulatedErr := errors.New("simulated stream failure")
	errRows := sample.NewErrorMockRows([]string{"val"}, [][]any{{"a"}, {"b"}, {"c"}}, 1, simulatedErr)
	_, err = pgx.AppendRows([]string{"base"}, errRows, pgx.RowTo[string])
	if err == nil {
		fmt.Fprintf(os.Stderr, "Assertion 6 failed: expected error from AppendRows\n")
		os.Exit(1)
	}
	if !errRows.IsClosed() {
		fmt.Fprintf(os.Stderr, "Assertion 6 failed: error rows were not closed\n")
		os.Exit(1)
	}

	// 7. Verify sample helpers provide typed row appending utilities for slices, scalars, and structs
	customFuncRows := sample.NewMockRows([]string{"num"}, [][]any{{1}, {2}, {3}})
	doubled, err := sample.CollectAppendedValues([]int{0}, customFuncRows, func(row pgx.CollectableRow) (int, error) {
		val, err := pgx.RowTo[int](row)
		if err != nil {
			return 0, err
		}
		return val * 2, nil
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 7 failed: CollectAppendedValues returned error: %v\n", err)
		os.Exit(1)
	}
	expectedDoubled := []int{0, 2, 4, 6}
	if !reflect.DeepEqual(doubled, expectedDoubled) {
		fmt.Fprintf(os.Stderr, "Assertion 7 failed: got %v, want %v\n", doubled, expectedDoubled)
		os.Exit(1)
	}

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