superbasic

README

The superbasic SQL-Builder

superbasic.Compile compiles expressions into an SQL template and thus offers an alternative to conventional query builders.

type Expression interface { 
    ToSQL() (string, []any, error) 
}

Compile Expressions into SQL

You can compile any expression into an SQL template. Raw expressions can be created by superbasic.SQL.

expr := superbasic.Compile("INSERT INTO presidents (nr, first, last) VALUES ? RETURNING id",
	superbasic.Join(", ",
		superbasic.Values{46, "Joe", "Biden"},
		superbasic.Values{45, "Donald", "trump"},
		superbasic.Values{44, "Barack", "Obama"},
		superbasic.Values{43, "George W.", "Bush"},
		superbasic.Values{42, "Bill", "Clinton"},
		superbasic.Values{41, "George H. W.", "Bush"},
	),
)

fmt.Println(superbasic.ToPositional("$", expr))
// INSERT INTO presidents (nr, first, last) VALUES
// 		($1, $2, $3), ($4, $5, $6), ($7, $8, $9), ($10, $11, $12), ($13, $14, $15), ($16, $17, $18)
//		RETURNING id
// [46 Joe Biden 45 Donald trump 44 Barack Obama 43 George W. Bush 42 Bill Clinton 41 George H. W. Bush]

expr = superbasic.Compile("UPDATE presidents SET ? WHERE ?",
	superbasic.Join(", ",
		superbasic.SQL("first = ?", "Donald"),
		superbasic.SQL("last = ?", "Trump"),
	),
	superbasic.SQL("nr = ?", 45),
)

fmt.Println(expr.ToSQL())
// UPDATE presidents SET first = ?, last = ? WHERE nr = ?
// [Donald Trump 45]

Query

Additionally, there are Query, Insert, Update and Delete helpers to create expressions.

query := superbasic.Query{
	From: superbasic.SQL("presidents"),
	Where: superbasic.Compile("(? OR ?)",
		superbasic.SQL("last = ?", "Bush"),
		superbasic.SQL("nr >= ?", 45),
	),
	OrderBy: superbasic.SQL("nr"),
	Limit:   3,
}

fmt.Println(query.ToSQL())
// SELECT * FROM presidents WHERE (last = ? OR nr >= ?) ORDER BY nr LIMIT 3
// [Bush 44]

insert := superbasic.Insert{
	Into:    "presidents",
	Columns: []string{"nr", "first", "last"},
	Data: []superbasic.Values{
		{46, "Joe", "Biden"},
		{45, "Donald", "trump"},
		{44, "Barack", "Obama"},
		{43, "George W.", "Bush"},
		{42, "Bill", "Clinton"},
		{41, "George H. W.", "Bush"},
	},
}
fmt.Println(superbasic.ToPositional("$", superbasic.Compile("? RETURNING id", insert)))
// INSERT INTO presidents (nr, first, last) VALUES
// 		($1, $2, $3), ($4, $5, $6), ($7, $8, $9), ($10, $11, $12), ($13, $14, $15), ($16, $17, $18)
//		RETURNING id
// [46 Joe Biden 45 Donald trump 44 Barack Obama 43 George W. Bush 42 Bill Clinton 41 George H. W. Bush]

Documentation

Index

• func ToPositional(placeholder string, expr Expression) (string, []any, error)
• type Compiler
  • func Compile(template string, expressions ...Expression) Compiler
  • func (c Compiler) ToSQL() (string, []any, error)
• type Delete
  • func (d Delete) ToSQL() (string, []any, error)
• type Expression
  • func If(condition bool, then Expression) Expression
  • func IfElse(condition bool, then, els Expression) Expression
  • func Slice[T Expression](s []T) []Expression
• type ExpressionError
  • func (e ExpressionError) Error() string
  • func (e ExpressionError) Unwrap() error
• type ExpressionIndexError
  • func (e ExpressionIndexError) Error() string
• type Insert
  • func (i Insert) ToSQL() (string, []any, error)
• type Joiner
  • func Append(expressions ...Expression) Joiner
  • func Join(sep string, expressions ...Expression) Joiner
  • func (j Joiner) ToSQL() (string, []any, error)
• type NumberOfArgumentsError
  • func (e NumberOfArgumentsError) Error() string
• type Query
  • func (q Query) ToSQL() (string, []any, error)
• type Raw
  • func SQL(sql string, args ...any) Raw
  • func Value(a any) Raw
  • func (r Raw) ToSQL() (string, []any, error)
• type Update
  • func (u Update) ToSQL() (string, []any, error)
• type Values
  • func (v Values) ToSQL() (string, []any, error)

Functions

func ToPositional

func ToPositional(placeholder string, expr Expression) (string, []any, error)

Types

type Compiler

type Compiler struct {
	Template    string
	Expressions []Expression
}

func Compile

func Compile(template string, expressions ...Expression) Compiler

Compile takes a template with placeholders into which expressions can be compiled. Escape '?' by using '??'.

func (Compiler) ToSQL

func (c Compiler) ToSQL() (string, []any, error)

type Delete

type Delete struct {
	From  string
	Where Expression
}

func (Delete) ToSQL

func (d Delete) ToSQL() (string, []any, error)

type Expression

type Expression interface {
	ToSQL() (string, []any, error)
}

func If

func If(condition bool, then Expression) Expression

func IfElse

func IfElse(condition bool, then, els Expression) Expression

func Slice

func Slice[T Expression](s []T) []Expression

Slice creates a slice of expressions from any slice of expressions. This function will exists util there are better alternatives.

type ExpressionError

type ExpressionError struct {
	Err error
}

ExpressionError is returned if expressions are nil.

func (ExpressionError) Error

func (e ExpressionError) Error() string

func (ExpressionError) Unwrap

func (e ExpressionError) Unwrap() error

type ExpressionIndexError

type ExpressionIndexError struct {
	Index int
}

func (ExpressionIndexError) Error

func (e ExpressionIndexError) Error() string

type Insert

type Insert struct {
	Into    string
	Columns []string
	Data    []Values
}

func (Insert) ToSQL

func (i Insert) ToSQL() (string, []any, error)

type Joiner

type Joiner struct {
	Sep         string
	Expressions []Expression
}

func Append

func Append(expressions ...Expression) Joiner

func Join

func Join(sep string, expressions ...Expression) Joiner

func (Joiner) ToSQL

func (j Joiner) ToSQL() (string, []any, error)

type NumberOfArgumentsError

type NumberOfArgumentsError struct {
	Got, Want int
}

NumberOfArgumentsError is returned if arguments doesn't match the number of placeholders.

func (NumberOfArgumentsError) Error

func (e NumberOfArgumentsError) Error() string

type Query

type Query struct {
	With    Expression
	Select  Expression
	From    Expression
	Where   Expression
	GroupBy Expression
	Having  Expression
	Window  Expression
	OrderBy Expression
	Limit   uint64
	Offset  uint64
}

func (Query) ToSQL

func (q Query) ToSQL() (string, []any, error)

type Raw

type Raw struct {
	SQL  string
	Args []any
	Err  error
}

func SQL

func SQL(sql string, args ...any) Raw

func Value

func Value(a any) Raw

func (Raw) ToSQL

func (r Raw) ToSQL() (string, []any, error)

type Update

type Update struct {
	Table string
	Sets  []Expression
	Where Expression
}

func (Update) ToSQL

func (u Update) ToSQL() (string, []any, error)

type Values

type Values []any

func (Values) ToSQL

func (v Values) ToSQL() (string, []any, error)