litsql

README

litsql - Literal SQL query builder

litsql is a Golang string concatenation library disguised as an SQL query builder.

Ok, it really is an SQL query builder, but it aims to be an easier-to-use replacement for raw SQL strings.

Each litsql statement must be directly related to an SQL output, including whitespace, which must be obvious to the user of the library.

The library will do:

• ensure clause ordering

The library won't do:

• prevent invalid SQL from being output
• automatic quoting

Installation

go get -u github.com/rrgmc/litsql

Reference

This library is heavily inspired by the excellent Bob Go SQL Access Toolkit. Its base ideas and some of its implementations where used to build this library's interface.

The biggest difference is that Bob is not only a query builder, but an ORM, so the query builder part must be much more complex to be able to tackle multiple jobs. In some parts it is hard to directly relate what SQL will be generated, and it encourages using Go to code SQL expressions, which this library heavily discourages.

Author

Rangel Reale (rangelreale@gmail.com)

Documentation

Index

• func Express(w Writer, d Dialect, start int, e Expression) ([]any, error)
• func ExpressIf(w Writer, d Dialect, start int, e Expression, cond bool, ...) ([]any, error)
• func ExpressSlice(w Writer, d Dialect, start int, expressions []Expression, ...) ([]any, error)
• type Argument
• type ArgumentBase
• type DBNamedArgument
• type Dialect
• type DialectWithNamed
• type ExpressBuilder
  • func NewExpressBuilder(w Writer, d Dialect, start int) *ExpressBuilder
  • func (h *ExpressBuilder) Err() error
  • func (h *ExpressBuilder) Express(e Expression)
  • func (h *ExpressBuilder) ExpressIf(e Expression, cond bool, prefix, suffix Expression)
  • func (h *ExpressBuilder) ExpressSlice(expressions []Expression, prefix, sep, suffix Expression)
  • func (h *ExpressBuilder) Result() ([]any, error)
  • func (h *ExpressBuilder) WriteQuery(e Query)
• type Expression
• type ExpressionFunc
  • func (e ExpressionFunc) WriteSQL(w Writer, d Dialect, start int) ([]any, error)
• type NamedArgument
• type Query
• type QueryBuilder
• type QueryClause
• type QueryClauseMerge
• type QueryClauseMultiple
• type ValuedArgument
• type Writer

Functions

func Express

func Express(w Writer, d Dialect, start int, e Expression) ([]any, error)

func ExpressIf

func ExpressIf(w Writer, d Dialect, start int, e Expression, cond bool, prefix, suffix Expression) ([]any, error)

ExpressIf expands an express if the condition evaluates to true it can also add a prefix and suffix

func ExpressSlice

func ExpressSlice(w Writer, d Dialect, start int, expressions []Expression, prefix, sep, suffix Expression) ([]any, error)

ExpressSlice is used to express a slice of expressions along with a prefix and suffix

Types

type Argument

type Argument interface {
	// contains filtered or unexported methods
}

Argument is the base interface for query arguments.

type ArgumentBase

type ArgumentBase struct{}

type DBNamedArgument

type DBNamedArgument interface {
	Argument
	DBName() string
}

DBNamedArgument is like NamedArgument but its value will be wrapped using [sql.Named].

type Dialect

type Dialect interface {
	WriteArg(w Writer, position int)
	WriteQuoted(w Writer, s string)
	WriteCheckQuoted(w Writer, s string)
}

type DialectWithNamed

type DialectWithNamed interface {
	Dialect
	WriteNamedArg(w Writer, name string)
}

type ExpressBuilder

type ExpressBuilder struct {
	// contains filtered or unexported fields
}

ExpressBuilder builds arguments in a sequence of Express calls.

func NewExpressBuilder

func NewExpressBuilder(w Writer, d Dialect, start int) *ExpressBuilder

func (*ExpressBuilder) Err

func (h *ExpressBuilder) Err() error

func (*ExpressBuilder) Express

func (h *ExpressBuilder) Express(e Expression)

func (*ExpressBuilder) ExpressIf

func (h *ExpressBuilder) ExpressIf(e Expression, cond bool, prefix, suffix Expression)

func (*ExpressBuilder) ExpressSlice

func (h *ExpressBuilder) ExpressSlice(expressions []Expression, prefix, sep, suffix Expression)

func (*ExpressBuilder) Result

func (h *ExpressBuilder) Result() ([]any, error)

func (*ExpressBuilder) WriteQuery

func (h *ExpressBuilder) WriteQuery(e Query)

type Expression

type Expression interface {
	WriteSQL(w Writer, d Dialect, start int) (args []any, err error)
}

type ExpressionFunc

type ExpressionFunc func(w Writer, d Dialect, start int) ([]any, error)

func (ExpressionFunc) WriteSQL

func (e ExpressionFunc) WriteSQL(w Writer, d Dialect, start int) ([]any, error)

type NamedArgument

type NamedArgument interface {
	Argument
	Name() string
}

NamedArgument represents an argument were its value will be provided by name.

type Query

type Query interface {
	Expression
	WriteQuery(w Writer, start int) (args []any, err error)
}

type QueryBuilder

type QueryBuilder interface {
	Dialect() Dialect
	Add(q QueryClause)
}

type QueryClause

type QueryClause interface {
	Expression
	ClauseID() string
	ClauseOrder() int
}

type QueryClauseMerge

type QueryClauseMerge interface {
	QueryClause
	ClauseMerge(other QueryClause)
}

type QueryClauseMultiple

type QueryClauseMultiple interface {
	QueryClause
	ClauseMultiple()
}

type ValuedArgument

type ValuedArgument interface {
	Argument
	Value() (any, error)
}

ValuedArgument represents an argument were its value will be provided by this instance.

type Writer

type Writer interface {
	Write(s string)
	WriteNewLine()
	WriteSeparator()
	AddSeparator(topLevel bool)
	StartQuery()
	Indent()
	Dedent()
	Err() error
}