superbasic

README

The superbasic SQL-Builder

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

If you need support for multiple SQL dialects, take a look at wroge/esperanto.

package main

import (
	"fmt"

	"github.com/wroge/superbasic"
)

func main() {
	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.Finalize("$%d", 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]
}

Documentation

Index

• func Finalize(placeholder string, expression Expression) (string, []any, error)
• func Replace(placeholder string, sql string) (string, int)
• type Compiler
  • func Compile(template string, expressions ...Expression) Compiler
  • func (c Compiler) ToSQL() (string, []any, error)
• type Error
  • func (e Error) Error() string
  • func (e Error) ToSQL() (string, []any, error)
  • func (e Error) Unwrap() 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
• 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 Raw
  • func SQL(sql string, args ...any) Raw
  • func Value(a any) Raw
  • func (r Raw) ToSQL() (string, []any, error)
• type Values
  • func (v Values) ToSQL() (string, []any, error)

Functions

func Finalize

func Finalize(placeholder string, expression Expression) (string, []any, error)

Finalize takes a static placeholder like '?' or a positional placeholder containing '%d'. Escaped placeholders ('??') are replaced to '?' when placeholder argument is not '?'.

func Replace

func Replace(placeholder string, sql string) (string, int)

Replace takes a static placeholder like '?' or a positional placeholder containing '%d'. Escaped placeholders ('??') are replaced to '?' when placeholder argument is not '?'.

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 Error

type Error struct {
	Err error
}

Error wraps any error in this package and can be used to create an Expression.

func (Error) Error

func (e Error) Error() string

func (Error) ToSQL

func (e Error) ToSQL() (string, []any, error)

func (Error) Unwrap

func (e Error) Unwrap() 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 {
	Position int
}

ExpressionError is returned by the Compile Expression, if an expression is nil.

func (ExpressionError) Error

func (e ExpressionError) Error() string

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 {
	SQL                     string
	Placeholders, Arguments int
}

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

func (NumberOfArgumentsError) Error

func (e NumberOfArgumentsError) Error() string

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 Values

type Values []any

func (Values) ToSQL

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