database

Documentation

Index

• Constants
• Variables
• func WithConnMaxLifetime(lifetime time.Duration) dataSourceOption
• func WithMaxConnections(maxConnections int) dataSourceOption
• func WithQueryTimeout(timeout time.Duration) dataSourceOption
• type AfterOpenHook
• type BaseDataSource
  • func NewDataSource(dsn string) BaseDataSource
  • func (d BaseDataSource) ConnMaxLifetime() time.Duration
  • func (d BaseDataSource) DSN() string
  • func (d BaseDataSource) MaxConnections() int
  • func (d BaseDataSource) QueryTimeout() time.Duration
  • func (d BaseDataSource) String() string
• type BaseEngine
  • func NewEngine(driver string, dsnSource DataSource, migrationFS *embed.FS) BaseEngine
  • func (e BaseEngine) DSNSource() DataSource
  • func (e BaseEngine) Driver() string
  • func (e BaseEngine) MigrationFS() *embed.FS
• type BeforeClose
• type BeforeMigrateUpHook
• type DBHandle
  • func New(engine Engine) *DBHandle
  • func (s *DBHandle) AddCloseListener(f BeforeClose) error
  • func (s *DBHandle) Close() error
  • func (s *DBHandle) ExecTimeout(timeout time.Duration, query string, args ...any) (sql.Result, error)
  • func (s *DBHandle) Maintenance(d time.Duration, f MaintenanceFunction) error
  • func (d DBHandle) MigrateReset(env ...string) error
  • func (d *DBHandle) MigrateUp(env ...string) error
  • func (s *DBHandle) Open(ctx context.Context) error
  • func (s *DBHandle) Ping() error
  • func (d DBHandle) PrintMigrationStatus() error
  • func (s *DBHandle) QueryRowTimeout(timeout time.Duration, query string, args ...any) *sql.Row
  • func (s *DBHandle) QueryTimeout(timeout time.Duration, query string, args ...any) (*sql.Rows, error)
  • func (s *DBHandle) Statement(key any, generator StatementGenerator) (*sql.Stmt, error)
  • func (s *DBHandle) Stats() (*stats, error)
  • func (s *DBHandle) StopMaintenance()
  • func (s DBHandle) String() string
• type DSNOptions
  • func NewDSN(dsn string, options ...dataSourceOption) DSNOptions
  • func (d DSNOptions) ConnMaxLifetime() time.Duration
  • func (d DSNOptions) DSN() string
  • func (d DSNOptions) MaxConnections() int
  • func (d DSNOptions) QueryTimeout() time.Duration
  • func (d DSNOptions) String() string
• type DataSource
• type DriverName
• type Engine
• type Maintainable
• type MaintenanceFunction
• type MigrationEnvSetter
• type Observable
• type StatementGenerator

Constants

const (
	MigrationDir = "migrations" // Default directory for migration files (in the embed.FS)
)

Variables

var (
	ErrCantCreateDatabase   = errors.New("can't create the database")
	ErrDatabaseNotFound     = errors.New("database not found")
	ErrDatabaseNotOpen      = errors.New("database not opened")
	ErrDatabaseAlreadyOpen  = errors.New("database already opened")
	ErrDatabaseClosed       = errors.New("database closed")
	ErrCantResetMaintenance = errors.New("can't reset maintenance ticker")
	ErrInvalidDuration      = errors.New("invalid duration for maintenance ticker")
	ErrCloseListenersFull   = errors.New("close listeners are at full capacity")
)

var (
	ErrNoMigrationFS = fmt.Errorf("migration filesystem is not set")
)

var (
	MinMaintenanceInterval = 1 * time.Minute
)

Functions

func WithConnMaxLifetime

func WithConnMaxLifetime(lifetime time.Duration) dataSourceOption

func WithMaxConnections

func WithMaxConnections(maxConnections int) dataSourceOption

func WithQueryTimeout

func WithQueryTimeout(timeout time.Duration) dataSourceOption

Types

type AfterOpenHook

type AfterOpenHook interface {
	AfterOpen(dbh *DBHandle) error
}

Provided for Engine implementations that want to do something right after the connection is opened.

type BaseDataSource

type BaseDataSource string

BaseDataSource provides a basic DataSource implementation that's wrapped around a dsn string. The configiration-ey options (QueryTimeout, MaxConnections, ConnMaxLifetime) are all set to set to defaults that are generally useful for development and probably not appropriate for production.

This implementation was initially provided for tests, but is currently unused and likely to be removed (or moved into a _test.go file) in the future.

func NewDataSource

func NewDataSource(dsn string) BaseDataSource

func (BaseDataSource) ConnMaxLifetime

func (d BaseDataSource) ConnMaxLifetime() time.Duration

func (BaseDataSource) DSN

func (d BaseDataSource) DSN() string

func (BaseDataSource) MaxConnections

func (d BaseDataSource) MaxConnections() int

func (BaseDataSource) QueryTimeout

func (d BaseDataSource) QueryTimeout() time.Duration

func (BaseDataSource) String

func (d BaseDataSource) String() string

type BaseEngine

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

func NewEngine

func NewEngine(driver string, dsnSource DataSource, migrationFS *embed.FS) BaseEngine

Provides a basic Engine implementation that can be used to build and test new DB implementations.

func (BaseEngine) DSNSource

func (e BaseEngine) DSNSource() DataSource

func (BaseEngine) Driver

func (e BaseEngine) Driver() string

func (BaseEngine) MigrationFS

func (e BaseEngine) MigrationFS() *embed.FS

type BeforeClose

type BeforeClose func()

A function to be invoked before the underlying database connection is closed. This function can/should block if it needs to complete in-progress writes.

type BeforeMigrateUpHook

type BeforeMigrateUpHook interface {
	BeforeMigrateUp(dbh *DBHandle) error
}

If the engine provides this hook, it will be run before a migrate up operation is performed.

type DBHandle

type DBHandle struct {
	*sql.DB
	Ctx    context.Context
	Engine Engine
	// contains filtered or unexported fields
}

func New

func New(engine Engine) *DBHandle

func (*DBHandle) AddCloseListener

func (s *DBHandle) AddCloseListener(f BeforeClose) error

Register a callback function to be called before the underlying database connection is closed. The passed function can/should block if it needs to complete in-progress writes. There is a limit (currently 8) to the number of listeners that can be registered. ErrCloseListenersFull will be returned if this limit is reached.

func (*DBHandle) Close

func (s *DBHandle) Close() error

Close will be called when the context passed to Open() is cancelled. It can also be called manually to release resources. It will close the database handle and any prepared statements, and stop any maintenance jobs.

func (*DBHandle) ExecTimeout

func (s *DBHandle) ExecTimeout(timeout time.Duration, query string, args ...any) (sql.Result, error)

Execute an Exec with a timeout. If the timeout is less than or equal to 0, the query timeout is used. This function will return an error if the context is cancelled or the timeout is reached. This is safe to use, since sql.Result doesn't depend on anything happening after the query is executed.

func (*DBHandle) Maintenance

func (s *DBHandle) Maintenance(d time.Duration, f MaintenanceFunction) error

Pass a maintenance function and a duration to run it at. The maintenance function will be called with the context and the database handle. If the function returns an error, the ticker will be stopped. If the duration is 0 or less than a second, an error will be returned. It is possible to set up multiple maintenance functions. The Maintenance ticker will be stopped when this DBHandle is closed, or with a StopMaintenance() call.

func (DBHandle) MigrateReset

func (d DBHandle) MigrateReset(env ...string) error

func (*DBHandle) MigrateUp

func (d *DBHandle) MigrateUp(env ...string) error

Execute an up migration using goose. The environment variables are set before running the migration. This may be used in conjunction with Goose's EnvSubOn directive.

func (*DBHandle) Open

func (s *DBHandle) Open(ctx context.Context) error

Open the database handle with the given context. This handle will be closed if and when this context is cancelled. The context will also be used to prepare statements and as the basis for timeout-bound queries. Open-ing the connection will also apply the DataSource settings to the underlying DB connection *if* these settings are non-zero. Passing unset/zero values for these will inherit the driver defaults.

func (*DBHandle) Ping

func (s *DBHandle) Ping() error

func (DBHandle) PrintMigrationStatus

func (d DBHandle) PrintMigrationStatus() error

func (*DBHandle) QueryRowTimeout

func (s *DBHandle) QueryRowTimeout(timeout time.Duration, query string, args ...any) *sql.Row

Experimental/Do not use: Execute a QueryRow with a timeout. If the timeout is less than or equal to 0, the query timeout is used.

func (*DBHandle) QueryTimeout

func (s *DBHandle) QueryTimeout(timeout time.Duration, query string, args ...any) (*sql.Rows, error)

Experimental/Do not use: Execute a Query with a timeout. If the timeout is less than or equal to 0, the query timeout is used. The goal of this function was to provide a simple way for the caller to specify a timeout for a query, and encapsulate the timeout mechanics. However, since the Rows.Scan() is in the domain of the caller, but _is_ included in the timeout scope, we're forced here to keep the query active until the timeout is reached, which is a worse use of resources than a single long-running query. Leaving this here for reference (hope to get back to it at some point), but it's not recommended to use this function (or the similar QueryRowTimeout).

func (*DBHandle) Statement

func (s *DBHandle) Statement(key any, generator StatementGenerator) (*sql.Stmt, error)

Provides a means to cache prepared statements on a key. Use custom types on the key (e.g. how Context does it) to avoid collisions. The generator function will create the statement if it doesn't exist.

func (*DBHandle) Stats

func (s *DBHandle) Stats() (*stats, error)

func (*DBHandle) StopMaintenance

func (s *DBHandle) StopMaintenance()

func (DBHandle) String

func (s DBHandle) String() string

Convenience method to get the safe DSN string, with the password obscured. Implements fmt.Stringer interface.

type DSNOptions

type DSNOptions struct {
	DSNString string
	// contains filtered or unexported fields
}

func NewDSN

func NewDSN(dsn string, options ...dataSourceOption) DSNOptions

func (DSNOptions) ConnMaxLifetime

func (d DSNOptions) ConnMaxLifetime() time.Duration

func (DSNOptions) DSN

func (d DSNOptions) DSN() string

func (DSNOptions) MaxConnections

func (d DSNOptions) MaxConnections() int

func (DSNOptions) QueryTimeout

func (d DSNOptions) QueryTimeout() time.Duration

func (DSNOptions) String

func (d DSNOptions) String() string

type DataSource

type DataSource interface {
	// Loggable string representation of the options
	fmt.Stringer
	// Returns the DSN string for the options (not ever written to logs)
	DSN() string
	QueryTimeout() time.Duration
	MaxConnections() int
	ConnMaxLifetime() time.Duration
}

DataSource is an interface that defines the options for a database connection. The DSN() method should return the DSN string for the connection. The String() method will be used when logging information about the connection. If the real DSN() contains a password or other privileged information, it should be masked in the String() method.

type DriverName

type DriverName string

const (
	SQLite DriverName = "sqlite3"
	MySQL  DriverName = "mysql"
)

type Engine

type Engine interface {
	// Provides DSN and basic configuration info
	DSNSource() DataSource
	// Driver Name
	Driver() string
	// Migrations directory, or nil if unsupported
	MigrationFS() *embed.FS
}

Interface for specific database implementations using DBHandle. SQL database handling is typically differentiated across 3 dimensions: 1. Configuration and DSN string generation 2. Open semantics (e.g. things you have to do when opening the connection) 3. Migrations (e.g. that's where platform-specific SQL needs tend to show up) This interface (along with the supplemental/options interfaces below), provide the hooks to implement platform-specific behaviors, while core CRUD operations using DBHandle should only require one implementation.

type Maintainable

type Maintainable interface {
	Maintain(dbh *DBHandle) error
}

Interface for DB maintenance functions. Required for invoking maintenance on-demand, not necessarily needed for setting up periodic maintenance.

type MaintenanceFunction

type MaintenanceFunction func(dbh *DBHandle) error

MaintenanceFunction is a function that can be called periodically to perform maintenance on the database. It's passed the context and current database handle. Returning an error will stop the maintenance ticker.

type MigrationEnvSetter

type MigrationEnvSetter interface {
	MigrationEnv() []string
}

If the engine provides this hook, it should return a list of key/value pairs that will be inserted into the environment before a migration is run. These environment variables can be used in the migration scripts, and will be cleared after the migration is run.

type Observable

type Observable interface {
	Stats(dbh *DBHandle) (any, error)
}

This interface is to expose a method to supply supplemental data (beyond what sql.Stats provides), in healthcheacks. The struct returned from this function will be added to the stats struct under the key 'engine'.

type StatementGenerator

type StatementGenerator func(ctx context.Context, db *sql.DB) (*sql.Stmt, error)

StatementGenerator is a function that returns a prepared statement. The DBHandle holds a map of prepared statements, and will clean them up when closing.