wire

Documentation

Overview

Package wire holds duckgres wire-level types and helpers shared between the PG protocol layer and the control plane / worker RPC paths. The package has no dependency on github.com/duckdb/duckdb-go so callers (notably the control plane) can use it without linking libduckdb.

Index

• Constants
• func GenerateSecretKey() int32
• func ReadMessage(r io.Reader) (byte, []byte, error)
• func ReadStartupMessage(r io.Reader) (map[string]string, error)
• func RedactSecrets(s string) string
• func WriteAuthCleartextPassword(w io.Writer) error
• func WriteAuthOK(w io.Writer) error
• func WriteBackendKeyData(w io.Writer, pid, secretKey int32) error
• func WriteBindComplete(w io.Writer) error
• func WriteCloseComplete(w io.Writer) error
• func WriteCommandComplete(w io.Writer, tag string) error
• func WriteCopyData(w io.Writer, data []byte) error
• func WriteCopyDone(w io.Writer) error
• func WriteCopyInResponse(w io.Writer, numColumns int16, textFormat bool) error
• func WriteCopyOutResponse(w io.Writer, numColumns int16, textFormat bool) error
• func WriteEmptyQueryResponse(w io.Writer) error
• func WriteErrorResponse(w io.Writer, severity, code, message string) error
• func WriteMessage(w io.Writer, msgType byte, data []byte) error
• func WriteNoData(w io.Writer) error
• func WriteNoticeResponse(w io.Writer, severity, code, message string) error
• func WriteParameterStatus(w io.Writer, name, value string) error
• func WriteParseComplete(w io.Writer) error
• func WriteReadyForQuery(w io.Writer, txStatus byte) error
• type BackendKey
• type WorkerActivationPayload
• type WorkerControlMetadata
• type WorkerCreateSessionPayload
• type WorkerDestroySessionPayload
• type WorkerHealthCheckPayload
• type WorkerReleaseQueryHandlePayload
• type WorkerWaitSessionIdlePayload

Constants

const (
	// Frontend (client) messages
	MsgQuery     = 'Q'
	MsgTerminate = 'X'
	MsgPassword  = 'p'
	MsgParse     = 'P'
	MsgBind      = 'B'
	MsgDescribe  = 'D'
	MsgExecute   = 'E'
	MsgSync      = 'S'
	MsgClose     = 'C'
	MsgFlush     = 'H'

	// Backend (server) messages
	MsgAuth            = 'R'
	MsgParamStatus     = 'S'
	MsgBackendKeyData  = 'K'
	MsgReadyForQuery   = 'Z'
	MsgRowDescription  = 'T'
	MsgDataRow         = 'D'
	MsgCommandComplete = 'C'
	MsgErrorResponse   = 'E'
	MsgNoticeResponse  = 'N'
	MsgEmptyQuery      = 'I'
	MsgParseComplete   = '1'
	MsgBindComplete    = '2'
	MsgCloseComplete   = '3'
	MsgNoData          = 'n'

	// COPY messages (both directions)
	MsgCopyData        = 'd' // Contains COPY data
	MsgCopyDone        = 'c' // COPY completed
	MsgCopyFail        = 'f' // COPY failed (frontend only)
	MsgCopyInResponse  = 'G' // Server ready to receive COPY data
	MsgCopyOutResponse = 'H' // Server about to send COPY data
)

PostgreSQL message types

Functions

func GenerateSecretKey

func GenerateSecretKey() int32

GenerateSecretKey returns a cryptographically random secret key suitable for embedding in a BackendKey. Falls back to a time-based key if crypto/rand fails.

func ReadMessage

func ReadMessage(r io.Reader) (byte, []byte, error)

readMessage reads a single message from the client

func ReadStartupMessage

func ReadStartupMessage(r io.Reader) (map[string]string, error)

readStartupMessage reads the initial startup message from the client

func RedactSecrets

func RedactSecrets(s string) string

RedactSecrets replaces password=<value> (and password: <value>) patterns with password=[REDACTED] for safe logging and error reporting. It handles both quoted and unquoted values. It does not currently redact other secret types (tokens, keys).

func WriteAuthCleartextPassword

func WriteAuthCleartextPassword(w io.Writer) error

writeAuthCleartextPassword requests cleartext password

func WriteAuthOK

func WriteAuthOK(w io.Writer) error

writeAuthOK sends authentication success

func WriteBackendKeyData

func WriteBackendKeyData(w io.Writer, pid, secretKey int32) error

writeBackendKeyData sends the backend key data (for cancel requests)

func WriteBindComplete

func WriteBindComplete(w io.Writer) error

writeBindComplete sends bind complete

func WriteCloseComplete

func WriteCloseComplete(w io.Writer) error

writeCloseComplete sends close complete

func WriteCommandComplete

func WriteCommandComplete(w io.Writer, tag string) error

writeCommandComplete sends a command completion message

func WriteCopyData

func WriteCopyData(w io.Writer, data []byte) error

writeCopyData sends a row of COPY data

func WriteCopyDone

func WriteCopyDone(w io.Writer) error

writeCopyDone signals the end of COPY data

func WriteCopyInResponse

func WriteCopyInResponse(w io.Writer, numColumns int16, textFormat bool) error

writeCopyInResponse tells client to send COPY data

func WriteCopyOutResponse

func WriteCopyOutResponse(w io.Writer, numColumns int16, textFormat bool) error

writeCopyOutResponse tells client we're about to send COPY data Format: overall format (0=text, 1=binary), num columns, format per column

func WriteEmptyQueryResponse

func WriteEmptyQueryResponse(w io.Writer) error

writeEmptyQueryResponse sends an empty query response

func WriteErrorResponse

func WriteErrorResponse(w io.Writer, severity, code, message string) error

writeErrorResponse sends an error to the client

func WriteMessage

func WriteMessage(w io.Writer, msgType byte, data []byte) error

writeMessage writes a message to the client

func WriteNoData

func WriteNoData(w io.Writer) error

writeNoData sends no data response

func WriteNoticeResponse

func WriteNoticeResponse(w io.Writer, severity, code, message string) error

writeNoticeResponse sends a notice/warning to the client Unlike errors, notices are informational and don't terminate the command

func WriteParameterStatus

func WriteParameterStatus(w io.Writer, name, value string) error

writeParameterStatus sends a parameter status message

func WriteParseComplete

func WriteParseComplete(w io.Writer) error

writeParseComplete sends parse complete

func WriteReadyForQuery

func WriteReadyForQuery(w io.Writer, txStatus byte) error

writeReadyForQuery indicates the server is ready for a new query

Types

type BackendKey

type BackendKey struct {
	Pid       int32
	SecretKey int32
}

BackendKey identifies a backend connection for PostgreSQL cancel requests. Pid is the backend process id surfaced to the client; SecretKey is the matching secret a cancel request must present.

type WorkerActivationPayload

type WorkerActivationPayload struct {
	WorkerControlMetadata
	OrgID    string          `json:"org_id"`
	DuckLake ducklake.Config `json:"ducklake"`
	// Iceberg is the per-tenant Iceberg catalog (AWS S3 Tables) config.
	// Empty when the tenant has not opted in or hasn't been provisioned yet.
	Iceberg iceberg.Config `json:"iceberg"`
}

WorkerActivationPayload is the tenant runtime material delivered to a shared warm worker over the control plane RPC path.

type WorkerControlMetadata

type WorkerControlMetadata struct {
	WorkerID     int    `json:"worker_id"`
	OwnerEpoch   int64  `json:"owner_epoch"`
	CPInstanceID string `json:"cp_instance_id,omitempty"`
}

WorkerControlMetadata identifies the logical worker owner on a control plane → worker request.

type WorkerCreateSessionPayload

type WorkerCreateSessionPayload struct {
	WorkerControlMetadata
	Username    string `json:"username"`
	MemoryLimit string `json:"memory_limit"`
	Threads     int    `json:"threads"`
	// SecretStatements are the user's persistent CREATE SECRET statements
	// (decrypted by the control plane from the config store) to replay on the
	// worker before the session is handed to the client. Worker pods are
	// ephemeral, so this is the only way a user secret survives across
	// sessions. Carries credential material: never log this payload.
	SecretStatements []string `json:"secret_statements,omitempty"`
}

WorkerCreateSessionPayload is the control plane request body for creating a worker-local session.

type WorkerDestroySessionPayload

type WorkerDestroySessionPayload struct {
	WorkerControlMetadata
	SessionToken string `json:"session_token"`
}

WorkerDestroySessionPayload is the control plane request body for destroying a worker-local session.

type WorkerHealthCheckPayload

type WorkerHealthCheckPayload struct {
	WorkerControlMetadata
}

WorkerHealthCheckPayload is the control plane request body for health-checking a worker.

type WorkerReleaseQueryHandlePayload

type WorkerReleaseQueryHandlePayload struct {
	WorkerControlMetadata
	Ticket []byte `json:"ticket"`
}

WorkerReleaseQueryHandlePayload asks a worker to release a statement query handle that was created by GetFlightInfo but abandoned before DoGet could consume it.

type WorkerWaitSessionIdlePayload

type WorkerWaitSessionIdlePayload struct {
	WorkerControlMetadata
}

WorkerWaitSessionIdlePayload asks a worker to acknowledge that the session's current Flight SQL operation has released its worker-side lifecycle state.