workqueuedb

type ClaimDueItemsParams ¶

type ClaimDueItemsParams struct {
	LeaseMicroseconds int64
	QueueName         string
	AttemptCeiling    int64
	ClaimLimit        int64
}

ClaimDueItemsParams are the arguments to ClaimDueItems.

type ClaimDueItemsRow ¶

type ClaimDueItemsRow struct {
	ItemKey   string
	Priority  int64
	Attempts  int64
	Reclaimed bool
}

ClaimDueItemsRow is one row of ClaimDueItems's result.

type CompleteItemsParams ¶

type CompleteItemsParams struct {
	QueueName string
	ItemKeys  []string
}

CompleteItemsParams are the arguments to CompleteItems.

type DBTX ¶

type DBTX interface {
	ExecContext(context.Context, string, ...any) (sql.Result, error)
	QueryContext(context.Context, string, ...any) (*sql.Rows, error)
	QueryRowContext(context.Context, string, ...any) *sql.Row
}

DBTX is what a generated method needs from a database handle.

It is satisfied by *sql.DB, *sql.Tx, and *sql.Conn alike, and it is taken per call rather than held on the querier so that running a query inside a transaction is a different argument rather than a different querier.

type Dialect ¶

type Dialect string

Dialect names a SQL dialect this package was generated for.

It is a type rather than a string so that naming one that was not generated is a compile error rather than an error value at startup.

const (
	// DialectPostgreSQL is postgresql.
	DialectPostgreSQL Dialect = "postgresql"
)

func Dialects() []Dialect

type EnqueueItemsParams ¶

type EnqueueItemsParams struct {
	QueueName         string
	ItemKeys          []string
	Priorities        []int64
	DelayMicroseconds []int64
}

EnqueueItemsParams are the arguments to EnqueueItems.

type Querier ¶

type Querier interface {
	// ClaimDueItems runs the :many query.
	ClaimDueItems(ctx context.Context, db DBTX, arg ClaimDueItemsParams) ([]ClaimDueItemsRow, error)
	// CompleteItems runs the :execrows query.
	//
	// The count means different things on different engines; see the note
	// on Querier.
	CompleteItems(ctx context.Context, db DBTX, arg CompleteItemsParams) (int64, error)
	// EnqueueItems runs the :exec query.
	EnqueueItems(ctx context.Context, db DBTX, arg EnqueueItemsParams) error
	// ReadQueueStats runs the :one query.
	ReadQueueStats(ctx context.Context, db DBTX, arg ReadQueueStatsParams) (ReadQueueStatsRow, error)
	// ReapCompletedItems runs the :execrows query.
	//
	// The count means different things on different engines; see the note
	// on Querier.
	ReapCompletedItems(ctx context.Context, db DBTX, arg ReapCompletedItemsParams) (int64, error)
	// ReleaseItems runs the :execrows query.
	//
	// The count means different things on different engines; see the note
	// on Querier.
	ReleaseItems(ctx context.Context, db DBTX, arg ReleaseItemsParams) (int64, error)
	// RemoveItems runs the :execrows query.
	//
	// The count means different things on different engines; see the note
	// on Querier.
	RemoveItems(ctx context.Context, db DBTX, arg RemoveItemsParams) (int64, error)
}

Querier is every query in this package, with one signature per query regardless of which dialect answers it.

That is the point of this package: the params type, the row type, and the method signature are the same on every dialect, so nothing above this line knows or cares which database is underneath.

A note on the :execrows count ¶

MySQL reports rows *changed*: an UPDATE that sets a column to the value it already held affects zero rows there. Postgres and SQLite report rows *matched*, and count that same UPDATE as one.

So a statement that gates on the count — treating zero as "not found" — is correct on two engines and wrong on the third. Either give it a predicate that discriminates, or set clientFoundRows=true in the MySQL DSN, which switches MySQL to matched semantics.

A note on empty lists ¶

A list parameter that is empty matches nothing, on every dialect: Postgres binds an empty array to `= ANY`, and the other two expand to `IN (NULL)` because `IN ()` is a syntax error there. Asking for the rows whose key is in an empty set gets no rows back, which is what the empty set says, so a caller does not have to guard the call.

The negation is where they part company, and nothing below can warn you. An empty list makes `NOT IN (NULL)` never true, so it matches nothing, while Postgres's empty `<> ALL` is true and matches everything. Both readings are defensible and no shared signature can say which was meant — so test membership rather than its negation, and let the caller decide what an empty set means before it calls.

func New(dialect Dialect, prefix string) (Querier, error)

type ReadQueueStatsParams ¶

type ReadQueueStatsParams struct {
	QueueName      string
	AttemptCeiling int64
}

ReadQueueStatsParams are the arguments to ReadQueueStats.

type ReadQueueStatsRow ¶

type ReadQueueStatsRow struct {
	Pending                 int64
	Ready                   int64
	Leased                  int64
	Stalled                 int64
	Completed               int64
	OldestReadyMicroseconds int64
}

ReadQueueStatsRow is one row of ReadQueueStats's result.

type ReapCompletedItemsParams ¶

type ReapCompletedItemsParams struct {
	QueueName             string
	RetentionMicroseconds int64
	ReapLimit             int64
}

ReapCompletedItemsParams are the arguments to ReapCompletedItems.

type ReleaseItemsParams ¶

type ReleaseItemsParams struct {
	DelayMicroseconds int64
	LastError         *string
	QueueName         string
	ItemKeys          []string
}

ReleaseItemsParams are the arguments to ReleaseItems.

type RemoveItemsParams ¶

type RemoveItemsParams struct {
	QueueName string
	ItemKeys  []string
}

RemoveItemsParams are the arguments to RemoveItems.