github.com/jackc/pgx/v5 v5.10.0: pgconn.FieldDescription

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/pgconn.FieldDescription 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/pgconn.FieldDescription

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:779d5256b61eac3233537f11ed8eee81a6845dd7f2a9fb44166292ee43f4efee","contract":["pgconn.FieldDescription defines column metadata including Name, TableOID, TableAttributeNumber, DataTypeOID, DataTypeSize, TypeModifier, and Format","sample helpers construct FieldDescription with specified column attributes and format codes","sample helpers evaluate format predicates (binary vs text), table origin, and variable length data types","sample helpers extract field names, search fields by name (case-sensitive and fold), and filter by table OID"],"goal":"verify github.com/jackc/pgx/v5/pgconn.FieldDescription 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/pgconn.FieldDescription"]},"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},"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/pgconn.FieldDescription"],"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 (
	"strings"

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

// Format codes defined by PostgreSQL wire protocol
const (
	FormatText   int16 = 0
	FormatBinary int16 = 1
)

// NewFieldDescription creates a new pgconn.FieldDescription with the specified column metadata.
func NewFieldDescription(name string, tableOID uint32, tableAttrNum uint16, dataTypeOID uint32, dataTypeSize int16, typeMod int32, format int16) pgconn.FieldDescription {
	return pgconn.FieldDescription{
		Name:                 name,
		TableOID:             tableOID,
		TableAttributeNumber: tableAttrNum,
		DataTypeOID:          dataTypeOID,
		DataTypeSize:         dataTypeSize,
		TypeModifier:         typeMod,
		Format:               format,
	}
}

// IsBinary returns true if the field format is binary (1).
func IsBinary(fd pgconn.FieldDescription) bool {
	return fd.Format == FormatBinary
}

// IsText returns true if the field format is text (0).
func IsText(fd pgconn.FieldDescription) bool {
	return fd.Format == FormatText
}

// IsFromTable returns true if the field originates from a database table (TableOID != 0).
func IsFromTable(fd pgconn.FieldDescription) bool {
	return fd.TableOID != 0
}

// IsVariableLength returns true if the field has variable data type size (DataTypeSize < 0).
func IsVariableLength(fd pgconn.FieldDescription) bool {
	return fd.DataTypeSize < 0
}

// FieldNames extracts column names from a slice of FieldDescription.
func FieldNames(fields []pgconn.FieldDescription) []string {
	names := make([]string, len(fields))
	for i, f := range fields {
		names[i] = f.Name
	}
	return names
}

// FindFieldByName searches for a FieldDescription by name (case-sensitive).
func FindFieldByName(fields []pgconn.FieldDescription, name string) (pgconn.FieldDescription, bool) {
	for _, f := range fields {
		if f.Name == name {
			return f, true
		}
	}
	return pgconn.FieldDescription{}, false
}

// FindFieldByNameFold searches for a FieldDescription by name (case-insensitive).
func FindFieldByNameFold(fields []pgconn.FieldDescription, name string) (pgconn.FieldDescription, bool) {
	for _, f := range fields {
		if strings.EqualFold(f.Name, name) {
			return f, true
		}
	}
	return pgconn.FieldDescription{}, false
}

// FilterFieldsByTableOID filters fields belonging to a specific table OID.
func FilterFieldsByTableOID(fields []pgconn.FieldDescription, tableOID uint32) []pgconn.FieldDescription {
	var filtered []pgconn.FieldDescription
	for _, f := range fields {
		if f.TableOID == tableOID {
			filtered = append(filtered, f)
		}
	}
	return filtered
}

// CountBinaryFields returns the number of binary formatted fields.
func CountBinaryFields(fields []pgconn.FieldDescription) int {
	count := 0
	for _, f := range fields {
		if IsBinary(f) {
			count++
		}
	}
	return count
}

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

package main

import (
	"fmt"
	"os"
	"reflect"

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

func main() {
	// 1. Verify FieldDescription struct definition and field types
	var fd pgconn.FieldDescription
	fdType := reflect.TypeOf(fd)
	if fdType.Kind() != reflect.Struct {
		fmt.Fprintf(os.Stderr, "expected pgconn.FieldDescription to be a struct, got %v\n", fdType)
		os.Exit(1)
	}

	expectedFields := map[string]string{
		"Name":                 "string",
		"TableOID":             "uint32",
		"TableAttributeNumber": "uint16",
		"DataTypeOID":          "uint32",
		"DataTypeSize":         "int16",
		"TypeModifier":         "int32",
		"Format":               "int16",
	}

	for fieldName, expectedType := range expectedFields {
		field, ok := fdType.FieldByName(fieldName)
		if !ok {
			fmt.Fprintf(os.Stderr, "missing field %s in pgconn.FieldDescription\n", fieldName)
			os.Exit(1)
		}
		if field.Type.String() != expectedType {
			fmt.Fprintf(os.Stderr, "field %s expected type %s, got %s\n", fieldName, expectedType, field.Type.String())
			os.Exit(1)
		}
	}

	// 2. Verify FieldDescription construction and field access
	colId := sample.NewFieldDescription("id", 16384, 1, 23, 4, -1, sample.FormatBinary)
	if colId.Name != "id" || colId.TableOID != 16384 || colId.TableAttributeNumber != 1 ||
		colId.DataTypeOID != 23 || colId.DataTypeSize != 4 || colId.TypeModifier != -1 || colId.Format != sample.FormatBinary {
		fmt.Fprintf(os.Stderr, "colId field value mismatch: %+v\n", colId)
		os.Exit(1)
	}

	colName := sample.NewFieldDescription("username", 16384, 2, 25, -1, -1, sample.FormatText)
	if colName.Name != "username" || colName.TableOID != 16384 || colName.TableAttributeNumber != 2 ||
		colName.DataTypeOID != 25 || colName.DataTypeSize != -1 || colName.Format != sample.FormatText {
		fmt.Fprintf(os.Stderr, "colName field value mismatch: %+v\n", colName)
		os.Exit(1)
	}

	colComputed := sample.NewFieldDescription("count", 0, 0, 20, 8, -1, sample.FormatBinary)

	// 3. Verify format and property predicates
	if !sample.IsBinary(colId) || sample.IsText(colId) {
		fmt.Fprintf(os.Stderr, "colId format predicates failed\n")
		os.Exit(1)
	}
	if !sample.IsText(colName) || sample.IsBinary(colName) {
		fmt.Fprintf(os.Stderr, "colName format predicates failed\n")
		os.Exit(1)
	}
	if !sample.IsFromTable(colId) || !sample.IsFromTable(colName) {
		fmt.Fprintf(os.Stderr, "table origin check failed for colId / colName\n")
		os.Exit(1)
	}
	if sample.IsFromTable(colComputed) {
		fmt.Fprintf(os.Stderr, "computed column should not be from table\n")
		os.Exit(1)
	}
	if !sample.IsVariableLength(colName) || sample.IsVariableLength(colId) {
		fmt.Fprintf(os.Stderr, "variable length predicate failed\n")
		os.Exit(1)
	}

	// 4. Verify slice operations (FieldNames, FindFieldByName, FindFieldByNameFold, FilterFieldsByTableOID)
	fields := []pgconn.FieldDescription{colId, colName, colComputed}

	names := sample.FieldNames(fields)
	if len(names) != 3 || names[0] != "id" || names[1] != "username" || names[2] != "count" {
		fmt.Fprintf(os.Stderr, "FieldNames failed: %+v\n", names)
		os.Exit(1)
	}

	found, ok := sample.FindFieldByName(fields, "username")
	if !ok || found.DataTypeOID != 25 {
		fmt.Fprintf(os.Stderr, "FindFieldByName('username') failed: ok=%v, found=%+v\n", ok, found)
		os.Exit(1)
	}

	_, ok = sample.FindFieldByName(fields, "nonexistent")
	if ok {
		fmt.Fprintf(os.Stderr, "FindFieldByName('nonexistent') expected false\n")
		os.Exit(1)
	}

	foundFold, ok := sample.FindFieldByNameFold(fields, "USERNAME")
	if !ok || foundFold.Name != "username" {
		fmt.Fprintf(os.Stderr, "FindFieldByNameFold('USERNAME') failed: ok=%v, found=%+v\n", ok, foundFold)
		os.Exit(1)
	}

	tableFields := sample.FilterFieldsByTableOID(fields, 16384)
	if len(tableFields) != 2 || tableFields[0].Name != "id" || tableFields[1].Name != "username" {
		fmt.Fprintf(os.Stderr, "FilterFieldsByTableOID failed: %+v\n", tableFields)
		os.Exit(1)
	}

	if binCount := sample.CountBinaryFields(fields); binCount != 2 {
		fmt.Fprintf(os.Stderr, "CountBinaryFields expected 2, got %d\n", binCount)
		os.Exit(1)
	}

	fmt.Println("All pgconn.FieldDescription contract assertions passed.")
}