postgres

package
v0.23.0 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package postgres provides the PostgreSQL-backed implementation of the workflow.Repository port, built on native pgx.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Repository

type Repository struct{}

Repository implements workflow.Repository using pgx. It is stateless: every method receives the pgxtx.DBTX to run against, so the caller decides whether to use a plain pool connection or an existing transaction.

func NewRepository

func NewRepository() *Repository

NewRepository creates a stateless PostgreSQL-backed workflow repository.

func (*Repository) AdvanceLastSeq added in v0.18.0

func (r *Repository) AdvanceLastSeq(ctx context.Context, db pgxtx.DBTX, id uuid.UUID) (*workflow.Case, error)

AdvanceLastSeq takes the next Seq of case id without changing anything else: it increments workflow_case.last_seq in one statement, which locks the row until the caller's transaction ends, and returns the case as updated (LastSeq is the Seq just taken). Revision is not advanced. A missing case fails with workflow.ErrCaseNotFound.

func (*Repository) AppendEvent

func (r *Repository) AppendEvent(ctx context.Context, db pgxtx.DBTX, e *workflow.Event) error

AppendEvent inserts e with the Seq the caller assigned (the engine takes it from Case.LastSeq). A Seq below 1 is rejected. Seq is not recomputed here: a Seq that is already taken fails on UNIQUE (case_id, seq) instead of being silently moved, and is returned as workflow.ErrConflict (wrapping the Postgres error): a concurrent RecordFailure took it, or a writer that does not advance workflow_case.last_seq (a binary from before migration 004) did. An empty e.Detail is stored as `{}`, and a SchemaVersion below 1 (a caller that does not set it) as 1, the version of an event without detail. actor_id stores e.Actor.ID, or the deprecated e.ActorID when Actor.ID is empty; an empty e.Actor.Kind is stored as workflow.ActorUnspecified. e.PrevDigest and e.Digest are not written: migration 007's trigger computes them from the stored row (with migration 010's v2 digest), and AppendEvent sets them on e from the insert. e.TokenID and e.ScopeID are stored as given, uuid.Nil as NULL. A second "joined" event for one scope fails on migration 008's uq_workflow_event_joined_once and is returned as workflow.ErrConflict too.

func (*Repository) Create

func (r *Repository) Create(ctx context.Context, db pgxtx.DBTX, c *workflow.Case) error

Create inserts a new case at revision 0 (whatever c.Revision held), with c.LastSeq as given, and sets c.Revision to 0. A unique-violation on (tenant, domain, external_id) is mapped to workflow.ErrCaseExists.

func (*Repository) CreateScope added in v0.19.0

func (r *Repository) CreateScope(ctx context.Context, db pgxtx.DBTX, s *workflow.Scope) error

CreateScope inserts s.

func (*Repository) CreateToken added in v0.19.0

func (r *Repository) CreateToken(ctx context.Context, db pgxtx.DBTX, t *workflow.Token) error

CreateToken inserts t.

func (*Repository) GetByExternalID

func (r *Repository) GetByExternalID(ctx context.Context, db pgxtx.DBTX, tenant, domain, externalID string) (*workflow.Case, error)

GetByExternalID retrieves a single case by its (tenant, domain, external_id) triple. A single-tenant consumer passes an empty tenant.

func (*Repository) GetByID

func (r *Repository) GetByID(ctx context.Context, db pgxtx.DBTX, id uuid.UUID) (*workflow.Case, error)

GetByID retrieves a single case by its primary key.

func (*Repository) ListEventDigests added in v0.18.0

func (r *Repository) ListEventDigests(ctx context.Context, db pgxtx.DBTX, caseID uuid.UUID) ([]workflow.EventDigest, error)

ListEventDigests returns caseID's hash chain links in seq order: each row's stored prev_digest and digest, and the digest vogel_workflow_event_digest (v2 since migration 010) computes again from the row as it is now and its stored prev_digest (nil for an unchained row).

func (*Repository) ListEvents

func (r *Repository) ListEvents(ctx context.Context, db pgxtx.DBTX, caseID uuid.UUID) ([]workflow.Event, error)

ListEvents returns every event for caseID, ordered by seq ascending, as stored: SchemaVersion is the row's schema_version (1 for rows written before migration 004, whose Actor.Kind reads as workflow.ActorUnspecified from the column default). Actor.ID and ActorID both hold actor_id. TokenID and ScopeID read as the case id for rows stored before migration 008. Upcasting older versions and rejecting newer ones is the engine's job (see workflow.Engine.History).

func (*Repository) ListOverdue added in v0.20.0

func (r *Repository) ListOverdue(ctx context.Context, db pgxtx.DBTX, f workflow.OverdueFilter) ([]workflow.WorkItem, error)

ListOverdue returns one workflow.WorkItem per active token of an open case whose deadline_at is before f.Before and not recorded as expired (expired_deadline_at differs from deadline_at, migration 009), oldest deadline first, then token id, after f.After when it is set, at most f.Page() rows. An empty f.Tenant matches every tenant. It reads the tokens through idx_workflow_token_deadline (migration 008).

func (*Repository) ListParticipated added in v0.18.0

func (r *Repository) ListParticipated(ctx context.Context, db pgxtx.DBTX, f workflow.ParticipationFilter) ([]workflow.Case, error)

ListParticipated returns the distinct cases in which f.ActorID is the actor of any event, ordered by that actor's newest event in each case (newest first, case id as the tie-break), restricted to f.Tenant when set and paged by f.Page. It reads the actor's events through idx_workflow_event_actor (migration 006), filtering the tenant on the events themselves (each event copies its case's tenant) before grouping. The cost grows with how many events the actor wrote in the tenant, not with the page size.

func (*Repository) ListScopes added in v0.19.0

func (r *Repository) ListScopes(ctx context.Context, db pgxtx.DBTX, caseID uuid.UUID) ([]workflow.Scope, error)

ListScopes returns every scope of caseID, in the order they opened.

func (*Repository) ListTokens added in v0.19.0

func (r *Repository) ListTokens(ctx context.Context, db pgxtx.DBTX, caseID uuid.UUID) ([]workflow.Token, error)

ListTokens returns every token of caseID, ordered by entered_seq, then id.

func (*Repository) ListWorkItems added in v0.19.0

func (r *Repository) ListWorkItems(ctx context.Context, db pgxtx.DBTX, f workflow.InboxFilter) ([]workflow.WorkItem, error)

ListWorkItems returns one workflow.WorkItem per active token of an open case matching f, oldest case first (opened_at, as before tokens existed, then case id), then the case's tokens by entered_seq and id, paged by f.Page. An empty f.Tenant matches every tenant. f.States restricts the token's node, f.Eligibility its stored (position, unit) pair, and f.AssignedTo, f.Unassigned and f.Overdue its assignment and deadline. Turning a person's positions into f.Eligibility is the caller's job (see workflow.Engine.EligibilityForToken), not this query's.

func (*Repository) Update

func (r *Repository) Update(ctx context.Context, db pgxtx.DBTX, c *workflow.Case, expectedLastSeq int64) error

Update persists every mutable field of c, LastSeq included, as a compare-and-swap on c.Revision and on the LastSeq the case was read with (expectedLastSeq): the row is written only while its stored revision still equals c.Revision and its stored last_seq equals expectedLastSeq, and the write advances revision by one. The last_seq check catches a workflow.Engine.RecordFailure that took a Seq after the read without advancing revision. On success c.Revision is advanced to match, so a caller holding c can keep using it. When no row matches, a follow-up existence check tells the two failures apart: workflow.ErrCaseNotFound when the case does not exist, workflow.ErrConflict when a concurrent writer committed first (nothing is written either way).

Under READ COMMITTED (PostgreSQL's default) a concurrent UPDATE of the same row blocks until the first writer commits, then re-evaluates the revision predicate and matches zero rows, yielding ErrConflict. Under REPEATABLE READ or SERIALIZABLE, PostgreSQL itself aborts the second writer with a serialization failure (SQLSTATE 40001) instead; that error is returned wrapped as-is and is equally safe to retry.

Rollout: the check only works when EVERY writer of workflow_case bumps revision. A binary built against a vogel release that predates migration 003 updates the row without touching revision, so while old and new binaries run side by side (a rolling deploy) a new writer can read revision n, have an old writer overwrite the row (still at n), and then commit its own write at n -- the old writer's change is lost and no ErrConflict is raised. Old writers never detect conflicts at all. Apply migration 003 first, then replace ALL old binaries (or stop them from writing) before relying on ErrConflict; until then concurrent updates can still be lost silently, exactly as before this check existed.

func (*Repository) UpdateScope added in v0.19.0

func (r *Repository) UpdateScope(ctx context.Context, db pgxtx.DBTX, s *workflow.Scope) error

UpdateScope writes s's status and closed seq, the only fields that change after a scope opens. A missing scope fails with workflow.ErrConflict.

func (*Repository) UpdateToken added in v0.19.0

func (r *Repository) UpdateToken(ctx context.Context, db pgxtx.DBTX, t *workflow.Token) error

UpdateToken writes every mutable field of t. A missing token fails with workflow.ErrConflict.

Jump to

Keyboard shortcuts

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