database

Documentation

Overview

Package database is a facade over the data storage layer.

Index

• Variables
• func NullableTime(t time.Time) *time.Time
• type Config
  • func (c *Config) ConnectionURL() string
  • func (c *Config) DatabaseConfig() *Config
  • func (c *Config) SecretManagerConfig() *secrets.Config
• type DB
  • func NewFromEnv(ctx context.Context, cfg *Config) (*DB, error)
  • func (db *DB) Close(ctx context.Context)
  • func (db *DB) InTx(ctx context.Context, isoLevel pgx.TxIsoLevel, f func(tx pgx.Tx) error) error
  • func (db *DB) Lock(ctx context.Context, lockID string, ttl time.Duration) (UnlockFn, error)
  • func (db *DB) MultiLock(ctx context.Context, lockIDs []string, ttl time.Duration) (UnlockFn, error)
• type TestInstance
  • func MustTestInstance() *TestInstance
  • func NewTestInstance() (*TestInstance, error)
  • func (i *TestInstance) Close() (retErr error)
  • func (i *TestInstance) MustClose() error
  • func (i *TestInstance) NewDatabase(tb testing.TB) (*DB, *Config)
• type UnlockFn

Variables

var (
	// ErrNotFound indicates that the requested record was not found in the database.
	ErrNotFound = errors.New("record not found")

	// ErrKeyConflict indicates that there was a key conflict inserting a row.
	ErrKeyConflict = errors.New("key conflict")
)

var ApproxTime = cmp.Options{cmpopts.EquateApproxTime(1 * time.Second)}

ApproxTime is a compare helper for clock skew.

var (
	// ErrAlreadyLocked is returned if the lock is already in use.
	ErrAlreadyLocked = errors.New("lock already in use")
)

Functions

func NullableTime

func NullableTime(t time.Time) *time.Time

Types

type Config

type Config struct {
	Secrets secrets.Config

	Name               string        `env:"DB_NAME" json:",omitempty"`
	User               string        `env:"DB_USER" json:",omitempty"`
	Host               string        `env:"DB_HOST, default=localhost" json:",omitempty"`
	Port               string        `env:"DB_PORT, default=5432" json:",omitempty"`
	SSLMode            string        `env:"DB_SSLMODE, default=require" json:",omitempty"`
	ConnectionTimeout  int           `env:"DB_CONNECT_TIMEOUT" json:",omitempty"`
	Password           string        `env:"DB_PASSWORD" json:"-"` // ignored by zap's JSON formatter
	SSLCertPath        string        `env:"DB_SSLCERT" json:",omitempty"`
	SSLKeyPath         string        `env:"DB_SSLKEY" json:",omitempty"`
	SSLRootCertPath    string        `env:"DB_SSLROOTCERT" json:",omitempty"`
	PoolMinConnections string        `env:"DB_POOL_MIN_CONNS" json:",omitempty"`
	PoolMaxConnections string        `env:"DB_POOL_MAX_CONNS" json:",omitempty"`
	PoolMaxConnLife    time.Duration `env:"DB_POOL_MAX_CONN_LIFETIME, default=5m" json:",omitempty"`
	PoolMaxConnIdle    time.Duration `env:"DB_POOL_MAX_CONN_IDLE_TIME, default=1m" json:",omitempty"`
	PoolHealthCheck    time.Duration `env:"DB_POOL_HEALTH_CHECK_PERIOD, default=1m" json:",omitempty"`
}

func (*Config) ConnectionURL

func (c *Config) ConnectionURL() string

func (*Config) DatabaseConfig

func (c *Config) DatabaseConfig() *Config

func (*Config) SecretManagerConfig

func (c *Config) SecretManagerConfig() *secrets.Config

type DB

type DB struct {
	Pool *pgxpool.Pool
}

func NewFromEnv

func NewFromEnv(ctx context.Context, cfg *Config) (*DB, error)

NewFromEnv sets up the database connections using the configuration in the process's environment variables. This should be called just once per server instance.

func (*DB) Close

func (db *DB) Close(ctx context.Context)

Close releases database connections.

func (*DB) InTx

func (db *DB) InTx(ctx context.Context, isoLevel pgx.TxIsoLevel, f func(tx pgx.Tx) error) error

InTx runs the given function f within a transaction with the provided isolation level isoLevel.

func (*DB) Lock

func (db *DB) Lock(ctx context.Context, lockID string, ttl time.Duration) (UnlockFn, error)

Lock acquires lock with given name that times out after ttl. Returns an UnlockFn that can be used to unlock the lock. ErrAlreadyLocked will be returned if there is already a lock in use.

func (*DB) MultiLock

func (db *DB) MultiLock(ctx context.Context, lockIDs []string, ttl time.Duration) (UnlockFn, error)

MultiLock obtains multiple locks in a single transaction. Either all locks are obtained, or the transaction is rolled back. The lockIDs are sorted by normal ascending string sort order before obtaining the locks.

type TestInstance

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

TestInstance is a wrapper around the Docker-based database instance.

func MustTestInstance

func MustTestInstance() *TestInstance

MustTestInstance is NewTestInstance, except it prints errors to stderr and calls os.Exit when finished. Callers can call Close or MustClose().

func NewTestInstance

func NewTestInstance() (*TestInstance, error)

NewTestInstance creates a new Docker-based database instance. It also creates an initial database, runs the migrations, and sets that database as a template to be cloned by future tests.

This should not be used outside of testing, but it is exposed in the package so it can be shared with other packages. It should be called and instantiated in TestMain.

All database tests can be skipped by running `go test -short` or by setting the `SKIP_DATABASE_TESTS` environment variable.

func (*TestInstance) Close

func (i *TestInstance) Close() (retErr error)

Close terminates the test database instance, cleaning up any resources.

func (*TestInstance) MustClose

func (i *TestInstance) MustClose() error

MustClose is like Close except it prints the error to stderr and calls os.Exit.

func (*TestInstance) NewDatabase

func (i *TestInstance) NewDatabase(tb testing.TB) (*DB, *Config)

NewDatabase creates a new database suitable for use in testing. It returns an established database connection and the configuration.

type UnlockFn

type UnlockFn func() error

UnlockFn can be deferred to release a lock.