storage

package module
v0.16.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: 29 Imported by: 0

Documentation

Overview

Package storage provides abstractions for database interactions and default implementations.

Package storage provides abstractions for queue interactions and default implementations.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotFound reports that a query expected a row but found none.
	ErrNotFound = errors.New("storage: not found")
	// ErrConflict reports that a write violated a unique constraint.
	ErrConflict = errors.New("storage: conflict")
)

Functions

func AddEmailWorkers added in v0.12.0

func AddEmailWorkers(
	workers *river.Workers,
	transactional postmand.TransactionalSender,
	marketing postmand.MarketingSender,
)

AddEmailWorkers registers the framework email workers on workers.

func AtomicOps added in v0.9.0

func AtomicOps(
	ctx context.Context,
	t Transactor,
	fn func(ctx context.Context, tx Tx) error,
	options ...TxOption,
) error

AtomicOps runs fn inside one transaction, and is the only way to commit or roll one back.

With an unbound Transactor it opens the transaction, commits when fn returns nil, and rolls back when fn returns an error or panics. The error is returned unchanged; a commit failure is returned wrapped. ReadOnly and Isolation options configure the transaction it opens.

With a bound Transactor (see InTx) it runs fn in the bound transaction and leaves commit and rollback to the owner of that transaction. Transaction options cannot be applied to an already-open transaction and are rejected; nil options are ignored on both paths because they configure nothing.

func Conflict added in v0.12.0

func Conflict(err error, constraint string) error

Conflict wraps ErrConflict when err is a unique violation of constraint. Unrelated errors are returned unchanged.

func Row added in v0.12.0

func Row[T any](v T, err error) (T, error)

Row maps pgx.ErrNoRows to ErrNotFound and returns any other error unchanged.

func RunMigrations

func RunMigrations(ctx context.Context, conn Connection, migrations fs.FS, migrationDir string) error

RunMigrations applies every Goose migration from an embedded filesystem. Goose still requires database/sql, so this opens a short-lived stdlib adapter over the same pgx pool.

func RunMigrationsTo added in v0.14.0

func RunMigrationsTo(
	ctx context.Context,
	conn Connection,
	migrations fs.FS,
	migrationDir string,
	version int64,
) error

RunMigrationsTo applies Goose migrations up to and including version. Use RunMigrations to apply every migration from an embedded filesystem.

func SendTransactional added in v0.12.0

func SendTransactional(
	ctx context.Context,
	data postmand.TransactionalData,
	sender postmand.TransactionalSender,
) error

SendTransactional delivers data, cancelling the job on errors a retry cannot fix.

Types

type Config added in v0.2.0

type Config struct {
	DatabaseKind             string
	Host                     string
	Port                     string
	Name                     string
	User                     string
	Password                 string
	SSLMode                  string
	ApplicationName          string
	ConnectTimeout           time.Duration
	StatementCacheCapacity   int
	DescriptionCacheCapacity int
	MaxOpenConnections       int
	MaxIdleConnections       int
	ConnectionMaxLifetime    time.Duration
	ConnectionMaxIdleTime    time.Duration
	OpenTelemetry            bool
}

Config contains PostgreSQL connection settings. Applications supply database identity and credentials and may override DefaultConfig's operational defaults.

func DefaultConfig added in v0.2.0

func DefaultConfig() Config

DefaultConfig returns operational defaults without application credentials.

func (Config) DatabaseURL added in v0.2.0

func (config Config) DatabaseURL() (string, error)

DatabaseURL returns the PostgreSQL connection URL represented by config.

func (Config) Validate added in v0.2.0

func (config Config) Validate() error

Validate verifies that all required connection settings are present.

type Connection added in v0.2.0

type Connection interface {
	Exec(ctx context.Context, sql string, arguments ...any) (pgconn.CommandTag, error)
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
	Health(ctx context.Context) error
	BeginTransaction(ctx context.Context) (Transaction, error)
}

Connection is the application database handle. Constructors and collaborators take this type rather than a driver-specific pool. Query methods match pgx DBTX so narsilc-generated clients can accept Connection directly: queries.New(db).

type InsertQueue

type InsertQueue interface {
	Insert(context.Context, river.JobArgs, *river.InsertOpts) (*rivertype.JobInsertResult, error)
	InsertMany(context.Context, []river.InsertManyParams) ([]*rivertype.JobInsertResult, error)
	InsertManyFast(context.Context, []river.InsertManyParams) (int, error)
	// InTx returns a queue whose inserts join tx: the jobs become visible to
	// workers only if tx commits.
	InTx(tx Tx) InsertQueue
}

InsertQueue is the subset of River used to insert jobs. Whether an insert is transactional depends only on whether the queue was bound with InTx.

type IsolationLevel added in v0.14.0

type IsolationLevel string

IsolationLevel names a PostgreSQL transaction isolation level.

type Option added in v0.2.0

type Option func(*postgresOptions) error

Option configures a PostgreSQL connection.

func WithApplicationName added in v0.2.0

func WithApplicationName(name string) Option

WithApplicationName sets the PostgreSQL application_name runtime parameter.

func WithConnectTimeout added in v0.2.0

func WithConnectTimeout(timeout time.Duration) Option

WithConnectTimeout sets the PostgreSQL connection timeout.

func WithConnectionMaxIdleTime added in v0.2.0

func WithConnectionMaxIdleTime(idleTime time.Duration) Option

WithConnectionMaxIdleTime sets the maximum time a connection may remain idle.

func WithConnectionMaxLifetime added in v0.2.0

func WithConnectionMaxLifetime(lifetime time.Duration) Option

WithConnectionMaxLifetime sets the maximum reusable connection lifetime.

func WithDatabaseURL added in v0.2.0

func WithDatabaseURL(databaseURL string) Option

WithDatabaseURL configures the connection from a PostgreSQL URL.

func WithDescriptionCacheCapacity added in v0.2.0

func WithDescriptionCacheCapacity(capacity int) Option

WithDescriptionCacheCapacity sets the query description cache capacity.

func WithMaxIdleConnections added in v0.2.0

func WithMaxIdleConnections(count int) Option

WithMaxIdleConnections is retained for configuration compatibility. pgxpool has no max-idle analog; prefer MaxOpenConnections and ConnectionMaxIdleTime.

func WithMaxOpenConnections added in v0.2.0

func WithMaxOpenConnections(count int) Option

WithMaxOpenConnections sets the pgx pool MaxConns limit.

func WithOpenTelemetry added in v0.2.0

func WithOpenTelemetry(config TelemetryConfig) Option

WithOpenTelemetry configures PostgreSQL tracing and metrics.

func WithRuntimeParameters added in v0.2.0

func WithRuntimeParameters(parameters map[string]string) Option

WithRuntimeParameters merges PostgreSQL runtime parameters.

func WithStatementCacheCapacity added in v0.2.0

func WithStatementCacheCapacity(capacity int) Option

WithStatementCacheCapacity sets the prepared statement cache capacity.

func WithTLSConfig added in v0.2.0

func WithTLSConfig(config *tls.Config) Option

WithTLSConfig replaces the TLS configuration used by PostgreSQL.

func WithTelemetry added in v0.12.0

func WithTelemetry(provider TelemetryProvider) Option

WithTelemetry configures PostgreSQL tracing and metrics from a telemetry provider. A nil provider disables instrumentation.

func WithoutOpenTelemetry added in v0.2.0

func WithoutOpenTelemetry() Option

WithoutOpenTelemetry disables PostgreSQL tracing and metrics.

type PageRequest added in v0.12.0

type PageRequest struct {
	Page     int64
	PageSize int64
	Limit    int32
	Offset   int32
}

PageRequest is a clamped page selection ready for a query.

func Page added in v0.12.0

func Page(page, pageSize int64) PageRequest

Page clamps page and pageSize to a valid selection. The page starts at 1, pageSize defaults to 10, pageSize is capped at 100, and the offset is kept inside int32 so a huge page cannot wrap into a negative SQL OFFSET.

type Paginated added in v0.12.0

type Paginated[T any] struct {
	Items      []T
	TotalCount int64
	Page       int64
	PageSize   int64
	TotalPages int64
}

Paginated is one page of items with the total count and page metadata.

func NewPaginated added in v0.12.0

func NewPaginated[T any](items []T, total int64, req PageRequest) Paginated[T]

NewPaginated combines a page of items with its total count and request.

type Postgres

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

Postgres wraps a pgx/v5 pool.

func NewPostgres

func NewPostgres(ctx context.Context, config Config, options ...Option) (*Postgres, error)

NewPostgres creates a new database connection from the supplied configuration.

func (*Postgres) BeginTransaction added in v0.4.0

func (p *Postgres) BeginTransaction(ctx context.Context) (Transaction, error)

BeginTransaction starts a transaction on the shared pool.

func (*Postgres) BeginTransactionWithOptions added in v0.14.0

func (p *Postgres) BeginTransactionWithOptions(
	ctx context.Context,
	options pgx.TxOptions,
) (Transaction, error)

BeginTransactionWithOptions starts a transaction with explicit PostgreSQL transaction options. AtomicOps calls it when ReadOnly or Isolation is set.

func (*Postgres) Close

func (p *Postgres) Close() error

Close closes the underlying pgx pool.

func (*Postgres) Exec added in v0.8.0

func (p *Postgres) Exec(ctx context.Context, sql string, arguments ...any) (pgconn.CommandTag, error)

func (*Postgres) Health added in v0.7.0

func (p *Postgres) Health(ctx context.Context) error

Health verifies that the database is reachable at runtime.

func (*Postgres) Pool added in v0.8.0

func (p *Postgres) Pool() *pgxpool.Pool

Pool returns the wrapped pgx pool.

func (*Postgres) Query added in v0.8.0

func (p *Postgres) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)

func (*Postgres) QueryRow added in v0.8.0

func (p *Postgres) QueryRow(ctx context.Context, sql string, args ...any) pgx.Row

type QueueConfig added in v0.6.0

type QueueConfig struct {
	AdvisoryLockPrefix          int32
	CancelledJobRetentionPeriod time.Duration
	CompletedJobRetentionPeriod time.Duration
	DiscardedJobRetentionPeriod time.Duration
	FetchCooldown               time.Duration
	PollInterval                time.Duration
	ID                          string
	JobCleanerTimeout           time.Duration
	JobStuckThreshold           time.Duration
	JobTimeout                  time.Duration
	MaxAttempts                 int
	MaxWorkers                  int
	Queues                      map[string]river.QueueConfig
	PollOnly                    bool
	ReindexerIndexNames         []string
	ReindexerTimeout            time.Duration
	RescueStuckJobsAfter        time.Duration
	Schema                      string
	SoftStopTimeout             time.Duration
	SkipJobKindValidation       bool
	SkipUnknownJobCheck         bool
}

QueueConfig contains River client settings and application queue definitions.

func DefaultQueueConfig added in v0.6.0

func DefaultQueueConfig() QueueConfig

DefaultQueueConfig returns operational defaults and no processor queues. Applications choose their queue names and concurrency in Queues.

func (QueueConfig) Clone added in v0.6.0

func (config QueueConfig) Clone() QueueConfig

Clone returns a configuration with independently mutable collections.

func (QueueConfig) RiverConfig added in v0.6.0

func (config QueueConfig) RiverConfig() river.Config

RiverConfig returns the River client configuration represented by config.

func (QueueConfig) Validate added in v0.6.0

func (config QueueConfig) Validate() error

Validate verifies queue configuration.

type QueueInsert added in v0.3.0

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

QueueInsert is an independently constructible River job inserter. A QueueInsert returned by InTx inserts on that transaction.

func NewQueueInsert added in v0.3.0

func NewQueueInsert(connection Connection, config QueueConfig, options ...QueueOption) (*QueueInsert, error)

NewQueueInsert creates an insert-only queue client using connection.

func (*QueueInsert) Client added in v0.15.0

func (q *QueueInsert) Client() *river.Client[pgx.Tx]

Client returns the River client behind this queue, for read-side work such as job history or mounting River UI from the web process. Inserts made directly on the returned client are not bound to any transaction; use Insert or InTx on QueueInsert to make an insert transactional.

func (*QueueInsert) InTx added in v0.9.0

func (q *QueueInsert) InTx(tx Tx) InsertQueue

InTx returns a QueueInsert whose inserts join tx.

func (*QueueInsert) Insert added in v0.3.0

func (*QueueInsert) InsertMany added in v0.3.0

func (q *QueueInsert) InsertMany(
	ctx context.Context,
	params []river.InsertManyParams,
) ([]*rivertype.JobInsertResult, error)

func (*QueueInsert) InsertManyFast added in v0.3.0

func (q *QueueInsert) InsertManyFast(
	ctx context.Context,
	params []river.InsertManyParams,
) (int, error)

type QueueOption added in v0.3.0

type QueueOption func(*river.Config)

QueueOption configures the underlying River client.

func WithRiverAdvisoryLockPrefix added in v0.3.0

func WithRiverAdvisoryLockPrefix(prefix int32) QueueOption

func WithRiverCancelledJobRetentionPeriod added in v0.3.0

func WithRiverCancelledJobRetentionPeriod(period time.Duration) QueueOption

func WithRiverCompletedJobRetentionPeriod added in v0.3.0

func WithRiverCompletedJobRetentionPeriod(period time.Duration) QueueOption

func WithRiverConfig added in v0.3.0

func WithRiverConfig(config river.Config) QueueOption

WithRiverConfig replaces the complete River configuration. Options are applied in order, so field-specific options after this one override it.

func WithRiverDiscardedJobRetentionPeriod added in v0.3.0

func WithRiverDiscardedJobRetentionPeriod(period time.Duration) QueueOption

func WithRiverErrorHandler added in v0.3.0

func WithRiverErrorHandler(handler river.ErrorHandler) QueueOption

func WithRiverFetchCooldown added in v0.3.0

func WithRiverFetchCooldown(cooldown time.Duration) QueueOption

func WithRiverFetchPollInterval added in v0.3.0

func WithRiverFetchPollInterval(interval time.Duration) QueueOption

func WithRiverHooks added in v0.3.0

func WithRiverHooks(hooks ...rivertype.Hook) QueueOption

func WithRiverID added in v0.3.0

func WithRiverID(id string) QueueOption

func WithRiverJobCleanerTimeout added in v0.3.0

func WithRiverJobCleanerTimeout(timeout time.Duration) QueueOption

func WithRiverJobStuckHandler added in v0.3.0

func WithRiverJobStuckHandler(handler river.JobStuckHandler) QueueOption

func WithRiverJobStuckThreshold added in v0.3.0

func WithRiverJobStuckThreshold(threshold time.Duration) QueueOption

func WithRiverJobTimeout added in v0.3.0

func WithRiverJobTimeout(timeout time.Duration) QueueOption

func WithRiverLogger added in v0.3.0

func WithRiverLogger(logger *slog.Logger) QueueOption

func WithRiverMaxAttempts added in v0.3.0

func WithRiverMaxAttempts(maxAttempts int) QueueOption

func WithRiverMiddleware added in v0.3.0

func WithRiverMiddleware(middleware ...rivertype.Middleware) QueueOption

func WithRiverPeriodicJobs added in v0.3.0

func WithRiverPeriodicJobs(jobs ...*river.PeriodicJob) QueueOption

func WithRiverPollOnly added in v0.3.0

func WithRiverPollOnly(pollOnly bool) QueueOption

func WithRiverQueues added in v0.3.0

func WithRiverQueues(queues map[string]river.QueueConfig) QueueOption

func WithRiverReindexerIndexNames added in v0.3.0

func WithRiverReindexerIndexNames(names ...string) QueueOption

func WithRiverReindexerSchedule added in v0.3.0

func WithRiverReindexerSchedule(schedule river.PeriodicSchedule) QueueOption

func WithRiverReindexerTimeout added in v0.3.0

func WithRiverReindexerTimeout(timeout time.Duration) QueueOption

func WithRiverRescueStuckJobsAfter added in v0.3.0

func WithRiverRescueStuckJobsAfter(period time.Duration) QueueOption

func WithRiverRetryPolicy added in v0.3.0

func WithRiverRetryPolicy(policy river.ClientRetryPolicy) QueueOption

func WithRiverSchema added in v0.3.0

func WithRiverSchema(schema string) QueueOption

func WithRiverSkipUnknownJobCheck added in v0.3.0

func WithRiverSkipUnknownJobCheck(skip bool) QueueOption

func WithRiverSoftStopTimeout added in v0.3.0

func WithRiverSoftStopTimeout(timeout time.Duration) QueueOption

func WithRiverTestConfig added in v0.3.0

func WithRiverTestConfig(test river.TestConfig) QueueOption

func WithRiverTestOnly added in v0.3.0

func WithRiverTestOnly(testOnly bool) QueueOption

func WithRiverWorkers added in v0.3.0

func WithRiverWorkers(workers *river.Workers) QueueOption

type QueueProcessor added in v0.3.0

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

QueueProcessor owns the lifecycle of a River worker client.

func NewQueueProcessor added in v0.3.0

func NewQueueProcessor(connection Connection, config QueueConfig, options ...QueueOption) (*QueueProcessor, error)

NewQueueProcessor creates a worker client using connection.

func (*QueueProcessor) Start added in v0.3.0

func (q *QueueProcessor) Start(ctx context.Context) error

Start starts processing jobs and returns once the processor is ready.

func (*QueueProcessor) Stop added in v0.3.0

func (q *QueueProcessor) Stop(ctx context.Context) error

Stop gracefully stops processing jobs.

type SendMarketingEmailArgs added in v0.12.0

type SendMarketingEmailArgs struct {
	Data postmand.MarketingData
}

SendMarketingEmailArgs carries one marketing email to its worker.

func (SendMarketingEmailArgs) Kind added in v0.12.0

type SendMarketingEmailWorker added in v0.12.0

type SendMarketingEmailWorker struct {
	river.WorkerDefaults[SendMarketingEmailArgs]
	// contains filtered or unexported fields
}

SendMarketingEmailWorker delivers a marketing email.

func NewSendMarketingEmailWorker added in v0.12.0

func NewSendMarketingEmailWorker(sender postmand.MarketingSender) *SendMarketingEmailWorker

func (*SendMarketingEmailWorker) Work added in v0.12.0

type SendTransactionalEmailArgs added in v0.12.0

type SendTransactionalEmailArgs struct {
	Data postmand.TransactionalData
}

SendTransactionalEmailArgs carries one transactional email to its worker.

func (SendTransactionalEmailArgs) Kind added in v0.12.0

type SendTransactionalEmailWorker added in v0.12.0

type SendTransactionalEmailWorker struct {
	river.WorkerDefaults[SendTransactionalEmailArgs]
	// contains filtered or unexported fields
}

SendTransactionalEmailWorker delivers a transactional email.

func NewSendTransactionalEmailWorker added in v0.12.0

func NewSendTransactionalEmailWorker(
	sender postmand.TransactionalSender,
) *SendTransactionalEmailWorker

func (*SendTransactionalEmailWorker) Work added in v0.12.0

type TelemetryConfig added in v0.2.0

type TelemetryConfig struct {
	TracerProvider         trace.TracerProvider
	MeterProvider          metric.MeterProvider
	Attributes             []attribute.KeyValue
	TrimSQLInSpanName      bool
	IncludeQueryParameters bool
}

TelemetryConfig configures PostgreSQL OpenTelemetry instrumentation without exposing the underlying database driver.

type TelemetryProvider added in v0.12.0

type TelemetryProvider interface {
	TracerProvider() trace.TracerProvider
	MeterProvider() metric.MeterProvider
}

TelemetryProvider supplies the OpenTelemetry providers used to instrument PostgreSQL. *telemetry.Telemetry satisfies it.

type Transaction added in v0.4.0

type Transaction interface {
	Exec(ctx context.Context, sql string, arguments ...any) (pgconn.CommandTag, error)
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
	Commit(ctx context.Context) error
	Rollback(ctx context.Context) error
}

Transaction is one PostgreSQL transaction on a Connection. narsilc clients accept it directly: queries.New(tx). Application code outside the domains layer holds the opaque Tx instead (see AtomicOps).

func Unwrap added in v0.9.0

func Unwrap(tx Tx) Transaction

Unwrap returns the transaction behind tx so a domain receiver can bind its generated queries to it (queries.New(storage.Unwrap(tx))). Only the domains layer calls it; andurel verify fails on any other call site.

type TransactionUnwrapper added in v0.14.0

type TransactionUnwrapper interface {
	UnwrapTransaction() Transaction
}

TransactionUnwrapper is implemented by decorators that wrap another Transaction. pgxTxFrom follows it, so a wrapper can preserve transactional queue inserts without exposing the unexported pgxTx method. Implementations must return the wrapped transaction; a nil or cyclic chain is rejected.

type Transactor added in v0.9.0

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

Transactor opens transactions for AtomicOps. One from NewTransactor opens a new transaction per call; one returned by InTx joins that transaction instead, so code that is atomic on its own also composes into a caller's transaction.

func NewTransactor added in v0.9.0

func NewTransactor(conn Connection) Transactor

NewTransactor returns a Transactor that opens transactions on conn.

func (Transactor) InTx added in v0.9.0

func (t Transactor) InTx(tx Tx) Transactor

InTx returns a Transactor whose AtomicOps joins tx instead of opening a new transaction.

type Tx added in v0.9.0

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

Tx is an open transaction. It has no query methods: holding one lets a caller bind to the transaction (an InTx method) but not issue SQL. Only AtomicOps creates a usable Tx.

type TxOption added in v0.14.0

type TxOption interface {
	// contains filtered or unexported methods
}

TxOption configures the transaction AtomicOps opens.

func Isolation added in v0.14.0

func Isolation(level IsolationLevel) TxOption

Isolation opens the transaction at level. The default is the server's setting, normally READ COMMITTED.

func ReadOnly added in v0.14.0

func ReadOnly() TxOption

ReadOnly opens the transaction with PostgreSQL's READ ONLY access mode, so any write fails instead of committing.

Directories

Path Synopsis
Package storagetest starts Postgres test containers and creates isolated, migrated databases for tests.
Package storagetest starts Postgres test containers and creates isolated, migrated databases for tests.

Jump to

Keyboard shortcuts

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