superbasic

README

The superbasic SQL-Builder

superbasic.Compile compiles expressions into a template.

In addition, this package provides a set of functions that can be used to create expressions.

go get github.com/wroge/superbasic

// Expression represents a prepared statement.
type Expression interface {
	ToSQL() (string, []any, error)
}


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


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

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


search := superbasic.In("last", "Bush", "Clinton")
sort := "first"

query := superbasic.Append(
	superbasic.SQL("SELECT id, first, last FROM presidents"),
	superbasic.If(search != nil, superbasic.Compile(" WHERE ?", search)),
	superbasic.If(sort != "", superbasic.SQL(fmt.Sprintf(" ORDER BY %s", sort))),
)

fmt.Println(query.ToSQL())
// SELECT id, first, last FROM presidents WHERE last IN (?, ?) ORDER BY first
// [Bush Clinton]

Documentation

Index

• func ToPositional(placeholder string, expr Expression) (string, []any, error)
• type Expression
  • func And(expr ...Expression) Expression
  • func Append(expressions ...Expression) Expression
  • func Between(ident string, lower, higher any) Expression
  • func Cast(value any, as string) Expression
  • func Compile(template string, expressions ...Expression) Expression
  • func Equals(ident string, value any) Expression
  • func Greater(ident string, value any) Expression
  • func GreaterOrEquals(ident string, value any) Expression
  • func Idents(idents ...string) Expression
  • func If(condition bool, then Expression) Expression
  • func IfElse(condition bool, then, els Expression) Expression
  • func In(ident string, values ...any) Expression
  • func IsNotNull(ident string) Expression
  • func IsNull(ident string) Expression
  • func Join(sep string, expressions ...Expression) Expression
  • func Less(ident string, value any) Expression
  • func LessOrEquals(ident string, value any) Expression
  • func Like(ident string, value any) Expression
  • func Not(expr Expression) Expression
  • func NotBetween(ident string, lower, higher any) Expression
  • func NotEquals(ident string, value any) Expression
  • func NotIn(ident string, values ...any) Expression
  • func NotLike(ident string, value any) Expression
  • func Or(left, right Expression) Expression
  • func SQL(sql string, args ...any) Expression
  • func Value(a any) Expression
  • func Values(a ...any) Expression
• type ExpressionError
  • func (e ExpressionError) Error() string
  • func (e ExpressionError) ToSQL() (string, []any, error)
• type NumberOfArgumentsError
  • func (e NumberOfArgumentsError) Error() string
  • func (e NumberOfArgumentsError) ToSQL() (string, []any, error)

Functions

func ToPositional

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

Types

type Expression

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

Expression represents a prepared statement.

func And

func And(expr ...Expression) Expression

And returns a AND expression.

func Append

func Append(expressions ...Expression) Expression

Append expressions.

func Between

func Between(ident string, lower, higher any) Expression

Between returns a BETWEEN expression.

func Cast

func Cast(value any, as string) Expression

Cast returns a CAST expression.

func Compile

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

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

func Equals

func Equals(ident string, value any) Expression

Equals returns an expression with an '=' sign.

func Greater

func Greater(ident string, value any) Expression

Greater returns an expression with an '>' sign.

func GreaterOrEquals

func GreaterOrEquals(ident string, value any) Expression

GreaterOrEquals returns an expression with an '>=' sign.

func Idents

func Idents(idents ...string) Expression

Idents joins idents with ", " to an expression.

func If

func If(condition bool, then Expression) Expression

If returns an expression based on a condition. If false an empty expression is returned.

func IfElse

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

IfElse returns an expression based on a condition.

func In

func In(ident string, values ...any) Expression

In returns a IN expression.

func IsNotNull

func IsNotNull(ident string) Expression

IsNotNull returns a IS NOT NULL expression.

func IsNull

func IsNull(ident string) Expression

IsNull returns a IS NULL expression.

func Join

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

Join joins expressions by a separator.

func Less

func Less(ident string, value any) Expression

Less returns an expression with an '<' sign.

func LessOrEquals

func LessOrEquals(ident string, value any) Expression

LessOrEquals returns an expression with an '<=' sign.

func Like

func Like(ident string, value any) Expression

Like returns a LIKE expression.

func Not

func Not(expr Expression) Expression

Not returns a NOT expression.

func NotBetween

func NotBetween(ident string, lower, higher any) Expression

NotBetween returns a NOT BETWEEN expression.

func NotEquals

func NotEquals(ident string, value any) Expression

NotEquals returns an expression with an '<>' sign.

func NotIn

func NotIn(ident string, values ...any) Expression

NotIn returns a NOT IN expression.

func NotLike

func NotLike(ident string, value any) Expression

NotLike returns a NOT LIKE expression.

func Or

func Or(left, right Expression) Expression

Or returns a OR expression.

func SQL

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

SQL returns an expression.

func Value

func Value(a any) Expression

Value returns an expression with a placeholder.

func Values

func Values(a ...any) Expression

Values returns an expression with placeholders.

type ExpressionError

type ExpressionError struct{}

ExpressionError is returned if expressions are nil.

func (ExpressionError) Error

func (e ExpressionError) Error() string

func (ExpressionError) ToSQL

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

type NumberOfArgumentsError

type NumberOfArgumentsError struct{}

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

func (NumberOfArgumentsError) Error

func (e NumberOfArgumentsError) Error() string

func (NumberOfArgumentsError) ToSQL

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