libdal

Documentation

Overview

Package libdal provides common types and functions for domain-specific DALs.

In particular, common error types and error handling function for all domain-specific DALs, e.g. controller DAL and configuration DAL, which all connect to the same underlying DB and maintain the same interface guarantees

Index

• Variables
• func IsNotFound(err error) bool
• func TranslatePGError(err error) error
• type Connection
• type Handle
  • func New[T any](sql Connection, fn MakeWithHandle[T]) *Handle[T]
  • func (h *Handle[T]) Adopt(tx Connection) *T
  • func (h *Handle[T]) Begin(ctx context.Context) (*T, error)
  • func (h *Handle[T]) Commit(ctx context.Context) error
  • func (h *Handle[T]) CommitOrRollback(ctx context.Context, err *error)
  • func (h *Handle[T]) Rollback(ctx context.Context) error
• type MakeWithHandle

Variables

var (
	// ErrConflict is returned by select methods in the DAL when a resource already exists.
	//
	// Its use will be documented in the corresponding methods.
	ErrConflict = errors.New("conflict")
	// ErrNotFound is returned by select methods in the DAL when no results are found.
	ErrNotFound = errors.New("not found")
	// ErrConstraint is returned by select methods in the DAL when a constraint is violated.
	ErrConstraint = errors.New("constraint violation")
)

Functions

func IsNotFound

func IsNotFound(err error) bool

func TranslatePGError

func TranslatePGError(err error) error

Types

type Connection

type Connection interface {
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row
}

Connection is a common interface for *sql.DB and *sql.Tx.

type Handle

type Handle[T any] struct {
	Connection Connection

	Make MakeWithHandle[T]
	// contains filtered or unexported fields
}

Handle is a wrapper around a database connection that can be embedded within a struct to provide access to a database connection and methods for managing transactions.

func New

func New[T any](sql Connection, fn MakeWithHandle[T]) *Handle[T]

New creates a new Handle

func (*Handle[T]) Adopt

func (h *Handle[T]) Adopt(tx Connection) *T

Adopt creates a new Handle with the given transaction.

TODO: This needs to be removed - DALs should not be shared.

func (*Handle[T]) Begin

func (h *Handle[T]) Begin(ctx context.Context) (*T, error)

Begin creates a new transaction or increments the transaction counter if the handle is already in a transaction.

In all cases a new handle is returned.

func (*Handle[T]) Commit

func (h *Handle[T]) Commit(ctx context.Context) error

Commit the transaction or savepoint.

func (*Handle[T]) CommitOrRollback

func (h *Handle[T]) CommitOrRollback(ctx context.Context, err *error)

CommitOrRollback commits the transaction if err is nil, otherwise rolls it back.

Use it in a defer like so, particularly taking note of named return value `(err error)`. Without this it will not work.

func (d *DAL) SomeMethod() (err error) {
	tx, err := d.Begin()
	if err != nil { return err }
	defer tx.CommitOrRollback(&err)
	// ...
	return nil
}

func (*Handle[T]) Rollback

func (h *Handle[T]) Rollback(ctx context.Context) error

Rollback the transaction or savepoint.

type MakeWithHandle

type MakeWithHandle[T any] func(*Handle[T]) *T

MakeWithHandle is a function that can be used to create a new T with a SQLHandle.