Documentation

Overview

    Package database is a facade over the data storage layer.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    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")
    )

      ApproxTime is a compare helper for clock skew.

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

      Functions

      This section is empty.

      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.

                func (*DB) NullableTime

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

                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.