superbasic

README

The superbasic SQL-Builder

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

To scan rows to types, i recommend wroge/scan.

Have a look at wroge/esperanto as well. It is a database access layer that can help you better organize your queries.

package main

import (
	"fmt"

	"github.com/wroge/superbasic"
)

func main() {
	// 1. CREATE SCHEMA

	create := superbasic.Compile("CREATE TABLE presidents (\n\t?\n)",
		superbasic.Join(",\n\t",
			superbasic.SQL("nr SERIAL PRIMARY KEY"),
			superbasic.SQL("first TEXT NOT NULL"),
			superbasic.SQL("last TEXT NOT NULL"),
		),
	)

	fmt.Println(create.ToSQL())
	// CREATE TABLE presidents (
	//	nr SERIAL PRIMARY KEY,
	//	first TEXT NOT NULL,
	//	last TEXT NOT NULL
	// )

	// 2. INSERT

	insert := superbasic.Join(" ",
		superbasic.SQL("INSERT INTO presidents (first, last)"),
		superbasic.Compile("VALUES ?",
			superbasic.Join(", ",
				superbasic.Map(presidents,
					func(_ int, president President) superbasic.Expression {
						return superbasic.Values{president.First, president.Last}
					})...,
			),
		),
		superbasic.SQL("RETURNING nr"),
	)

	fmt.Println(superbasic.Finalize("$%d", insert))
	// INSERT INTO presidents (first, last) VALUES ($1, $2), ($3, $4) RETURNING nr [George Washington John Adams]
}

type President struct {
	First string
	Last  string
}

var presidents = []President{
	{"George", "Washington"},
	{"John", "Adams"},
	// {"Thomas", "Jefferson"},
	// {"James", "Madison"},
	// {"James", "Monroe"},
	// {"John Quincy", "Adams"},
	// {"Andrew", "Jackson"},
	// {"Martin", "Van Buren"},
	// {"William Henry", "Harrison"},
	// {"John", "Tyler"},
	// {"James K.", "Polk"},
	// {"Zachary", "Taylor"},
	// {"Millard", "Fillmore"},
	// {"Franklin", "Pierce"},
	// {"James", "Buchanan"},
	// {"Abraham", "Lincoln"},
	// {"Andrew", "Johnson"},
	// {"Ulysses S.", "Grant"},
	// {"Rutherford B.", "Hayes"},
	// {"James A.", "Garfield"},
	// {"Chester A.", "Arthur"},
	// {"Grover", "Cleveland"},
	// {"Benjamin", "Harrison"},
	// {"Grover", "Cleveland"},
	// {"William", "McKinley"},
	// {"Theodore", "Roosevelt"},
	// {"William Howard", "Taft"},
	// {"Woodrow", "Wilson"},
	// {"Warren G.", "Harding"},
	// {"Calvin", "Coolidge"},
	// {"Herbert", "Hoover"},
	// {"Franklin D.", "Roosevelt"},
	// {"Harry S.", "Truman"},
	// {"Dwight D.", "Eisenhower"},
	// {"John F.", "Kennedy"},
	// {"Lyndon B.", "Johnson"},
	// {"Richard", "Nixon"},
	// {"Gerald", "Ford"},
	// {"Jimmy", "Carter"},
	// {"Ronald", "Reagan"},
	// {"George H. W.", "Bush"},
	// {"Bill", "Clinton"},
	// {"George W.", "Bush"},
	// {"Barack", "Obama"},
	// {"Donald", "Trump"},
	// {"Joe", "Biden"},
}

Documentation

Index

• func Finalize(placeholder string, expression Expression) (string, []any, error)
• func Map[From any, To any](from []From, mapper func(int, From) To) []To
• func Replace(placeholder string, sql string) (string, int)
• type Caser
  • func Case[T any](value T, then Expression) Caser[T]
• type Compiler
  • func Compile(template string, expressions ...Expression) Compiler
  • func (c Compiler) ToSQL() (string, []any, error)
• type Expression
  • func If(condition bool, then Expression) Expression
  • func IfElse(condition bool, then, els Expression) Expression
  • func Switch[T comparable](value T, cases ...Caser[T]) 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 Map

func Map[From any, To any](from []From, mapper func(int, From) To) []To

Map is a generic function for mapping one slice to another slice. It is useful for creating a slice of expressions as input to the join function.

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 Caser

type Caser[T any] struct {
	Value T
	Then  Expression
}

func Case

func Case[T any](value T, then Expression) Caser[T]

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

func Switch[T comparable](value T, cases ...Caser[T]) 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)