csql

Documentation

Overview

Package csql helps create and manage database connections

Index

• Constants
• Variables
• func CtxWithTx(parentCtx context.Context, db *sql.DB, dialect string) (context.Context, *sql.Tx, error)
• func NewDBConnection(lc *clifecycle.Lifecycle, config Config, logger clogger.Logger) (*sql.DB, error)
• func TxFromCtx(ctx context.Context) (*sql.Tx, error)
• type Config
  • func LoadConfig(appConfig cconfig.Loader) (Config, error)
• type ConfigMigrations
• type Migrations
• type Migrator
  • func NewMigrator(p NewMigratorParams) *Migrator
  • func (m *Migrator) Run() error
• type NewMigratorParams
• type Querier
  • func NewQuerier(db *sql.DB, config Config) Querier
• type TxMiddleware
  • func NewTxMiddleware(db *sql.DB, config Config, logger clogger.Logger) *TxMiddleware
  • func (m *TxMiddleware) Handle(next http.Handler) http.Handler

Constants

const (
	MigrationsSourceDir   = "dir"
	MigrationsSourceEmbed = "embed"
)

MigrationsSource are valid options for csql.migrations.source configuration option. Use "dir" to load migrations from the local filesystem. Use "embed" to load migrations from the embedded directory in the binary.

const (
	MigrationsDirectionUp   = "up"
	MigrationsDirectionDown = "down"
)

MigrationsDirection are valid options for csql.migrations.direction configuration option. Use "up" when running forward migrations and "down" when rolling back migrations.

Variables

var WireModule = wire.NewSet(
	NewDBConnection,
	NewQuerier,
	NewMigrator,
	LoadConfig,
	NewTxMiddleware,

	wire.Struct(new(NewMigratorParams), "*"),
)

WireModule can be used as part of google/wire setup.

Functions

func CtxWithTx

func CtxWithTx(parentCtx context.Context, db *sql.DB, dialect string) (context.Context, *sql.Tx, error)

CtxWithTx creates a context with a new database transaction. Any queries run using Querier will be run within this transaction.

func NewDBConnection

func NewDBConnection(lc *clifecycle.Lifecycle, config Config, logger clogger.Logger) (*sql.DB, error)

NewDBConnection creates and returns a new database connection. The connection is closed when the app exits.

func TxFromCtx

func TxFromCtx(ctx context.Context) (*sql.Tx, error)

TxFromCtx returns an existing transaction from the context. This method should be called with context created using CtxWithTx.

Types

type Config

type Config struct {
	Dialect            string           `toml:"dialect"`
	DSN                string           `toml:"dsn"`
	Migrations         ConfigMigrations `toml:"migrations"`
	MaxOpenConnections *int             `toml:"max_open_connections"`
}

Config configures the csql module

func LoadConfig

func LoadConfig(appConfig cconfig.Loader) (Config, error)

LoadConfig loads the csql config from the app config

type ConfigMigrations

type ConfigMigrations struct {
	Direction string `toml:"direction"`
	Source    string `toml:"source"`
}

ConfigMigrations configures the migrations

type Migrations

type Migrations embed.FS

Migrations is a collection of .sql files that represent the database schema

type Migrator

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

Migrator can run database migrations by running the provided migrations in the migrations dir

func NewMigrator

func NewMigrator(p NewMigratorParams) *Migrator

NewMigrator creates a new Migrator

func (*Migrator) Run

func (m *Migrator) Run() error

Run runs the provided database migrations

type NewMigratorParams

type NewMigratorParams struct {
	DB         *sql.DB
	Migrations Migrations
	Config     Config
	Logger     clogger.Logger
}

NewMigratorParams holds the params needed for NewMigrator

type Querier

type Querier interface {
	WithIn() Querier
	Get(ctx context.Context, dest interface{}, query string, args ...interface{}) error
	Select(ctx context.Context, dest interface{}, query string, args ...interface{}) error
	Exec(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
}

Querier provides a set of helpful methods to run database queries. It can be used to run parameterized queries and scan results into Go structs or slices.

func NewQuerier

func NewQuerier(db *sql.DB, config Config) Querier

NewQuerier returns a querier using the given database connection and the dialect

type TxMiddleware

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

TxMiddleware is a chttp.Middleware that wraps an HTTP request in a database transaction. If the request succeeds (i.e. 2xx or 3xx response code), the transaction is committed. Else, the transaction is rolled back.

func NewTxMiddleware

func NewTxMiddleware(db *sql.DB, config Config, logger clogger.Logger) *TxMiddleware

NewTxMiddleware creates a new TxMiddleware

func (*TxMiddleware) Handle

func (m *TxMiddleware) Handle(next http.Handler) http.Handler

Handle implements the chttp.Middleware interface. See TxMiddleware