store

package
v0.6.110 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package store is backplane's PostgreSQL: schema `backplane` (§12.1), migrations applied at start, typed queries generated by sqld.

Layout:

schema.sql     declarative schema: the desired state, every object
               qualified with `backplane.`
migrations/    history, applied in version order at start (embedded);
               `make db-migration name=<what>` writes the next one from
               the schema.sql diff
queries/       named queries (`-- name: X :one`); `make db` generates db/
db/            generated: models and Queries (do not edit)

Every connection runs with search_path=backplane, so sqld's bookkeeping table (sqld_migrations) lives in the schema too; the schema itself is created before migrating.

Index

Constants

View Source
const Schema = "backplane"

Schema is where everything of backplane lives in PostgreSQL.

Variables

This section is empty.

Functions

func New

func New(cfg postgres.Config, options ...Option) deps.Provider[*Store]

New is the provider of the store: a required dependency whose start connects, creates the schema and applies pending migrations (retried with backoff while PostgreSQL is down); its probe pings.

func ServiceOf

func ServiceOf(name string) string

ServiceOf is the service of a qualified name "<service>.<Name>".

Types

type AuditDetail

type AuditDetail struct {
	Revision   int64    `json:"revision,omitempty"`
	RollbackOf int64    `json:"rollback_of,omitempty"`
	Keys       []string `json:"keys,omitempty"`
	Paused     *bool    `json:"paused,omitempty"`
	Code       string   `json:"code,omitempty"`
	WorkflowID string   `json:"workflow_id,omitempty"`
	RunID      string   `json:"run_id,omitempty"`
	Affected   int64    `json:"affected,omitempty"`
	Signal     string   `json:"signal,omitempty"`
	Reason     string   `json:"reason,omitempty"`
	Note       string   `json:"note,omitempty"`
	// State an error group was set to.
	State string `json:"state,omitempty"`
}

AuditDetail permits control metadata, never arbitrary request bodies, secrets, configuration values, workflow arguments, revision comments or backend error messages. Signal, Reason and Note are the operator's words on a run or schedule command (a signal's name, never its argument), bounded by the caller.

type AuditDraft

type AuditDraft struct {
	Actor       string
	Action      string
	Subject     string
	Outcome     string
	OperationID uuid.UUID
	Detail      AuditDetail
	// Service the entry is about; empty for installation-wide entries.
	Service string
}

AuditDraft is one semantic action or one phase of an external command. Actor uses the established console:<session UUID> identity, or a named system actor.

type Option

type Option func(*provider)

Option configures persistence behavior at construction time.

func AuditExport

func AuditExport(enabled bool) Option

AuditExport controls whether new history entries enqueue an export. Existing pending exports remain durable and resume when export is enabled again.

type Store

type Store struct {
	// Pool for what the generated queries do not cover (LISTEN, COPY).
	Pool *pgxpool.Pool
	// Trm owns transaction boundaries (pgtx); InTx is the common case.
	Trm tx.Trm
	// DB routes to the context's transaction, else the pool.
	DB tx.DB
	// Q are the generated queries over DB.
	Q *db.Queries
	// Installation identifies the installation this database belongs to.
	Installation uuid.UUID
	// contains filtered or unexported fields
}

Store is the pool with its transaction manager and the generated queries.

Queries run on DB, which is the transaction in the context when there is one and the pool otherwise, so a repository is the same code inside and outside of InTx:

err := st.InTx(ctx, func(ctx context.Context) error {
    if err := st.Q.CreateRevision(ctx, ...); err != nil { return err }
    return st.Q.SetCurrent(ctx, ...)
})

func (*Store) AppendAudit

func (s *Store) AppendAudit(ctx context.Context, draft AuditDraft) (db.InsertAuditEntryRow, error)

AppendAudit joins the caller's control transaction or opens its own. The clock's row lock survives until commit, preventing a later visible sequence from overtaking this entry. Outbox work is committed with the entry.

func (*Store) AuditControl

func (s *Store) AuditControl(ctx context.Context, actor, action, subject, service string, detail AuditDetail) error

AuditControl is the transaction participant for a completed database mutation. service is the service the change is about; empty for installation-wide ones.

func (*Store) InAuditedTx added in v0.6.44

func (s *Store) InAuditedTx(ctx context.Context, fn func(ctx context.Context) error) error

InAuditedTx is InTx for a transaction that appends audit or moves the audit clock. Its first statement locks the clock before the serializable snapshot is taken, so the transaction queues behind concurrent entries instead of failing on the clock row with 40001 whenever one commits first. Joined to an outer transaction the lock comes too late to help; open it outermost.

func (*Store) InTx

func (s *Store) InTx(ctx context.Context, fn func(ctx context.Context) error) error

InTx runs fn in one serializable transaction, retried from scratch on serialization failures and deadlocks: fn must be safe to run again. Queries through Q and DB inside fn join it; a nested InTx joins it too.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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