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 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:
  - github.com/jackc/pgx/v5.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:9c014b02c44ce233ebfdac38362edc02bef48094ce0a7cfa3422feddff4920ee","constraints":{"executionContext":"node"},"contract":["pgx.AppendRows iterates through rows and appends mapped items to an existing pre-populated slice","pgx.AppendRows returns the original slice unchanged when rows is empty","pgx.AppendRows automatically closes the rows upon completion","pgx.AppendRows stops iteration early and returns the error when RowToFunc returns an error","pgx.AppendRows returns rows.Err() if rows iteration produced an error","pgx.AppendRows automatically closes rows when an error occurs during iteration"],"goal":"verify 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":["github.com/jackc/pgx/v5.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":["github.com/jackc/pgx/v5.AppendRows"],"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"
)

// User represents a sample domain model.
type User struct {
	ID   int64
	Name string
}

func main() {
	var appendRowsFn = pgx.AppendRows[User, []User]
	fmt.Printf("pgx.AppendRows function type: %T\n", appendRowsFn)
}

{
  "schemaVersion": 1,
  "goal": "verify 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": [
    "github.com/jackc/pgx/v5.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"
	"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 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
	tag    pgconn.CommandTag
	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 m.tag
}

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")
	}
	if len(dest) == 0 {
		return nil
	}
	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 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 User struct {
	ID   int64
	Name string
}

func main() {
	fields := []pgconn.FieldDescription{
		{Name: "id"},
		{Name: "name"},
	}
	sampleData := [][]any{
		{int64(101), "Alice"},
		{int64(102), "Bob"},
		{int64(103), "Charlie"},
	}

	userScanner := func(row pgx.CollectableRow) (User, error) {
		var u User
		err := row.Scan(&u.ID, &u.Name)
		return u, err
	}

	// Contract: pgx.AppendRows iterates through rows and appends mapped items to an existing pre-populated slice
	initialSlice := []User{
		{ID: 100, Name: "Admin"},
	}
	rows1 := &mockRows{fields: fields, rows: sampleData}
	res1, err1 := pgx.AppendRows(initialSlice, rows1, userScanner)
	assertTrue("AppendRows completes without error", err1 == nil)
	assertEqualInt("Appended total count", len(res1), 4)
	assertEqualString("Pre-existing element preserved", res1[0].Name, "Admin")
	assertEqualString("First appended element matches", res1[1].Name, "Alice")
	assertEqualString("Second appended element matches", res1[2].Name, "Bob")
	assertEqualString("Third appended element matches", res1[3].Name, "Charlie")
	assertTrue("Rows closed after successful AppendRows", rows1.closed)

	// Contract: pgx.AppendRows returns the original slice unchanged when rows is empty
	rowsEmpty := &mockRows{fields: fields, rows: [][]any{}}
	emptyInitial := []User{{ID: 1, Name: "Root"}}
	resEmpty, errEmpty := pgx.AppendRows(emptyInitial, rowsEmpty, userScanner)
	assertTrue("AppendRows on empty rows completes without error", errEmpty == nil)
	assertEqualInt("Slice length unchanged", len(resEmpty), 1)
	assertEqualString("Original element preserved", resEmpty[0].Name, "Root")
	assertTrue("Empty rows closed", rowsEmpty.closed)

	// Contract: pgx.AppendRows stops iteration early and returns the error when RowToFunc returns an error
	scanErr := errors.New("mapping failed")
	failingScanner := func(row pgx.CollectableRow) (User, error) {
		var u User
		if err := row.Scan(&u.ID, &u.Name); err != nil {
			return u, err
		}
		if u.ID == 102 {
			return u, scanErr
		}
		return u, nil
	}
	rowsErr := &mockRows{fields: fields, rows: sampleData}
	resErr, errReturned := pgx.AppendRows([]User{}, rowsErr, failingScanner)
	assertTrue("AppendRows returns error when mapper fails", errors.Is(errReturned, scanErr))
	assertTrue("Result is nil on mapper error", resErr == nil)
	assertTrue("Rows closed after mapper error", rowsErr.closed)

	// Contract: pgx.AppendRows returns rows.Err() if rows iteration produced an error
	iterationErr := errors.New("connection broken during iteration")
	rowsWithErr := &mockRows{fields: fields, rows: sampleData, err: iterationErr}
	resIterErr, errIterReturned := pgx.AppendRows([]User{}, rowsWithErr, userScanner)
	assertTrue("AppendRows returns rows.Err()", errors.Is(errIterReturned, iterationErr))
	assertTrue("Result is nil on iteration error", resIterErr == nil)
	assertTrue("Rows closed after iteration error", rowsWithErr.closed)

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