github.com/jackc/pgx/v5 v5.10.0: pgproto3.ReadyForQuery

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/pgproto3.ReadyForQuery 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/pgproto3.ReadyForQuery
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:746e5e96cf0ba31815bd685b881bf9159a5144042afba3ba3985712ed6e51ed3","contract":["pgproto3.ReadyForQuery encodes with message type 'Z' and 4-byte length header containing TxStatus byte","pgproto3.ReadyForQuery decodes 1-byte body slice into TxStatus","pgproto3.ReadyForQuery Decode returns an error when body slice length is not 1","pgproto3.ReadyForQuery implements BackendMessage and marshals to JSON with Type and TxStatus fields","pgproto3.ReadyForQuery UnmarshalJSON correctly restores TxStatus from JSON payload"],"goal":"verify github.com/jackc/pgx/v5/pgproto3.ReadyForQuery 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/pgproto3.ReadyForQuery"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","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/pgproto3.ReadyForQuery"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require github.com/jackc/pgx/v5 v5.10.0

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/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/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
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 (
	"fmt"

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

const (
	// TxStatusIdle indicates backend is idle (outside a transaction block).
	TxStatusIdle = byte('I')
	// TxStatusTransaction indicates backend is inside a transaction block.
	TxStatusTransaction = byte('T')
	// TxStatusError indicates backend is inside a failed transaction block.
	TxStatusError = byte('E')
)

// NewReadyForQuery creates a new ReadyForQuery message with the given transaction status.
func NewReadyForQuery(txStatus byte) *pgproto3.ReadyForQuery {
	return &pgproto3.ReadyForQuery{
		TxStatus: txStatus,
	}
}

// EncodeReadyForQuery encodes a ReadyForQuery message into protocol wire bytes.
func EncodeReadyForQuery(msg *pgproto3.ReadyForQuery) ([]byte, error) {
	if msg == nil {
		return nil, fmt.Errorf("message cannot be nil")
	}
	return msg.Encode(nil)
}

// DecodeReadyForQuery decodes a single-byte payload body into a ReadyForQuery message.
func DecodeReadyForQuery(body []byte) (*pgproto3.ReadyForQuery, error) {
	msg := &pgproto3.ReadyForQuery{}
	if err := msg.Decode(body); err != nil {
		return nil, err
	}
	return msg, nil
}

// IsIdle checks if the transaction status is Idle ('I').
func IsIdle(msg *pgproto3.ReadyForQuery) bool {
	return msg != nil && msg.TxStatus == TxStatusIdle
}

// IsInTransaction checks if the transaction status is in Transaction ('T').
func IsInTransaction(msg *pgproto3.ReadyForQuery) bool {
	return msg != nil && msg.TxStatus == TxStatusTransaction
}

// IsInFailedTransaction checks if the transaction status is in Error/Failed ('E').
func IsInFailedTransaction(msg *pgproto3.ReadyForQuery) bool {
	return msg != nil && msg.TxStatus == TxStatusError
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/jackc/pgx/v5/pgproto3.ReadyForQuery 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/pgproto3.ReadyForQuery"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"os"

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

func main() {
	if err := runContractTests(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract test failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("All ReadyForQuery contract assertions passed successfully.")
}

func runContractTests() error {
	// Assertion 1: pgproto3.ReadyForQuery encodes with message type 'Z' and 4-byte length header containing TxStatus byte
	rfqIdle := sample.NewReadyForQuery(sample.TxStatusIdle)
	encoded, err := sample.EncodeReadyForQuery(rfqIdle)
	if err != nil {
		return fmt.Errorf("failed to encode ReadyForQuery: %w", err)
	}
	// Wire format: 'Z' (byte 90), int32 length 5 ([0, 0, 0, 5]), payload TxStatus ('I')
	expectedWire := []byte{'Z', 0, 0, 0, 5, 'I'}
	if !bytes.Equal(encoded, expectedWire) {
		return fmt.Errorf("unexpected wire encoding for Idle: expected %v, got %v", expectedWire, encoded)
	}

	rfqTx := sample.NewReadyForQuery(sample.TxStatusTransaction)
	encodedTx, err := rfqTx.Encode(nil)
	if err != nil {
		return fmt.Errorf("direct Encode failed: %w", err)
	}
	expectedTxWire := []byte{'Z', 0, 0, 0, 5, 'T'}
	if !bytes.Equal(encodedTx, expectedTxWire) {
		return fmt.Errorf("unexpected wire encoding for Tx: expected %v, got %v", expectedTxWire, encodedTx)
	}

	// Assertion 2: pgproto3.ReadyForQuery decodes 1-byte body slice into TxStatus
	decodedMsg, err := sample.DecodeReadyForQuery([]byte{sample.TxStatusTransaction})
	if err != nil {
		return fmt.Errorf("failed to decode valid 1-byte body: %w", err)
	}
	if decodedMsg.TxStatus != sample.TxStatusTransaction {
		return fmt.Errorf("expected decoded TxStatus %c, got %c", sample.TxStatusTransaction, decodedMsg.TxStatus)
	}
	if !sample.IsInTransaction(decodedMsg) {
		return fmt.Errorf("expected sample.IsInTransaction to return true")
	}
	if sample.IsIdle(decodedMsg) || sample.IsInFailedTransaction(decodedMsg) {
		return fmt.Errorf("expected other status checks to return false")
	}

	var directDecoded pgproto3.ReadyForQuery
	if err := directDecoded.Decode([]byte{sample.TxStatusError}); err != nil {
		return fmt.Errorf("direct Decode failed: %w", err)
	}
	if directDecoded.TxStatus != sample.TxStatusError {
		return fmt.Errorf("expected TxStatus 'E', got %c", directDecoded.TxStatus)
	}
	if !sample.IsInFailedTransaction(&directDecoded) {
		return fmt.Errorf("expected sample.IsInFailedTransaction to return true")
	}

	// Assertion 3: pgproto3.ReadyForQuery Decode returns an error when body slice length is not 1
	var invalidDecode pgproto3.ReadyForQuery
	if err := invalidDecode.Decode([]byte{}); err == nil {
		return fmt.Errorf("expected error decoding empty slice, got nil")
	}
	if err := invalidDecode.Decode([]byte{'I', 'T'}); err == nil {
		return fmt.Errorf("expected error decoding 2-byte slice, got nil")
	}

	// Assertion 4: pgproto3.ReadyForQuery implements BackendMessage and marshals to JSON with Type and TxStatus fields
	var bm pgproto3.BackendMessage = rfqIdle
	bm.Backend() // BackendMessage interface method

	jsonData, err := json.Marshal(rfqIdle)
	if err != nil {
		return fmt.Errorf("failed to marshal ReadyForQuery to JSON: %w", err)
	}
	var rawMap map[string]interface{}
	if err := json.Unmarshal(jsonData, &rawMap); err != nil {
		return fmt.Errorf("failed to parse JSON into map: %w", err)
	}
	if rawMap["Type"] != "ReadyForQuery" {
		return fmt.Errorf("expected JSON Type field 'ReadyForQuery', got %v", rawMap["Type"])
	}
	if rawMap["TxStatus"] != "I" {
		return fmt.Errorf("expected JSON TxStatus field 'I', got %v", rawMap["TxStatus"])
	}

	// Assertion 5: pgproto3.ReadyForQuery UnmarshalJSON correctly restores TxStatus from JSON payload
	jsonInput := []byte(`{"Type":"ReadyForQuery","TxStatus":"T"}`)
	var unmarshaled pgproto3.ReadyForQuery
	if err := json.Unmarshal(jsonInput, &unmarshaled); err != nil {
		return fmt.Errorf("failed to unmarshal JSON: %w", err)
	}
	if unmarshaled.TxStatus != 'T' {
		return fmt.Errorf("expected unmarshaled TxStatus 'T', got %c", unmarshaled.TxStatus)
	}

	return nil
}