postgres

Documentation

Overview

Package postgres provides transactional completion adapters for dureq handlers whose business state lives in PostgreSQL. By committing a business write and the dureq completion marker in the same SQL transaction, handlers achieve exactly-once outcome semantics — even under retries and crashes.

Usage:

func handleOrder(ctx context.Context, order OrderPayload) error {
    tx, _ := db.BeginTx(ctx, nil)
    defer tx.Rollback()

    // Business write.
    tx.ExecContext(ctx, "INSERT INTO orders (...) VALUES (...)", ...)

    // Mark this run as completed — same TX.
    if err := postgres.CompleteTx(ctx, tx); err != nil {
        return err // already completed on a previous attempt
    }
    return tx.Commit()
}

Index

• Variables
• func CheckpointTx(ctx context.Context, tx *sql.Tx, step string, data []byte) error
• func CompleteTx(ctx context.Context, tx *sql.Tx) error
• func EnsureTable(ctx context.Context, db *sql.DB) error
• func FailTx(ctx context.Context, tx *sql.Tx, err error) error
• func IsCheckpointed(ctx context.Context, db *sql.DB, step string) (bool, []byte, error)
• func IsCompleted(ctx context.Context, db *sql.DB) (bool, error)

Variables

var ErrAlreadyCompleted = errors.New("dureq: run already completed")

ErrAlreadyCompleted is returned when a run has already been marked as completed. The handler should treat this as a successful no-op (the previous attempt committed).

Functions

func CheckpointTx

func CheckpointTx(ctx context.Context, tx *sql.Tx, step string, data []byte) error

CheckpointTx records an intermediate checkpoint within a long-running handler. The step name distinguishes different checkpoints within the same run. On retry, the handler can call IsCheckpointed to skip already-completed steps.

func CompleteTx

func CompleteTx(ctx context.Context, tx *sql.Tx) error

CompleteTx inserts a completion marker for the current run inside the given transaction. If the run was already completed (duplicate), ErrAlreadyCompleted is returned and the caller should skip further work (or commit as no-op).

The run ID and job ID are extracted from the context (set by the dureq worker).

func EnsureTable

func EnsureTable(ctx context.Context, db *sql.DB) error

EnsureTable creates the dureq_completions table if it does not exist. Call this once during application startup or in a migration.

func FailTx

func FailTx(ctx context.Context, tx *sql.Tx, err error) error

FailTx records a failure marker for the current run. This is useful when the handler wants to record that it attempted but failed, preventing re-execution of side effects on retry.

func IsCheckpointed

func IsCheckpointed(ctx context.Context, db *sql.DB, step string) (bool, []byte, error)

IsCheckpointed checks whether a specific checkpoint step has been recorded.

func IsCompleted

func IsCompleted(ctx context.Context, db *sql.DB) (bool, error)

IsCompleted checks whether the current run has already been completed. Use this at the start of a handler to skip re-execution entirely.