postgrestest

package
v2.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 23, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source
const DiagnosticFirstSampleTimeout = 30 * time.Second

DiagnosticFirstSampleTimeout bounds startup even when a caller supplies a context without a deadline.

Variables

This section is empty.

Functions

func DiagnosticEnabled

func DiagnosticEnabled() bool

DiagnosticEnabled intentionally checks only the exact opt-in value.

func EnsureMigrationRoles

func EnsureMigrationRoles(ctx context.Context, dsn string) error

EnsureMigrationRoles serializes the cluster-global role bootstrap used by PostgreSQL integration packages. The session lock covers the check/create sequence across databases and processes on the same test cluster.

func PGXPoolerConfig

func PGXPoolerConfig(dsn string) (*pgx.ConnConfig, error)

PGXPoolerConfig derives the administrative connection from the supplied pooler DSN. The caller's database is intentionally not used for SHOW commands; it remains the observer's row-filter prefix instead.

func Validate

func Validate(samples []Sample, interval time.Duration, prefix string) error

Types

type Activity

type Activity struct {
	PID                   int64
	Query                 string
	XactStart, QueryStart *time.Time
}

type ActivityKey

type ActivityKey struct{ Application, State, WaitEvent string }

type ActivityRecord

type ActivityRecord struct {
	Database    string     `json:"database,omitempty"`
	Application string     `json:"application,omitempty"`
	State       string     `json:"state,omitempty"`
	WaitEvent   string     `json:"wait,omitempty"`
	PID         int64      `json:"pid"`
	QuerySHA256 string     `json:"query_sha256,omitempty"`
	XactStart   *time.Time `json:"xact_start,omitempty"`
	QueryStart  *time.Time `json:"query_start,omitempty"`
}

type ActivitySnapshot

type ActivitySnapshot []ActivityRecord

func ParseActivity

func ParseActivity(rows Rows) (ActivitySnapshot, error)

type Clock

type Clock interface{ Now() time.Time }

type ClockFunc

type ClockFunc func() time.Time

func (ClockFunc) Now

func (f ClockFunc) Now() time.Time

type Config

type Config struct {
	RunPrefix, Source string
	Interval          time.Duration

	Pooler, Postgres ConnFactory
	Clock            Clock
	// contains filtered or unexported fields
}

type ConfigSnapshot

type ConfigSnapshot struct {
	Source, Identity, Version string
	ActivityRequired          bool `json:"activity_required"`
}

type ConnFactory

type ConnFactory func(context.Context) (QueryConn, error)

func PGXFactory

func PGXFactory(dsn string) ConnFactory

PGXFactory creates one persistent pgx connection. Observer caches the returned connection, so samples share a session and terminal shutdown owns its close; callers never need to expose a DSN in observer output.

func PGXPoolerFactory

func PGXPoolerFactory(dsn string) ConnFactory

PGXPoolerFactory uses pgx's simple protocol, which is required by the PgBouncer administrative database. Extended-protocol prepared statements are not supported by that database.

type Counter

type Counter struct{ Xacts, Queries, Received, Sent, Wait, QueryTime, XactTime, Assignments, ClientParse, ServerParse, ClientBind int64 }

type Diagnostic

type Diagnostic struct {
	// contains filtered or unexported fields
}

func NewDiagnostic

func NewDiagnostic(c Config) *Diagnostic

func (*Diagnostic) EmitReport

func (d *Diagnostic) EmitReport(emit any) error

EmitReport emits the one diagnostic line. The caller supplies the logger so this package never couples telemetry to testing.T or a production logger. JSON contains only bounded observer data and the sanitized run identity.

func (*Diagnostic) RecordPhase

func (d *Diagnostic) RecordPhase(p Phase)

func (*Diagnostic) SetMeasuredOverhead

func (d *Diagnostic) SetMeasuredOverhead(off, on []time.Duration)

SetMeasuredOverhead replaces the provisional gate measurements after the sampler has been started. This is used by wired tests whose ON arm must be measured while the observer is live.

func (*Diagnostic) Start

func (d *Diagnostic) Start(ctx context.Context, off, on []time.Duration) error

Start performs the overhead gate before the sampler is started. Empty or mismatched baselines are incomplete telemetry, not a pass.

func (*Diagnostic) Stop

func (d *Diagnostic) Stop() DiagnosticReport

Stop is cancellation-safe and idempotent. A started sampler is always stopped before the snapshot is returned.

func (*Diagnostic) WaitFirstSample

func (d *Diagnostic) WaitFirstSample(ctx context.Context) bool

WaitFirstSample waits until the sampler has successfully populated one complete sample. A timeout is a diagnostic gap, never a pass.

type DiagnosticReport

type DiagnosticReport struct {
	Identity    string           `json:"identity"`
	Status      DiagnosticStatus `json:"status"`
	Overhead    OverheadReport   `json:"overhead"`
	Complete    bool             `json:"complete"`
	Gaps        []string         `json:"gaps,omitempty"`
	Samples     []Sample         `json:"samples,omitempty"`
	PhaseEvents []PhaseEvent     `json:"phase_events,omitempty"`
	Truncated   bool             `json:"truncated,omitempty"`
}

type DiagnosticStatus

type DiagnosticStatus string

Diagnostic is an opt-in, fail-closed telemetry controller for C32. It is deliberately separate from the protocol runner: its verdict is never an input to the runner's PASS/FAIL decision.

const (
	DiagnosticPass         DiagnosticStatus = "PASS"
	DiagnosticBlocked      DiagnosticStatus = "BLOCKED"
	DiagnosticInconclusive DiagnosticStatus = "INCONCLUSIVE"
	DiagnosticInterval                      = 100 * time.Millisecond
)

type Observer

type Observer struct {
	// contains filtered or unexported fields
}

func NewObserver

func NewObserver(c Config) *Observer

func (*Observer) Run

func (o *Observer) Run(ctx context.Context) ([]Sample, error)

func (*Observer) Sample

func (o *Observer) Sample(ctx context.Context) (Sample, error)

type Overhead

type Overhead struct{ Off, On []time.Duration }

func (Overhead) Pass

func (o Overhead) Pass() bool

type OverheadReport

type OverheadReport struct {
	OffP50 time.Duration `json:"off_p50_ns"`
	OnP50  time.Duration `json:"on_p50_ns"`
	OffP95 time.Duration `json:"off_p95_ns"`
	OnP95  time.Duration `json:"on_p95_ns"`
	Pass   bool          `json:"pass"`
}

type PgBouncerSnapshot

type PgBouncerSnapshot struct {
	Stats     map[string]Counter
	Pools     map[string]Pool
	Servers   map[string]Server
	Truncated bool `json:"truncated,omitempty"`
}

func ParsePGBouncer

func ParsePGBouncer(stats, pools, servers Rows, prefix string) (PgBouncerSnapshot, error)

ParsePGBouncer parses SHOW STATS, SHOW POOLS, and SHOW SERVERS using column names (never positional columns), aggregating only databases in RunPrefix.

type Phase

type Phase string
const (
	PhasePath       Phase = "path"
	PhaseRepetition Phase = "repetition"
	PhaseBlock      Phase = "block"
	PhasePopulation Phase = "population"
	PhaseCold       Phase = "cold"
	PhaseWarm       Phase = "warm"
	PhaseMeasured   Phase = "measured"
)

type PhaseEvent

type PhaseEvent struct {
	Phase Phase     `json:"phase"`
	At    time.Time `json:"at"`
}

type Pool

type Pool struct{ ClientActive, ClientWaiting, ServerActive, ServerIdle, ServerUsed, ServerTested, ServerLogin, MaxWait int64 }

type QueryConn

type QueryConn interface {
	Query(context.Context, string, ...any) (Rows, error)
	Close(context.Context) error
}

type Rows

type Rows interface {
	Next() bool
	Values() ([]any, error)
	Err() error
	Close()
	FieldDescriptions() []pgconn.FieldDescription
}

Rows is the small part of pgx.Rows needed by the observer. It also makes the parser usable with in-memory rows in unit tests.

type Sample

type Sample struct {
	Offset            time.Duration
	Wall              time.Time
	Sequence          uint64
	Gap               time.Duration
	Stats             PgBouncerSnapshot
	Activity          ActivitySnapshot
	Config            ConfigSnapshot
	Truncated         bool `json:"truncated,omitempty"`
	ActivityTruncated bool `json:"activity_truncated,omitempty"`
}

type Server

type Server struct {
	Type                                                                string
	Active, Idle, Used, Tested, Login, New, ActiveCancel, BeingCanceled int64
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL