postgres

Documentation

Overview

Package postgres provides transactional admission backed by PostgreSQL and pgx. It is intended for coordination-heavy workloads, not as the default high-throughput backend.

Index

• Constants
• func GoMigration() (migrations.Migration, error)
• type ClockPolicy
• type Migration
  • func SchemaMigration() Migration
• type Options
• type Store
  • func New(pool *pgxpool.Pool, options Options) (*Store, error)
  • func Open(ctx context.Context, pool *pgxpool.Pool, options Options) (*Store, error)
  • func (store *Store) Acquire(ctx context.Context, request ratelimit.LeaseRequest) (ratelimit.Lease, ratelimit.Decision, error)
  • func (store *Store) Admit(ctx context.Context, request ratelimit.Request) (ratelimit.Decision, error)
  • func (store *Store) Check(ctx context.Context) error
  • func (store *Store) Cleanup(ctx context.Context, batch int) (int64, error)
  • func (store *Store) Name() string
  • func (store *Store) Release(ctx context.Context, lease ratelimit.Lease) error

Constants

const (
	// MaxCleanupBatch bounds rows locked and returned by one cleanup statement.
	MaxCleanupBatch = 10_000
)

Functions

func GoMigration

func GoMigration() (migrations.Migration, error)

GoMigration adapts SchemaMigration to migrations.

Types

type ClockPolicy

type ClockPolicy uint8

ClockPolicy selects the authoritative time source for transactions.

const (
	// ClientClock uses Request.Now and clamps rollback per key.
	ClientClock ClockPolicy = iota
	// ServerClock uses PostgreSQL clock_timestamp in the locked transaction.
	ServerClock
)

type Migration

type Migration struct {
	// Version is the migrations version.
	Version uint
	// Name is the stable migration name.
	Name string
	// Up creates indexed rate-limit state storage.
	Up string
	// Down removes package-owned state storage.
	Down string
}

Migration is the portable SQL definition owned by this package.

func SchemaMigration

func SchemaMigration() Migration

SchemaMigration returns the package-owned PostgreSQL schema migration.

type Options

type Options struct {
	// Timeout bounds each backend operation.
	Timeout time.Duration
	// LockTimeout bounds PostgreSQL lock acquisition; zero uses Timeout.
	LockTimeout time.Duration
	// Clock selects client or PostgreSQL server time.
	Clock ClockPolicy
}

Options configures transaction deadlines, lock waits, and clock authority.

type Store

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

Store is an atomic pgx-backed admission backend.

func New

func New(pool *pgxpool.Pool, options Options) (*Store, error)

New constructs a Store without checking whether its migration is installed.

func Open

func Open(ctx context.Context, pool *pgxpool.Pool, options Options) (*Store, error)

Open constructs a Store and verifies the package-owned table exists.

func (*Store) Acquire

func (store *Store) Acquire(ctx context.Context, request ratelimit.LeaseRequest) (ratelimit.Lease, ratelimit.Decision, error)

Acquire transactionally obtains a weighted distributed concurrency lease.

func (*Store) Admit

func (store *Store) Admit(ctx context.Context, request ratelimit.Request) (ratelimit.Decision, error)

Admit evaluates one non-concurrency request in a locked transaction.

func (*Store) Check

func (store *Store) Check(ctx context.Context) error

Check verifies that the package-owned schema migration is installed.

func (*Store) Cleanup

func (store *Store) Cleanup(ctx context.Context, batch int) (int64, error)

Cleanup deletes at most batch expired states using SKIP LOCKED.

func (*Store) Name

func (store *Store) Name() string

Name returns the stable backend identifier.

func (*Store) Release

func (store *Store) Release(ctx context.Context, lease ratelimit.Lease) error

Release transactionally verifies and relinquishes an owned lease.