sqld

README

sqld

A Go library to build and manage dynamic queries. No external dependencies. Slightly inspired by Drizzle ORM

Scope of the project

The scope of sqld is to provide an easy way to organize your dynamic queries in re-usable components, not to validate said queries. I suggest to use other tools like SQLParser and a lot of e2e tests!

Usage

query := sqld.New(
	sqld.Block(`
		SELECT
			name,
			pizzas
		FROM Table`,
	),
	sqld.Where(
		sqld.And( 
			sqld.IfNotNil(filters.Name,
				sqld.Eq("name", filters.Name),
			),
			sqld.IfNotEmpty(filters.Pizzas,
				sqld.In("pizzas", filters.Pizzas),
			),
		),
	),
	sqld.OrderBy(
		sqld.IfNotNil(filters.OrderBy,
			sqld.Desc(filters.OrderBy),
		),
	),
)

s, args, err := query()

Glossary

• Operators: callbacks that have this signature, used to build various parts of the query
• Statements: major "blocks" of the query, like a whole WHERE statement with all its conditions
• Conditionals: functions that return different operators depending on the inputs (usually boolean checks). Check this file

Customize

You can provide your own operators: every function (anonymous or not) that has this signature can be used by the library.

Check here for the built-in errors.

Documentation

Index

• Constants
• Variables
• func NoOp() (string, []driver.Value, error)
• func TableColumn[M Model](column string) string
• func TableColumnErr[M Model](column string) (string, error)
• func TableColumns[M Model]() []string
• func TableName[M Model]() string
• type JoinType
• type Model
• type SqldFn
  • func And(ops ...SqldFn) SqldFn
  • func As(op SqldFn, aliasName string) SqldFn
  • func Asc(columnExpr *string) SqldFn
  • func ColumnEq(firstColumn string, secondColumn string) SqldFn
  • func Columns(columns ...string) SqldFn
  • func Desc(columnExpr *string) SqldFn
  • func Eq[T driver.Value](columnExpr string, val *T) SqldFn
  • func From(tableName string) SqldFn
  • func Having(ops ...SqldFn) SqldFn
  • func If(pred func() bool, op SqldFn) SqldFn
  • func IfElse(pred func() bool, trueFn SqldFn, falseFn SqldFn) SqldFn
  • func IfEmpty[T driver.Value](vals []T, op SqldFn) SqldFn
  • func IfEmptyElse[T driver.Value](vals []T, trueFn SqldFn, falseFn SqldFn) SqldFn
  • func IfNil[T driver.Value](val *T, op SqldFn) SqldFn
  • func IfNilElse[T driver.Value](val *T, trueFn SqldFn, falseFn SqldFn) SqldFn
  • func IfNotEmpty[T driver.Value](vals []T, op SqldFn) SqldFn
  • func IfNotEmptyElse[T driver.Value](vals []T, trueFn SqldFn, falseFn SqldFn) SqldFn
  • func IfNotNil[T driver.Value](val *T, op SqldFn) SqldFn
  • func IfNotNilElse[T driver.Value](val *T, trueFn SqldFn, falseFn SqldFn) SqldFn
  • func In[T driver.Value](columnExpr string, vals []T) SqldFn
  • func Join(joinType JoinType, subject SqldFn, op SqldFn) SqldFn
  • func Just(s string) SqldFn
  • func LeftJoin(subject SqldFn, op SqldFn) SqldFn
  • func New(ops ...SqldFn) SqldFn
  • func Not(op SqldFn) SqldFn
  • func Null(columnExpr string) SqldFn
  • func Or(ops ...SqldFn) SqldFn
  • func OrderBy(ops ...SqldFn) SqldFn
  • func RightJoin(subject SqldFn, op SqldFn) SqldFn
  • func Select(ops ...SqldFn) SqldFn
  • func Where(ops ...SqldFn) SqldFn

Constants

const (
	LEFT_JOIN        = "LEFT"
	RIGHT_JOIN       = "RIGHT"
	INNER_JOIN       = "INNER"
	CROSS_JOIN       = "CROSS"
	FULL_JOIN        = "FULL"
	LEFT_OUTER_JOIN  = "LEFT OUTER"
	RIGHT_OUTER_JOIN = "RIGHT OUTER"
	INNER_OUTER_JOIN = "INNER OUTER"
	CROSS_OUTER_JOIN = "CROSS OUTER"
	FULL_OUTER_JOIN  = "FULL OUTER"
)

Variables

var ErrArgNotSlice = errors.New("argument is not a slice")

var ErrEmptySlice = errors.New("slice is empty")

var ErrNilColumnExpr = errors.New("column expression is nil")

var ErrNilVal = errors.New("value is nil")

var ErrNoColumns = errors.New("no columns in statement")

var ErrNoOps = errors.New("operations slice is empty")

Functions

func NoOp

func NoOp() (string, []driver.Value, error)

func TableColumn

func TableColumn[M Model](column string) string

TableColumn returns a combination of `Model.TableName()` and the provided column. Panics if the column is not present in the model

func TableColumnErr

func TableColumnErr[M Model](column string) (string, error)

TableColumnErr returns a combination of `Model.TableName()` and the provided column. Returns error if the column is not present in the model

func TableColumns

func TableColumns[M Model]() []string

TableColumns extracts a list of columns from a `Model`, using sqlx `db` tags and falling back on field names

func TableName

func TableName[M Model]() string

TableName is a generic proxy for `Model.TableName()`

Types

type JoinType

type JoinType string

type Model

type Model interface {
	TableName() string
}

type SqldFn

type SqldFn func() (string, []driver.Value, error)

SqldFn is the type describing all callbacks used in the library.

func And

func And(ops ...SqldFn) SqldFn

And builds a callback combining all the operators with AND conditions.

sqld.And(
	sqld.IfNotNil(filters.Name,
		sqld.Eq("name", filters.Name),
	),
	sqld.IfNotEmpty(filters.Pizzas,
		sqld.In("pizzas", filters.Pizzas),
	),
)

func As

func As(op SqldFn, aliasName string) SqldFn

As builds a callback that returns an alias

func Asc

func Asc(columnExpr *string) SqldFn

Asc builds a callback used to specify the sorting in `OrderBy()`.

func ColumnEq

func ColumnEq(firstColumn string, secondColumn string) SqldFn

ColumnEq builds a callback that returns a comparison statement between two columns

func Columns

func Columns(columns ...string) SqldFn

Columns builds a callback that returns a list of columns, comma-separated

func Desc

func Desc(columnExpr *string) SqldFn

Desc builds a callback used to specify the sorting in `OrderBy()`.

func Eq

func Eq[T driver.Value](columnExpr string, val *T) SqldFn

Eq builds a callback that compares a column with the provided value.

sqld.Eq("name", filters.Name)

func From

func From(tableName string) SqldFn

From builds a callback that just returns a FROM statement with the provided table

func Having

func Having(ops ...SqldFn) SqldFn

Having builds a callback combining all the operators in a HAVING statement.

sqld.Having(
	sqld.And(
		sqld.IfNotNil(filters.Name,
			sqld.Eq("name", filters.Name),
		),
		sqld.IfNotEmpty(filters.Pizzas,
			sqld.In("pizzas", filters.Pizzas),
		),
	),
)

func If

func If(pred func() bool, op SqldFn) SqldFn

func IfElse

func IfElse(pred func() bool, trueFn SqldFn, falseFn SqldFn) SqldFn

func IfEmpty

func IfEmpty[T driver.Value](vals []T, op SqldFn) SqldFn

func IfEmptyElse

func IfEmptyElse[T driver.Value](vals []T, trueFn SqldFn, falseFn SqldFn) SqldFn

func IfNil

func IfNil[T driver.Value](val *T, op SqldFn) SqldFn

func IfNilElse

func IfNilElse[T driver.Value](val *T, trueFn SqldFn, falseFn SqldFn) SqldFn

func IfNotEmpty

func IfNotEmpty[T driver.Value](vals []T, op SqldFn) SqldFn

func IfNotEmptyElse

func IfNotEmptyElse[T driver.Value](vals []T, trueFn SqldFn, falseFn SqldFn) SqldFn

func IfNotNil

func IfNotNil[T driver.Value](val *T, op SqldFn) SqldFn

func IfNotNilElse

func IfNotNilElse[T driver.Value](val *T, trueFn SqldFn, falseFn SqldFn) SqldFn

func In

func In[T driver.Value](columnExpr string, vals []T) SqldFn

In builds a callback that checks if a column value is contained in the provided slice of values.

sqld.In("pizzas", filters.Pizzas)

func Join

func Join(joinType JoinType, subject SqldFn, op SqldFn) SqldFn

Join builds a callback that returns a JOIN statement of the provided type with the desired subject, with a condition callback

func Just

func Just(s string) SqldFn

Just returns a callback that just returns the provided string

func LeftJoin

func LeftJoin(subject SqldFn, op SqldFn) SqldFn

LeftJoin is a shortcut for `Join()` with `LEFT_JOIN` type

func New

func New(ops ...SqldFn) SqldFn

New builds a `SqldFn` callback combining the provided operators.

Example usage:

const query := sqld.New(
	sqld.Block(`
		SELECT
			name,
			pizzas
		FROM Table`,
	),
	sqld.Where(
		sqld.And(
			sqld.IfNotNil(filters.Name,
				sqld.Eq("name", filters.Name),
			),
			sqld.IfNotEmpty(filters.Pizzas,
				sqld.In("pizzas", filters.Pizzas),
			),
		),
	),
	sqld.OrderBy(
		sqld.IfNotNil(filters.OrderBy,
			sqld.Desc(filters.OrderBy),
		),
	),
)

func Not

func Not(op SqldFn) SqldFn

Not negates the provided operator.

func Null

func Null(columnExpr string) SqldFn

Eq builds a callback that checks if a column is NULL.

sqld.Null("name")

func Or

func Or(ops ...SqldFn) SqldFn

Or builds a callback combining all the operators with OR conditions.

sqld.Or(
	sqld.IfNotNil(filters.Name,
		sqld.Eq("name", filters.Name),
	),
	sqld.IfNotEmpty(filters.Pizzas,
		sqld.In("pizzas", filters.Pizzas),
	),
)

func OrderBy

func OrderBy(ops ...SqldFn) SqldFn

OrderBy builds a callback combining all the operators in a ORDER BY statement.

sqld.OrderBy(
	sqld.IfNotNil(filters.OrderBy,
		sqld.Desc(filters.OrderBy),
	),
)

func RightJoin

func RightJoin(subject SqldFn, op SqldFn) SqldFn

RightJoin is a shortcut for `Join()` with `RIGHT_JOIN` type

func Select

func Select(ops ...SqldFn) SqldFn

Select builds a callback that returns a SELECT statement with a concatenation of the provided operators.

func Where

func Where(ops ...SqldFn) SqldFn

Where builds a callback combining all the operators in a WHERE statement.

sqld.Where(
	sqld.And(
		sqld.IfNotNil(filters.Name,
			sqld.Eq("name", filters.Name),
		),
		sqld.IfNotEmpty(filters.Pizzas,
			sqld.In("pizzas", filters.Pizzas),
		),
	),
)