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 Column[M Model](column string) string
• func ColumnErr[M Model](column string) (string, error)
• func Columns[M Model]() []string
• func NoOp() (string, []driver.Value, error)
• func TableName[M Model]() string
• type JoinType
• type Model
• type SqldFn
  • func And(ops ...SqldFn) SqldFn
  • func Asc(columnExpr *string) SqldFn
  • func Block(block string) SqldFn
  • func ColumnEq(firstColumn string, secondColumn 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, tableName string, op SqldFn) SqldFn
  • func LeftJoin(tableName string, 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(tableName string, op SqldFn) SqldFn
  • func Select(columns ...string) 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 select statement")

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

Functions

func Column

func Column[M Model](column string) string

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

func ColumnErr

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

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

func Columns

func Columns[M Model]() []string

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

func NoOp

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

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 Asc

func Asc(columnExpr *string) SqldFn

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

func Block

func Block(block string) SqldFn

Block builds a callback that just returns the provided strings. Use it for the "static" parts of your query, like SELECT and JOIN statements.

sqld.Block(`
	SELECT
		name,
		pizzas
	FROM Table`,
)

func ColumnEq

func ColumnEq(firstColumn string, secondColumn string) SqldFn

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

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, tableName string, op SqldFn) SqldFn

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

func LeftJoin

func LeftJoin(tableName string, 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(tableName string, op SqldFn) SqldFn

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

func Select

func Select(columns ...string) SqldFn

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

sqld.Select(
	"name",
	"pizzas",
)

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),
		),
	),
)