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
- func New(cfg postgres.Config, options ...Option) deps.Provider[*Store]
- func ServiceOf(name string) string
- type AuditDetail
- type AuditDraft
- type Option
- type Store
- func (s *Store) AppendAudit(ctx context.Context, draft AuditDraft) (db.InsertAuditEntryRow, error)
- func (s *Store) AuditControl(ctx context.Context, actor, action, subject, service string, ...) error
- func (s *Store) InAuditedTx(ctx context.Context, fn func(ctx context.Context) error) error
- func (s *Store) InTx(ctx context.Context, fn func(ctx context.Context) error) error
Constants ¶
const Schema = "backplane"
Schema is where everything of backplane lives in PostgreSQL.
Variables ¶
This section is empty.
Functions ¶
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 ¶
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
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.