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 a list of values into an SQL template...

expr := superbasic.Compile("INSERT INTO presidents (nr, first, last) VALUES ? RETURNING id", 
    []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("$", 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] 

or any other expression. Lists of expressions are always joined by ", ".

expr := superbasic.Compile("UPDATE presidents SET ? WHERE ?",
    []superbasic.Expression{
        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 that can be used 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]

The Query helper can be used as a reference to build your own expressions...

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

func (q Query) ToSQL() (string, []any, error) {
	return Join(" ",
		If(q.With != nil, Compile("WITH ?", q.With)),
		SQL("SELECT"),
		IfElse(q.Select != nil, q.Select, SQL("*")),
		If(q.From != nil, Compile("FROM ?", q.From)),
		If(q.Where != nil, Compile("WHERE ?", q.Where)),
		If(q.GroupBy != nil, Compile("GROUP BY ?", q.GroupBy)),
		If(q.Having != nil, Compile("HAVING ?", q.Having)),
		If(q.Having != nil, Compile("WINDOW ?", q.Window)),
		If(q.OrderBy != nil, Compile("ORDER BY ?", q.OrderBy)),
		If(q.Limit > 0, SQL(fmt.Sprintf("LIMIT %d", q.Limit))),
		If(q.Offset > 0, SQL(fmt.Sprintf("OFFSET %d", q.Offset))),
	).ToSQL()
}

Documentation

Index

• func ToPositional(placeholder string, expr Expression) (string, []any, error)
• type Compiler
  • func Compile(template string, expressions ...any) 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
• type ExpressionError
  • func (e ExpressionError) Error() string
  • func (e ExpressionError) Unwrap() error
• 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 (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 []any
}

func Compile

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

Compile takes a template with placeholders into which expressions can be compiled. []Expression is compiled to Join(", ", expr...). 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

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 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
}

func SQL

func SQL(sql string, args ...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)