builder

Documentation

Index

• Variables
• func Merge[TParent, TChildren any](results KeyedResult[TParent], mapper storage.Mapper[TChildren], ...) storage.Mapper[TChildren]
• type Dataloader
  • func NewDataloader[T any](extractor func(T) string, ...) Dataloader[T]
• type Executor
• type KeyedResult
  • func (r KeyedResult[T]) Keys() []string
• type KeysMapping
• type QueryBuilder
  • func Command(sql string, args ...any) QueryBuilder[any]
  • func Insert(table string, values Values) QueryBuilder[any]
  • func Query[T any](sql string, args ...any) QueryBuilder[T]
  • func Select[T any](fields ...string) QueryBuilder[T]
  • func Update(table string, values Values) QueryBuilder[any]
• type Statement
  • func Array[T any](prefix string, values []T) Statement
  • func Maybe[T any](value monad.Maybe[T], fn func(T) (string, []any)) Statement
  • func MaybeValue[T any](value monad.Maybe[T], sql string) Statement
• type Values

Variables

var ErrPaginationNotSupported = errors.New("pagination not supported for this query. Did you forget to build the query using the Select function?")

Functions

func Merge

func Merge[TParent, TChildren any](
	results KeyedResult[TParent],
	mapper storage.Mapper[TChildren],
	merger storage.Merger[TParent, TChildren],
) storage.Mapper[TChildren]

Map TChild entities and merge them in a TParent entity using the key/index mapping given by the KeyedResult.

The mapper given to this function SHOULD NOT scan the first column of the result set because this function will do it and consider the first scanned value to be the key of the TParent entity. It means that you should always include the TParent key as the first column when retrieving related entities.

Types

type Dataloader

type Dataloader[T any] interface {
	ExtractKey(T) string                                   // Extract the key from the parent data. Will be given to the Fetch function afterwards.
	Fetch(Executor, context.Context, KeyedResult[T]) error // Fetch related data represented by this dataloader.
}

Represents an element which can fetch additional data from a T parent entity. Dataloaders will be called with a list of keys to fetch as a whole to avoid N+1 queries.

func NewDataloader

func NewDataloader[T any](
	extractor func(T) string,
	fetcher func(Executor, context.Context, KeyedResult[T]) error,
) Dataloader[T]

Builds up a new dataloader.

type Executor

type Executor interface {
	ExecContext(context.Context, string, ...any) (sql.Result, error)
	QueryContext(context.Context, string, ...any) (*sql.Rows, error)
	QueryRowContext(context.Context, string, ...any) *sql.Row
}

Element which could execute queries on a database (direct connection or current transaction).

type KeyedResult

type KeyedResult[T any] struct {
	// contains filtered or unexported fields
}

Represents a key indexed set of data.

func (KeyedResult[T]) Keys

func (r KeyedResult[T]) Keys() []string

Keys returns the list of keys contained in this dataset.

type KeysMapping

type KeysMapping map[string]int

type QueryBuilder

type QueryBuilder[T any] interface {
	// F for format, append a raw SQL statement to the builder with the optional arguments.
	F(string, ...any) QueryBuilder[T]
	// S for Statement, apply one or multiple statements to this builder.
	S(...Statement) QueryBuilder[T]

	// Returns the SQL query generated
	String() string

	// Executes the query and returns all results
	All(Executor, context.Context, storage.Mapper[T], ...Dataloader[T]) ([]T, error)
	// Executes the query and returns the first matching result
	One(Executor, context.Context, storage.Mapper[T], ...Dataloader[T]) (T, error)
	// Returns a paginated data result set.
	Paginate(Executor, context.Context, storage.Mapper[T], int, ...Dataloader[T]) (storage.Paginated[T], error)

	// Same as One but extract a primitive value by using a simple generic scanner
	Extract(Executor, context.Context) (T, error)
	// Executes the query without scanning the result.
	Exec(Executor, context.Context) error
}

Query builder result used to interact with the database.

func Command

func Command(sql string, args ...any) QueryBuilder[any]

Builds a new query without specifying a return type. Useful for commands such as INSERT, UPDATE and DELETE where no results are expected.

func Insert

func Insert(table string, values Values) QueryBuilder[any]

Builds a new query for an INSERT statement.

func Query

func Query[T any](sql string, args ...any) QueryBuilder[T]

Builds up a new query.

func Select

func Select[T any](fields ...string) QueryBuilder[T]

Starts a SELECT query with pagination handling. Giving fields with this function will make it possible to retrieve the total element count when calling .Paginate. Without this, pagination could not work.

func Update

func Update(table string, values Values) QueryBuilder[any]

Builds a new query for an UPDATE statement.

type Statement

type Statement func(sqlBuilder)

Statement function to append an SQL statement to a builder.

func Array

func Array[T any](prefix string, values []T) Statement

Generates an IN clause from a list of values. Just provide the prefix such as "name IN" and the list of values and it will append (?, ?, ?) to the prefix based on what's in the list.

func Maybe

func Maybe[T any](value monad.Maybe[T], fn func(T) (string, []any)) Statement

Maybe is a helper function that will only append the SQL statement and arguments if the monad value is set. This is useful for optional fields in a query.

func MaybeValue

func MaybeValue[T any](value monad.Maybe[T], sql string) Statement

Shortcut to append the monad value to the query if it's set.

type Values

type Values map[string]any

Tiny shortcut to a map of field name => field value