history

Documentation

Index

• type HistoryStore
• type Option
  • func WithCustomFields(fields map[string]string) Option
  • func WithTable(name string) Option
• type QueryOptions
• type SQLHistory
  • func NewPostgresHistory(db *sql.DB, opts ...Option) *SQLHistory
  • func NewSQLiteHistory(db *sql.DB, opts ...Option) *SQLHistory
  • func (h *SQLHistory) GenerateSchema() string
  • func (h *SQLHistory) Initialize(ctx context.Context) error
  • func (h *SQLHistory) ListHistory(ctx context.Context, workflowID string, opts QueryOptions) (records []TransitionRecord, err error)
  • func (h *SQLHistory) SaveTransition(ctx context.Context, record *TransitionRecord) error
  • func (h *SQLHistory) SaveTransitionTx(ctx context.Context, tx *sql.Tx, record *TransitionRecord) error
• type SQLiteHistory
• type TransitionRecord

Types

type HistoryStore

type HistoryStore interface {
	SaveTransition(ctx context.Context, record *TransitionRecord) error
	ListHistory(ctx context.Context, workflowID string, opts QueryOptions) ([]TransitionRecord, error)
	GenerateSchema() string
	Initialize(ctx context.Context) error
}

HistoryStore is the interface for saving and querying transition history.

SaveTransition, ListHistory and Initialize take a context.Context so callers can apply cancellation and deadlines; implementations honor it via the database/sql *Context methods.

type Option

type Option func(*SQLHistory)

Option configures a SQLHistory.

func WithCustomFields

func WithCustomFields(fields map[string]string) Option

WithCustomFields declares additional columns to persist alongside each record. The map key is the field name (matched against TransitionRecord.CustomFields); the value is the full SQL column definition (e.g. "ip_address TEXT").

func WithTable

func WithTable(name string) Option

WithTable sets the name of the table used to store transition history. Default: "transition_history".

type QueryOptions

type QueryOptions struct {
	Limit      int
	Offset     int
	FromDate   *time.Time
	ToDate     *time.Time
	Actor      string
	Transition string
}

QueryOptions allows for pagination and filtering.

type SQLHistory

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

SQLHistory is a HistoryStore backed by a SQL database. Construct it with NewSQLiteHistory or NewPostgresHistory; the two differ only in dialect.

func NewPostgresHistory

func NewPostgresHistory(db *sql.DB, opts ...Option) *SQLHistory

NewPostgresHistory creates a history store speaking PostgreSQL's dialect ($N placeholders, BIGSERIAL primary key, TIMESTAMPTZ timestamps). Use it with any database/sql driver that speaks PostgreSQL (pgx stdlib recommended), and share the *sql.DB with a storage.PostgresStorage to commit state and history atomically (SaveTransitionTx + storage.RunInTx, or Manager.Execute with workflow.WithTxSideEffect).

func NewSQLiteHistory

func NewSQLiteHistory(db *sql.DB, opts ...Option) *SQLHistory

NewSQLiteHistory creates a history store speaking SQLite's dialect.

func (*SQLHistory) GenerateSchema

func (h *SQLHistory) GenerateSchema() string

GenerateSchema returns the CREATE TABLE statement for the history table, including any configured custom-field columns.

func (*SQLHistory) Initialize

func (h *SQLHistory) Initialize(ctx context.Context) error

Initialize creates the history table if it does not already exist.

func (*SQLHistory) ListHistory

func (h *SQLHistory) ListHistory(ctx context.Context, workflowID string, opts QueryOptions) (records []TransitionRecord, err error)

ListHistory returns the transition records for a workflow, most recent first, honoring the filtering and pagination options in opts.

func (*SQLHistory) SaveTransition

func (h *SQLHistory) SaveTransition(ctx context.Context, record *TransitionRecord) error

SaveTransition appends a single transition record to the history table.

func (*SQLHistory) SaveTransitionTx

func (h *SQLHistory) SaveTransitionTx(ctx context.Context, tx *sql.Tx, record *TransitionRecord) error

SaveTransitionTx behaves like SaveTransition but writes through the provided transaction, so a history record can be committed atomically with a state change. The same *sql.DB must back the state store for the writes to share the transaction. See storage.RunInTx and workflow.WithTxSideEffect.

type SQLiteHistory

type SQLiteHistory = SQLHistory

SQLiteHistory is the historical name for the SQLite-flavored SQLHistory.

type TransitionRecord

type TransitionRecord struct {
	WorkflowID   string
	FromState    string
	ToState      string
	Transition   string
	Notes        string
	Actor        string
	CreatedAt    time.Time
	CustomFields map[string]any // For custom columns, if any
}

TransitionRecord is the base struct for a transition event.