database

Documentation

Index

• Variables
• func WithConnMaxLifetime(lifetime time.Duration) dataSourceOption
• func WithMaxConnections(maxConnections int) dataSourceOption
• func WithQueryTimeout(timeout time.Duration) dataSourceOption
• type DBHandle
  • func (s *DBHandle[T]) Close() error
  • func (s *DBHandle[T]) Exec(query string, args ...any) (sql.Result, error)
  • func (s *DBHandle[T]) ExecTimeout(timeout time.Duration, query string, args ...any) (sql.Result, error)
  • func (s *DBHandle[T]) Maintenance(d time.Duration, f MaintenanceFunction) error
  • func (s *DBHandle[T]) Open(ctx context.Context) error
  • func (s *DBHandle[T]) Ping() error
  • func (s *DBHandle[T]) Query(query string, args ...any) (*sql.Rows, error)
  • func (s *DBHandle[T]) QueryRow(query string, args ...any) *sql.Row
  • func (s *DBHandle[T]) QueryRowTimeout(timeout time.Duration, query string, args ...any) *sql.Row
  • func (s *DBHandle[T]) QueryTimeout(timeout time.Duration, query string, args ...any) (*sql.Rows, error)
  • func (s *DBHandle[T]) Statement(key T, generator StatementGenerator) (*sql.Stmt, error)
  • func (s *DBHandle[T]) StopMaintenance()
  • func (s DBHandle[T]) 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 MaintenanceFunction
• type StatementGenerator

Variables

var (
	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")
	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 DBHandle

type DBHandle[T comparable] struct {
	Ctx       context.Context
	DB        *sql.DB
	Driver    DriverName
	DSNSource DataSource
	// contains filtered or unexported fields
}

func (*DBHandle[T]) Close

func (s *DBHandle[T]) 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[T]) Exec

func (s *DBHandle[T]) Exec(query string, args ...any) (sql.Result, error)

func (*DBHandle[T]) ExecTimeout

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

func (*DBHandle[T]) Maintenance

func (s *DBHandle[T]) 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[T]) Open

func (s *DBHandle[T]) 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[T]) Ping

func (s *DBHandle[T]) Ping() error

func (*DBHandle[T]) Query

func (s *DBHandle[T]) Query(query string, args ...any) (*sql.Rows, error)

func (*DBHandle[T]) QueryRow

func (s *DBHandle[T]) QueryRow(query string, args ...any) *sql.Row

func (*DBHandle[T]) QueryRowTimeout

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

func (*DBHandle[T]) QueryTimeout

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

func (*DBHandle[T]) Statement

func (s *DBHandle[T]) Statement(key T, generator StatementGenerator) (*sql.Stmt, error)

func (*DBHandle[T]) StopMaintenance

func (s *DBHandle[T]) StopMaintenance()

func (DBHandle[T]) String

func (s DBHandle[T]) 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
}

DSNOptions is a struct that implements the DataSourceOptions interface, a basic implementaion of DataSourceOptions.

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 MaintenanceFunction

type MaintenanceFunction func(ctx context.Context, db *sql.DB, t time.Time) 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 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.