github.com/jackc/pgproto3/v2 v2.1.1

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 pkg:golang/github.com/jackc/pgproto3/v2@v2.1.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/jackc/pgproto3/v2@v2.1.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:2a65117435fcec37e709aca421ce7d94288290712788b5ea4193606f7f4b972c","contract":["StartupMessage.Encode and StartupMessage.Decode serialize and deserialize protocol version and connection parameter key-value pairs","Query.Encode and Query.Decode serialize and deserialize SQL query command strings into wire format","ReadyForQuery.Encode and ReadyForQuery.Decode serialize and deserialize backend transaction status indicator bytes","RowDescription.Encode and RowDescription.Decode serialize and deserialize column field descriptions and type OIDs","DataRow.Encode and DataRow.Decode serialize and deserialize row column values including byte payloads and NULL fields","CommandComplete.Encode and CommandComplete.Decode serialize and deserialize command completion tags","AuthenticationOk.Encode and AuthenticationOk.Decode serialize and deserialize backend authentication success response messages","Terminate.Encode and Terminate.Decode serialize and deserialize client connection termination messages","pgproto3.Frontend and pgproto3.Backend exchange frontend and backend wire protocol messages over connected streams"],"goal":"verify pkg:golang/github.com/jackc/pgproto3/v2@v2.1.1","kind":"HOW","packages":["pkg:golang/github.com/jackc/pgproto3/v2@v2.1.1"],"schemaVersion":1},"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/pgproto3/v2@v2.1.1"],"schemaVersion":1,"subject":"pkg:golang/github.com/jackc/pgproto3/v2@v2.1.1","verifierAdapter":"golang@1"}

module sample-pgproto3

go 1.26.6

require github.com/jackc/pgproto3/v2 v2.1.1

require (
	github.com/jackc/chunkreader/v2 v2.0.0 // indirect
	github.com/jackc/pgio v1.0.0 // indirect
)

github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/jackc/chunkreader/v2 v2.0.0 h1:DUwgMQuuPnS0rhMXenUtZpqZqrR/30NWY+qQvTpSvEs=
github.com/jackc/chunkreader/v2 v2.0.0/go.mod h1:odVSm741yZoC3dpHEUXIqA9tQRhFrgOHwnPIn9lDKlk=
github.com/jackc/pgio v1.0.0 h1:g12B9UwVnzGhueNavwioyEEpAmqMe1E/BN9ES+8ovkE=
github.com/jackc/pgio v1.0.0/go.mod h1:oP+2QK2wFfUWgr+gxjoBH9KGBb31Eio69xUb0w5bYf8=
github.com/jackc/pgproto3/v2 v2.1.1 h1:7PQ/4gLoqnl87ZxL7xjO0DR5gYuviDCZxQJsUlFW1eI=
github.com/jackc/pgproto3/v2 v2.1.1/go.mod h1:WfJCnwN3HIg9Ish/j3sgWXnAfK8A9Y0bwXYU5xKaEdA=
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.4.0 h1:2E4SXV/wtOkTonXsotYi4li6zVWxYlZuYNCXe9XRJyk=
github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v2 v2.2.2 h1:ZCJp+EgiOT7lHqUV2J862kp8Qj64Jo6az82+3Td9dZw=
gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=

package main

import (
	"fmt"

	"github.com/jackc/pgproto3/v2"
)

func main() {
	query := &pgproto3.Query{String: "SELECT 1;"}
	encoded := query.Encode(nil)

	var decoded pgproto3.Query
	if err := decoded.Decode(encoded[5:]); err != nil {
		fmt.Printf("decode error: %v\n", err)
		return
	}

	fmt.Printf("Decoded query: %s\n", decoded.String)
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/github.com/jackc/pgproto3/v2@v2.1.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/jackc/pgproto3/v2@v2.1.1"
  ]
}

package main

import (
	"bytes"
	"fmt"
	"os"

	"github.com/jackc/pgproto3/v2"
)

func main() {
	// 1. StartupMessage.Encode and StartupMessage.Decode serialize and deserialize protocol version and connection parameter key-value pairs
	{
		sm := &pgproto3.StartupMessage{
			ProtocolVersion: pgproto3.ProtocolVersionNumber,
			Parameters: map[string]string{
				"user":        "testuser",
				"database":    "testdb",
				"application": "sample-pgproto3",
			},
		}
		buf := sm.Encode(nil)
		var decoded pgproto3.StartupMessage
		if err := decoded.Decode(buf[4:]); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 1 failed Decode: %v\n", err)
			os.Exit(1)
		}
		if decoded.ProtocolVersion != pgproto3.ProtocolVersionNumber {
			fmt.Fprintf(os.Stderr, "Contract 1 failed: protocol version mismatch\n")
			os.Exit(1)
		}
		if decoded.Parameters["user"] != "testuser" || decoded.Parameters["database"] != "testdb" || decoded.Parameters["application"] != "sample-pgproto3" {
			fmt.Fprintf(os.Stderr, "Contract 1 failed: parameter mismatch\n")
			os.Exit(1)
		}
	}

	// 2. Query.Encode and Query.Decode serialize and deserialize SQL query command strings into wire format
	{
		q := &pgproto3.Query{String: "SELECT id, name FROM users WHERE active = true;"}
		buf := q.Encode(nil)
		var decoded pgproto3.Query
		if err := decoded.Decode(buf[5:]); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 2 failed Decode: %v\n", err)
			os.Exit(1)
		}
		if decoded.String != "SELECT id, name FROM users WHERE active = true;" {
			fmt.Fprintf(os.Stderr, "Contract 2 failed: query mismatch: %s\n", decoded.String)
			os.Exit(1)
		}
	}

	// 3. ReadyForQuery.Encode and ReadyForQuery.Decode serialize and deserialize backend transaction status indicator bytes
	{
		rfq := &pgproto3.ReadyForQuery{TxStatus: 'I'}
		buf := rfq.Encode(nil)
		var decoded pgproto3.ReadyForQuery
		if err := decoded.Decode(buf[5:]); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 3 failed Decode: %v\n", err)
			os.Exit(1)
		}
		if decoded.TxStatus != 'I' {
			fmt.Fprintf(os.Stderr, "Contract 3 failed: status mismatch: %c\n", decoded.TxStatus)
			os.Exit(1)
		}
	}

	// 4. RowDescription.Encode and RowDescription.Decode serialize and deserialize column field descriptions and type OIDs
	{
		rd := &pgproto3.RowDescription{
			Fields: []pgproto3.FieldDescription{
				{
					Name:                 []byte("id"),
					TableOID:             0,
					TableAttributeNumber: 0,
					DataTypeOID:          23, // int4
					DataTypeSize:         4,
					TypeModifier:         -1,
					Format:               0,
				},
				{
					Name:                 []byte("title"),
					TableOID:             0,
					TableAttributeNumber: 0,
					DataTypeOID:          25, // text
					DataTypeSize:         -1,
					TypeModifier:         -1,
					Format:               0,
				},
			},
		}
		buf := rd.Encode(nil)
		var decoded pgproto3.RowDescription
		if err := decoded.Decode(buf[5:]); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 4 failed Decode: %v\n", err)
			os.Exit(1)
		}
		if len(decoded.Fields) != 2 {
			fmt.Fprintf(os.Stderr, "Contract 4 failed: field count mismatch: %d\n", len(decoded.Fields))
			os.Exit(1)
		}
		if string(decoded.Fields[0].Name) != "id" || decoded.Fields[0].DataTypeOID != 23 {
			fmt.Fprintf(os.Stderr, "Contract 4 failed: field 0 mismatch\n")
			os.Exit(1)
		}
		if string(decoded.Fields[1].Name) != "title" || decoded.Fields[1].DataTypeOID != 25 {
			fmt.Fprintf(os.Stderr, "Contract 4 failed: field 1 mismatch\n")
			os.Exit(1)
		}
	}

	// 5. DataRow.Encode and DataRow.Decode serialize and deserialize row column values including byte payloads and NULL fields
	{
		dr := &pgproto3.DataRow{
			Values: [][]byte{
				[]byte("42"),
				nil,
				[]byte("hello world"),
			},
		}
		buf := dr.Encode(nil)
		var decoded pgproto3.DataRow
		if err := decoded.Decode(buf[5:]); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 5 failed Decode: %v\n", err)
			os.Exit(1)
		}
		if len(decoded.Values) != 3 {
			fmt.Fprintf(os.Stderr, "Contract 5 failed: value count mismatch\n")
			os.Exit(1)
		}
		if string(decoded.Values[0]) != "42" || decoded.Values[1] != nil || string(decoded.Values[2]) != "hello world" {
			fmt.Fprintf(os.Stderr, "Contract 5 failed: values mismatch\n")
			os.Exit(1)
		}
	}

	// 6. CommandComplete.Encode and CommandComplete.Decode serialize and deserialize command completion tags
	{
		cc := &pgproto3.CommandComplete{
			CommandTag: []byte("INSERT 0 1"),
		}
		buf := cc.Encode(nil)
		var decoded pgproto3.CommandComplete
		if err := decoded.Decode(buf[5:]); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 6 failed Decode: %v\n", err)
			os.Exit(1)
		}
		if string(decoded.CommandTag) != "INSERT 0 1" {
			fmt.Fprintf(os.Stderr, "Contract 6 failed: tag mismatch: %s\n", string(decoded.CommandTag))
			os.Exit(1)
		}
	}

	// 7. AuthenticationOk.Encode and AuthenticationOk.Decode serialize and deserialize backend authentication success response messages
	{
		auth := &pgproto3.AuthenticationOk{}
		buf := auth.Encode(nil)
		var decoded pgproto3.AuthenticationOk
		if err := decoded.Decode(buf[5:]); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 7 failed Decode: %v\n", err)
			os.Exit(1)
		}
	}

	// 8. Terminate.Encode and Terminate.Decode serialize and deserialize client connection termination messages
	{
		term := &pgproto3.Terminate{}
		buf := term.Encode(nil)
		var decoded pgproto3.Terminate
		if err := decoded.Decode(buf[5:]); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 8 failed Decode: %v\n", err)
			os.Exit(1)
		}
	}

	// 9. pgproto3.Frontend and pgproto3.Backend exchange frontend and backend wire protocol messages over connected streams
	{
		clientToServer := &bytes.Buffer{}
		serverToClient := &bytes.Buffer{}

		frontend := pgproto3.NewFrontend(pgproto3.NewChunkReader(serverToClient), clientToServer)
		backend := pgproto3.NewBackend(pgproto3.NewChunkReader(clientToServer), serverToClient)

		// Frontend sends Query
		if err := frontend.Send(&pgproto3.Query{String: "SELECT 100;"}); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 9 failed frontend.Send: %v\n", err)
			os.Exit(1)
		}

		// Backend receives Query
		bMsg, err := backend.Receive()
		if err != nil {
			fmt.Fprintf(os.Stderr, "Contract 9 failed backend.Receive: %v\n", err)
			os.Exit(1)
		}
		q, ok := bMsg.(*pgproto3.Query)
		if !ok || q.String != "SELECT 100;" {
			fmt.Fprintf(os.Stderr, "Contract 9 failed: backend expected Query 'SELECT 100;', got %#v\n", bMsg)
			os.Exit(1)
		}

		// Backend sends AuthenticationOk, RowDescription, DataRow, CommandComplete, ReadyForQuery
		if err := backend.Send(&pgproto3.AuthenticationOk{}); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 9 failed backend.Send AuthOk: %v\n", err)
			os.Exit(1)
		}
		if err := backend.Send(&pgproto3.ReadyForQuery{TxStatus: 'I'}); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 9 failed backend.Send Ready: %v\n", err)
			os.Exit(1)
		}

		// Frontend receives AuthenticationOk
		fMsg1, err := frontend.Receive()
		if err != nil {
			fmt.Fprintf(os.Stderr, "Contract 9 failed frontend.Receive 1: %v\n", err)
			os.Exit(1)
		}
		if _, ok := fMsg1.(*pgproto3.AuthenticationOk); !ok {
			fmt.Fprintf(os.Stderr, "Contract 9 failed: frontend expected AuthenticationOk, got %#v\n", fMsg1)
			os.Exit(1)
		}

		// Frontend receives ReadyForQuery
		fMsg2, err := frontend.Receive()
		if err != nil {
			fmt.Fprintf(os.Stderr, "Contract 9 failed frontend.Receive 2: %v\n", err)
			os.Exit(1)
		}
		rfq, ok := fMsg2.(*pgproto3.ReadyForQuery)
		if !ok || rfq.TxStatus != 'I' {
			fmt.Fprintf(os.Stderr, "Contract 9 failed: frontend expected ReadyForQuery 'I', got %#v\n", fMsg2)
			os.Exit(1)
		}

		// Frontend sends Terminate
		if err := frontend.Send(&pgproto3.Terminate{}); err != nil {
			fmt.Fprintf(os.Stderr, "Contract 9 failed frontend.Send Terminate: %v\n", err)
			os.Exit(1)
		}

		// Backend receives Terminate
		bMsg2, err := backend.Receive()
		if err != nil {
			fmt.Fprintf(os.Stderr, "Contract 9 failed backend.Receive Terminate: %v\n", err)
			os.Exit(1)
		}
		if _, ok := bMsg2.(*pgproto3.Terminate); !ok {
			fmt.Fprintf(os.Stderr, "Contract 9 failed: backend expected Terminate, got %#v\n", bMsg2)
			os.Exit(1)
		}
	}

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