database

Documentation

Overview

Package database implements PostgreSQL database client helpers.

Index

• Constants
• Variables
• func Migrate(db *sql.DB, migrations fs.FS, direction MigrationDirection) (int, error)
• func MigrateMax(db *sql.DB, migrations fs.FS, direction MigrationDirection, maxAmount int) (int, error)
• func NewStdlib(ctx context.Context, cfg Config) (*sql.DB, error)
• type CommandTag
• type Config
  • func (cfg *Config) Validate() error
• type Connection
  • func New(ctx context.Context, cfg Config) (*Connection, error)
• type Logger
  • func NewLogger(logger *log.Logger) *Logger
  • func (l *Logger) Level() tracelog.LogLevel
  • func (l *Logger) Log(ctx context.Context, level tracelog.LogLevel, msg string, data map[string]any)
• type LoggerContract
• type MigrationDirection
• type Pool
  • func NewPool(ctx context.Context, cfg Config) (*Pool, error)
  • func (p *Pool) Close(_ context.Context) error
• type Querier
• type Row
• type Rows

Constants

const (
	// UpMigration executes migrations that are new and have not been applied yet.
	UpMigration = migrate.Up
	// DownMigration migrates down.
	DownMigration = migrate.Down
)

Variables

var (
	// ErrNoRows occurs when rows are expected but none are returned.
	ErrNoRows = pgx.ErrNoRows
	// ErrRowAlreadyExists occurs when a row already exists when trying to insert.
	ErrRowAlreadyExists = errors.New("row already exists")
	// ErrTooManyRows occurs when more rows than expected are returned.
	ErrTooManyRows = pgx.ErrTooManyRows
)

Functions

func Migrate

func Migrate(db *sql.DB, migrations fs.FS, direction MigrationDirection) (int, error)

Migrate the given database with the embedded migrations and direction.

func MigrateMax

func MigrateMax(db *sql.DB, migrations fs.FS, direction MigrationDirection, maxAmount int) (int, error)

MigrateMax migrates the given database with the embedded migrations and direction, will apply at most `max` migrations, pass 0 for no limit.

func NewStdlib

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

NewStdlib establishes a connection with a PostgreSQL database and returns a *sql.DB object.

Types

type CommandTag

type CommandTag = pgconn.CommandTag

CommandTag is the status text returned by PostgreSQL for a query.

type Config

type Config struct {
	Host     string `env:"HOST"`
	Port     string `env:"PORT"`
	User     string `env:"USER"`
	Password string `env:"PASSWORD"`
	Database string `env:"DATABASE"`
	Driver   string `env:"DRIVER"`

	Logger LoggerContract
}

Config contains the database configuration.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate checks that all mandatory configuration values are set.

type Connection

type Connection struct {
	*pgx.Conn
	*pgxscan.API
}

Connection defines a database connection. It exposes the exported functions of both embedded types. The connection is not concurrency-safe.

func New

func New(ctx context.Context, cfg Config) (*Connection, error)

New establishes a connection with a PostgreSQL database.

type Logger

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

Logger implements a database logger.

func NewLogger

func NewLogger(logger *log.Logger) *Logger

NewLogger returns a new database logger based on the given logger.

func (*Logger) Level

func (l *Logger) Level() tracelog.LogLevel

Level returns the minimum enabled log level.

func (*Logger) Log

func (l *Logger) Log(ctx context.Context, level tracelog.LogLevel, msg string, data map[string]any)

Log a message from the database package.

type LoggerContract

type LoggerContract interface {
	Log(ctx context.Context, level tracelog.LogLevel, msg string, data map[string]any)
	Level() tracelog.LogLevel
}

LoggerContract defines the logger interface used by the database implementation.

type MigrationDirection

type MigrationDirection = migrate.MigrationDirection

MigrationDirection defines the direction of the migration.

type Pool

type Pool struct {
	*pgxpool.Pool
	*pgxscan.API
}

Pool defines a connection pool. It exposes the exported functions of both embedded types. The pool is concurrency-safe.

func NewPool

func NewPool(ctx context.Context, cfg Config) (*Pool, error)

NewPool establishes a connection pool with a PostgreSQL database.

func (*Pool) Close

func (p *Pool) Close(_ context.Context) error

Close closes all connections in the pool and rejects future Acquire calls. Blocks until all connections are returned to pool and closed. Implement the same Close function signature to allow Pool and Connection to have the same function signatures.

type Querier

type Querier = pgxscan.Querier

Querier is something that pgxscan can query and get the pgx.Rows from. For example, it can be: *pgxpool.Pool, *pgx.Conn or pgx.Tx.

type Row

type Row = pgx.Row

Row is a convenience wrapper over Rows that is returned by QueryRow.

type Rows

type Rows = pgx.Rows

Rows is the result set returned from *Conn.Query. Rows must be closed before the *Conn can be used again. Rows are closed by explicitly calling Close().