builder

Documentation

Index

• Variables
• func Merge[TParent, TChildren any](results KeyedResult[TParent], ...) storage.Mapper[TChildren]
• type Executor
• type KeyedResult
  • func (r KeyedResult[T]) Data() []T
  • func (r KeyedResult[T]) Keys() []string
• type QueryBuilder
  • func Command(sql string, args ...any) QueryBuilder[any, storage.Scanner]
  • func Insert(table string, values Values) QueryBuilder[any, storage.Scanner]
  • func Query[T any](sql string, args ...any) QueryBuilder[T, storage.Scanner]
  • func QueryEx[T any, TScanner storage.Scanner](sql string, args ...any) QueryBuilder[T, TScanner]
  • func Select[T any](fields ...string) QueryBuilder[T, storage.Scanner]
  • func Update(table string, values Values) QueryBuilder[any, storage.Scanner]
• type ScannerBuilder
• type ScannerEx
• 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.KeyedMapper[TChildren, storage.Scanner],
	merger storage.Merger[TParent, TChildren],
) storage.Mapper[TChildren]

Merge the results of the query with given data. The mapper MUST returns the key representing the parent entity identity.

With the retrieved key, it will merge the result by calling the merger func.

Types

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]) Data

func (r KeyedResult[T]) Data() []T

func (KeyedResult[T]) Keys

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

Keys returns the list of keys contained in this dataset.

type QueryBuilder

type QueryBuilder[T any, TScanner storage.Scanner] interface {
	// Append a raw SQL statement to the builder with the optional arguments.
	F(string, ...any) QueryBuilder[T, TScanner]
	// Apply one or multiple statements to this builder.
	S(...Statement) QueryBuilder[T, TScanner]

	// Returns the SQL query generated
	String() string
	// Executes the query and returns all results
	All(Executor, context.Context, storage.Mapper[T]) ([]T, error)
	// Returns a paginated data result set.
	Paginate(Executor, context.Context, storage.Mapper[T], int) (storage.Paginated[T], error)
	// Same as All but fetch related data using a custom scanner.
	AllEx(Executor, context.Context, ScannerBuilder[T, TScanner], storage.KeyedMapper[T, TScanner]) ([]T, error)
	// Executes the query and returns the first matching result
	One(Executor, context.Context, storage.Mapper[T]) (T, error)
	// Same as One but fetch related data using a custom scanner.
	OneEx(Executor, context.Context, ScannerBuilder[T, TScanner], storage.KeyedMapper[T, TScanner]) (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, storage.Scanner]

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, storage.Scanner]

Builds a new query for an INSERT statement.

func Query

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

Builds up a new query.

func QueryEx

func QueryEx[T any, TScanner storage.Scanner](sql string, args ...any) QueryBuilder[T, TScanner]

Builds up a new query with a custom scanner needed to retrieve relational data.

func Select

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

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, storage.Scanner]

Builds a new query for an UPDATE statement.

type ScannerBuilder

type ScannerBuilder[T any, TScanner storage.Scanner] func(Executor) ScannerEx[T, TScanner]

Function to build a custom scanner for a given entity type.

type ScannerEx

type ScannerEx[T any, TConcreteScanner storage.Scanner] interface {
	storage.Scanner
	// Extend the given scanner to handle relationships.
	Contextualize(storage.Scanner) TConcreteScanner
	// Fetch related resources for the given entities.
	Finalize(context.Context, KeyedResult[T]) ([]T, error)
}

Scanner interface to handle entities with relations and to bulk queries.

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