Help us shape the future of Go! Take the 2026 Go Developer Survey

postgres

package
v2.0.2 Latest Latest
Warning

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

Go to latest
Published: Oct 12, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package postgres provides PostgreSQL persistence for control-plane state.

Index

Constants

View Source
const (
	// MaxCommandPageSize bounds one command-history database response.
	MaxCommandPageSize uint32 = 1_000
	// MaxCommandCursorBytes bounds opaque command-history pagination state.
	MaxCommandCursorBytes = 1_024
	// MaxCommandRetentionBatch bounds one terminal-command cleanup transaction.
	MaxCommandRetentionBatch uint32 = 1_000
)
View Source
const (
	// MaxAuditBatch bounds verification and retention database work.
	MaxAuditBatch uint32 = 1_000
)

Variables

View Source
var (
	// ErrInvalidAuditRequest reports an unscoped or unbounded audit operation.
	ErrInvalidAuditRequest = errors.New("postgres: invalid audit request")
	// ErrAuditAnchorNotFound reports a tenant without initialized audit state.
	ErrAuditAnchorNotFound = errors.New("postgres: audit anchor not found")
	// ErrInvalidAuditState reports malformed persisted audit metadata.
	ErrInvalidAuditState = errors.New("postgres: invalid audit state")
)
View Source
var (
	// ErrInvalidCommandRequest reports an unbounded command lookup scope.
	ErrInvalidCommandRequest = errors.New("postgres: invalid command request")
	// ErrInvalidCommandState reports a malformed persisted command result.
	ErrInvalidCommandState = errors.New("postgres: invalid command state")
	// ErrInvalidCommandRetentionRequest reports an unsafe cleanup scope.
	ErrInvalidCommandRetentionRequest = errors.New("postgres: invalid command retention request")
	// ErrInvalidCommandRetentionState reports an impossible deletion count.
	ErrInvalidCommandRetentionState = errors.New("postgres: invalid command retention state")
)
View Source
var (
	// ErrNilQueryer reports a missing PostgreSQL read boundary.
	ErrNilQueryer = errors.New("postgres: queryer is nil")
	// ErrInvalidDesiredLookup reports an unscoped or unsupported target.
	ErrInvalidDesiredLookup = errors.New("postgres: invalid desired-state lookup")
	// ErrDesiredStateNotFound reports a target without durable desired state.
	ErrDesiredStateNotFound = errors.New("postgres: desired state not found")
)
View Source
var (
	// ErrNilBeginner reports a missing PostgreSQL transaction source.
	ErrNilBeginner = errors.New("postgres: transaction beginner is nil")
	// ErrIdempotencyConflict reports reuse of a key for another command.
	ErrIdempotencyConflict = errors.New("postgres: idempotency key conflicts with stored command")
	// ErrCompletionConflict reports an attempt to replace a terminal result.
	ErrCompletionConflict = errors.New("postgres: terminal command result conflicts with stored result")
	// ErrCommandNotFound reports completion of an unknown tenant-scoped key.
	ErrCommandNotFound = errors.New("postgres: command not found")
	// ErrAuditSequenceExhausted reports an audit chain beyond bigint capacity.
	ErrAuditSequenceExhausted = errors.New("postgres: audit sequence exhausted")
	// ErrAuditHashInvalid reports malformed persisted audit-chain state.
	ErrAuditHashInvalid = errors.New("postgres: invalid audit hash")
	// ErrDesiredStateConflict reports a concurrent desired-state replacement.
	ErrDesiredStateConflict = errors.New("postgres: desired state update conflict")
)
View Source
var ErrInvalidMigrationDatabase = errors.New("postgres: migration database is nil")

ErrInvalidMigrationDatabase reports a missing migration connection pool.

View Source
var ErrInvalidRuntimePool = errors.New("postgres: invalid runtime pool")

ErrInvalidRuntimePool reports a missing or uninitialized PostgreSQL pool.

View Source
var ErrResultNotTerminal = errors.New("postgres: command result is not terminal")

ErrResultNotTerminal rejects accepted results at the completion boundary.

Functions

func MigrationSource

func MigrationSource() (migrations.Source, error)

MigrationSource returns the immutable embedded control-plane schema history.

func NewMigrationRunner

func NewMigrationRunner(database *sql.DB) (*migrations.Runner, error)

NewMigrationRunner builds the bounded migrations runner for the embedded control-plane schema. The caller retains ownership of database.

Types

type AuditPage

type AuditPage struct {
	Entries      []history.Entry
	NextSequence uint64
}

AuditPage is one verified bounded tenant audit-history page.

type AuditStore

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

AuditStore verifies and retains tenant audit history transactionally.

func NewAuditStore

func NewAuditStore(beginner gopostgres.Beginner) (*AuditStore, error)

NewAuditStore creates a transaction-backed audit operations repository.

func (*AuditStore) AuditSensitiveAccess

func (s *AuditStore) AuditSensitiveAccess(
	ctx context.Context,
	access controlplane.SensitiveAccess,
) error

AuditSensitiveAccess durably records one authorized privileged record read.

func (*AuditStore) ListTenant

func (s *AuditStore) ListTenant(
	ctx context.Context,
	tenant string,
	after uint64,
	limit uint32,
) (AuditPage, error)

ListTenant returns one verified page after the supplied sequence cursor.

func (*AuditStore) RetainBefore

func (s *AuditStore) RetainBefore(
	ctx context.Context,
	tenant string,
	cutoff time.Time,
	batchSize uint32,
) (RetentionResult, error)

RetainBefore deletes one contiguous old prefix and advances its anchor.

func (*AuditStore) VerifyTenant

func (s *AuditStore) VerifyTenant(
	ctx context.Context,
	tenant string,
	pageSize uint32,
) (VerificationReport, error)

VerifyTenant streams and verifies one tenant chain in a repeatable snapshot.

type CommandPage

type CommandPage struct {
	Records    []CommandRecord
	NextCursor string
}

CommandPage is one bounded newest-first tenant command-history page.

type CommandRecord

type CommandRecord struct {
	Command controlplane.Command
	Result  controlplane.CommandResult
}

CommandRecord joins one immutable command envelope to its durable outcome.

type CommandRetentionResult

type CommandRetentionResult struct {
	Deleted uint32
}

CommandRetentionResult reports one bounded terminal-command cleanup batch.

type CommandStore

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

CommandStore reads tenant-scoped durable command outcomes.

func NewCommandStore

func NewCommandStore(beginner gopostgres.Beginner) (*CommandStore, error)

NewCommandStore creates a transaction-backed command result reader.

func (*CommandStore) Get

func (s *CommandStore) Get(
	ctx context.Context,
	tenant string,
	key string,
) (controlplane.CommandResult, error)

Get returns one durable result by tenant and idempotency key.

func (*CommandStore) ListTenant

func (s *CommandStore) ListTenant(
	ctx context.Context,
	tenant string,
	cursor string,
	limit uint32,
) (CommandPage, error)

ListTenant returns one newest-first tenant command-history page.

func (*CommandStore) RetainCommandsBefore

func (s *CommandStore) RetainCommandsBefore(
	ctx context.Context,
	tenant string,
	cutoff time.Time,
	batchSize uint32,
) (CommandRetentionResult, error)

RetainCommandsBefore deletes old terminal commands that no retained audit event or current desired state references.

type DesiredStore

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

DesiredStore reads tenant-scoped operational state for worker convergence.

func NewDesiredStore

func NewDesiredStore(queryer rowQueryer) (*DesiredStore, error)

NewDesiredStore creates a desired-state read repository.

func (*DesiredStore) Get

func (s *DesiredStore) Get(
	ctx context.Context,
	tenant string,
	target controlplane.Target,
) (control.DesiredRecord, error)

Get returns the latest durable desired state for one target.

type Journal

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

Journal persists command outcomes and their audit records in one transaction.

func NewJournal

func NewJournal(beginner gopostgres.Beginner) (*Journal, error)

NewJournal creates a journal backed by postgres transaction semantics.

func (*Journal) Accept

Accept atomically records a command and its initial audit event.

func (*Journal) Complete

func (j *Journal) Complete(
	ctx context.Context,
	result controlplane.CommandResult,
) error

Complete atomically records a terminal command result and audit event.

func (*Journal) MarkAcknowledged

func (j *Journal) MarkAcknowledged(ctx context.Context, result controlplane.CommandResult) error

MarkAcknowledged atomically persists a successful data-plane acknowledgement before the terminal result is written.

func (*Journal) MarkDispatched

func (j *Journal) MarkDispatched(ctx context.Context, result controlplane.CommandResult) error

MarkDispatched atomically persists the pre-dispatch recovery boundary and its audit event.

type PoolReadiness

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

PoolReadiness adapts postgres bounded health checks to the API contract.

func (*PoolReadiness) Ready

func (readiness *PoolReadiness) Ready(ctx context.Context) error

Ready performs a bounded PostgreSQL ping through postgres.

type RetentionResult

type RetentionResult struct {
	Deleted         uint32
	AnchorSequence  uint64
	AnchorHash      history.Hash
	RetainedThrough time.Time
}

RetentionResult describes one bounded retained-prefix cleanup batch.

type Runtime

type Runtime struct {
	Journal   *Journal
	Audit     *AuditStore
	Commands  *CommandStore
	Desired   *DesiredStore
	Readiness *PoolReadiness
}

Runtime is the complete PostgreSQL-backed control-plane service bundle. The caller retains ownership of the underlying pool.

func NewRuntime

func NewRuntime(pool *gopostgres.Pool) (*Runtime, error)

NewRuntime wires all control-plane persistence services to one pool.

type VerificationReport

type VerificationReport struct {
	Events       uint64
	HeadSequence uint64
	HeadHash     history.Hash
}

VerificationReport identifies the verified tenant audit head.

Jump to

Keyboard shortcuts

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