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

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.RowScanner 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.RowScanner

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:0eb57769b6d432e63a6dc9cc53e9c67b565aef494fe7e060b1dbdd8858e83fdd","contract":["pgx.RowScanner interface requires ScanRow(Rows) error method","Custom type implementing ScanRow(pgx.Rows) error satisfies pgx.RowScanner interface","RowScanner scans columnar data across multiple rows into structured entities","RowScanner error encountered in ScanRow propagates to row scanning caller"],"goal":"verify github.com/jackc/pgx/v5.RowScanner 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.RowScanner"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/jackc/pgx/v5@v5.10.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/jackc/pgx/v5@v5.10.0","symbols":["github.com/jackc/pgx/v5.RowScanner"],"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 sample

import (
	"errors"
	"fmt"

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

// Account represents a domain entity scanned directly from a database row.
type Account struct {
	ID     int64
	Name   string
	Email  string
	Active bool
}

// Ensure Account implements pgx.RowScanner at compile time.
var _ pgx.RowScanner = (*Account)(nil)

// ScanRow implements pgx.RowScanner for Account.
func (a *Account) ScanRow(rows pgx.Rows) error {
	fields := rows.FieldDescriptions()
	if len(fields) < 4 {
		return fmt.Errorf("expected at least 4 columns, got %d", len(fields))
	}
	return rows.Scan(&a.ID, &a.Name, &a.Email, &a.Active)
}

// FailingScanner is a scanner designed to simulate scan failures.
type FailingScanner struct {
	Err error
}

// Ensure FailingScanner implements pgx.RowScanner at compile time.
var _ pgx.RowScanner = (*FailingScanner)(nil)

// ScanRow implements pgx.RowScanner for FailingScanner.
func (f *FailingScanner) ScanRow(rows pgx.Rows) error {
	if f.Err != nil {
		return f.Err
	}
	return errors.New("scan failure")
}

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

package main

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

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

// mockRows implements pgx.Rows to enable deterministic offline verification.
type mockRows struct {
	closed     bool
	fields     []pgconn.FieldDescription
	rows       [][]any
	currentRow int
	err        error
}

func newMockRows(fields []pgconn.FieldDescription, rows [][]any) *mockRows {
	return &mockRows{
		fields:     fields,
		rows:       rows,
		currentRow: -1,
	}
}

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

func (m *mockRows) Scan(dest ...any) error {
	if m.currentRow < 0 || m.currentRow >= len(m.rows) {
		return errors.New("scan called outside valid row range")
	}

	// Single argument implementing RowScanner receives the entire row
	if len(dest) == 1 {
		if rs, ok := dest[0].(pgx.RowScanner); ok {
			err := rs.ScanRow(m)
			if err != nil {
				m.err = err
			}
			return err
		}
	}

	rowValues := m.rows[m.currentRow]
	if len(dest) != len(rowValues) {
		return fmt.Errorf("column count mismatch: expected %d destinations, got %d", len(rowValues), len(dest))
	}

	for i, d := range dest {
		switch target := d.(type) {
		case *int64:
			if v, ok := rowValues[i].(int64); ok {
				*target = v
			} else {
				return fmt.Errorf("cannot scan %T to int64", rowValues[i])
			}
		case *string:
			if v, ok := rowValues[i].(string); ok {
				*target = v
			} else {
				return fmt.Errorf("cannot scan %T to string", rowValues[i])
			}
		case *bool:
			if v, ok := rowValues[i].(bool); ok {
				*target = v
			} else {
				return fmt.Errorf("cannot scan %T to bool", rowValues[i])
			}
		default:
			return fmt.Errorf("unsupported type: %T", d)
		}
	}
	return nil
}

func (m *mockRows) Values() ([]any, error) {
	if m.currentRow < 0 || m.currentRow >= len(m.rows) {
		return nil, errors.New("values called outside valid row range")
	}
	return m.rows[m.currentRow], nil
}

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

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

func main() {
	// Assertion 1: pgx.RowScanner interface requires ScanRow(Rows) error method
	scannerType := reflect.TypeOf((*pgx.RowScanner)(nil)).Elem()
	if scannerType.NumMethod() != 1 {
		fmt.Fprintf(os.Stderr, "expected 1 method on pgx.RowScanner, got %d\n", scannerType.NumMethod())
		os.Exit(1)
	}
	method := scannerType.Method(0)
	if method.Name != "ScanRow" {
		fmt.Fprintf(os.Stderr, "expected method name 'ScanRow', got %q\n", method.Name)
		os.Exit(1)
	}

	// Assertion 2: Custom type implementing ScanRow(pgx.Rows) error satisfies pgx.RowScanner interface
	var _ pgx.RowScanner = (*sample.Account)(nil)
	var account pgx.RowScanner = &sample.Account{}
	if account == nil {
		fmt.Fprintf(os.Stderr, "expected non-nil RowScanner instance\n")
		os.Exit(1)
	}

	// Assertion 3: RowScanner scans columnar data across multiple rows into structured entities
	fields := []pgconn.FieldDescription{
		{Name: "id"},
		{Name: "name"},
		{Name: "email"},
		{Name: "active"},
	}
	records := [][]any{
		{int64(1), "Alice", "alice@example.com", true},
		{int64(2), "Bob", "bob@example.com", false},
	}

	rows := newMockRows(fields, records)
	var accounts []sample.Account
	for rows.Next() {
		var acc sample.Account
		if err := rows.Scan(&acc); err != nil {
			fmt.Fprintf(os.Stderr, "failed scanning account: %v\n", err)
			os.Exit(1)
		}
		accounts = append(accounts, acc)
	}

	if err := rows.Err(); err != nil {
		fmt.Fprintf(os.Stderr, "rows error: %v\n", err)
		os.Exit(1)
	}

	if len(accounts) != 2 {
		fmt.Fprintf(os.Stderr, "expected 2 accounts, got %d\n", len(accounts))
		os.Exit(1)
	}
	if accounts[0].ID != 1 || accounts[0].Name != "Alice" || accounts[0].Email != "alice@example.com" || !accounts[0].Active {
		fmt.Fprintf(os.Stderr, "unexpected account 0: %+v\n", accounts[0])
		os.Exit(1)
	}
	if accounts[1].ID != 2 || accounts[1].Name != "Bob" || accounts[1].Email != "bob@example.com" || accounts[1].Active {
		fmt.Fprintf(os.Stderr, "unexpected account 1: %+v\n", accounts[1])
		os.Exit(1)
	}

	// Assertion 4: RowScanner error encountered in ScanRow propagates to row scanning caller
	expectedErr := errors.New("custom scanner failed")
	failingScanner := &sample.FailingScanner{Err: expectedErr}
	errRows := newMockRows(fields, records)
	if errRows.Next() {
		err := errRows.Scan(failingScanner)
		if !errors.Is(err, expectedErr) {
			fmt.Fprintf(os.Stderr, "expected error %v, got %v\n", expectedErr, err)
			os.Exit(1)
		}
	}

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