query

Documentation

Overview

Package query provides a fluent, driver-aware SQL builder. It is used by the ORM but is fully usable on its own — it returns *sql.Rows where the caller wants raw access.

The builder is immutable in spirit: chaining methods returns a new (deeply-cloned) Builder. The actual implementation reuses the receiver and returns it for chaining; the contract is that a Builder, once executed, is not reused.

Index

• Constants
• type Builder
  • func New(conn *database.Connection, table string) *Builder
  • func (b *Builder) Avg(ctx context.Context, col string) (float64, error)
  • func (b *Builder) Connection() *database.Connection
  • func (b *Builder) Count(ctx context.Context) (int64, error)
  • func (b *Builder) Delete(ctx context.Context) (int64, error)
  • func (b *Builder) Distinct() *Builder
  • func (b *Builder) Exists(ctx context.Context) (bool, error)
  • func (b *Builder) From(table string) *Builder
  • func (b *Builder) Get(ctx context.Context) (*sql.Rows, error)
  • func (b *Builder) GroupBy(cols ...string) *Builder
  • func (b *Builder) Having(col, op string, value any) *Builder
  • func (b *Builder) Insert(ctx context.Context, values map[string]any) (sql.Result, error)
  • func (b *Builder) InsertBatch(ctx context.Context, rows []map[string]any) (sql.Result, error)
  • func (b *Builder) InsertGetID(ctx context.Context, values map[string]any, pk string) (int64, error)
  • func (b *Builder) Join(table, on string, args ...any) *Builder
  • func (b *Builder) Latest(col ...string) *Builder
  • func (b *Builder) LeftJoin(table, on string, args ...any) *Builder
  • func (b *Builder) Limit(n int) *Builder
  • func (b *Builder) LockForUpdate() *Builder
  • func (b *Builder) Max(ctx context.Context, col string) (float64, error)
  • func (b *Builder) Min(ctx context.Context, col string) (float64, error)
  • func (b *Builder) Offset(n int) *Builder
  • func (b *Builder) Oldest(col ...string) *Builder
  • func (b *Builder) OrWhere(args ...any) *Builder
  • func (b *Builder) OrderBy(col, dir string) *Builder
  • func (b *Builder) OrderByRaw(expr string) *Builder
  • func (b *Builder) Select(cols ...string) *Builder
  • func (b *Builder) SetExecutor(e database.Executor) *Builder
  • func (b *Builder) SharedLock() *Builder
  • func (b *Builder) Sum(ctx context.Context, col string) (float64, error)
  • func (b *Builder) ToSQL() (string, []any, error)
  • func (b *Builder) Truncate(ctx context.Context) error
  • func (b *Builder) Update(ctx context.Context, values map[string]any) (int64, error)
  • func (b *Builder) Where(args ...any) *Builder
  • func (b *Builder) WhereBetween(col string, lo, hi any) *Builder
  • func (b *Builder) WhereIn(col string, values any) *Builder
  • func (b *Builder) WhereNotIn(col string, values any) *Builder
  • func (b *Builder) WhereNotNull(col string) *Builder
  • func (b *Builder) WhereNull(col string) *Builder
  • func (b *Builder) WhereRaw(expr string, args ...any) *Builder

Constants

const (
	OpEq         = "="
	OpNe         = "<>"
	OpLt         = "<"
	OpLte        = "<="
	OpGt         = ">"
	OpGte        = ">="
	OpLike       = "like"
	OpILike      = "ilike"
	OpIn         = "in"
	OpNotIn      = "not in"
	OpBetween    = "between"
	OpNotBetween = "not between"
	OpIsNull     = "is null"
	OpNotNull    = "is not null"
)

Op enumerates supported comparison operators.

Types

type Builder

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

Builder builds SQL statements.

func New

func New(conn *database.Connection, table string) *Builder

New returns a fresh Builder for the given connection/table.

func (*Builder) Avg

func (b *Builder) Avg(ctx context.Context, col string) (float64, error)

Avg returns the average of a column.

func (*Builder) Connection

func (b *Builder) Connection() *database.Connection

Connection returns the underlying connection.

func (*Builder) Count

func (b *Builder) Count(ctx context.Context) (int64, error)

Count returns the COUNT(*) for the current WHERE/JOIN state.

func (*Builder) Delete

func (b *Builder) Delete(ctx context.Context) (int64, error)

Delete deletes rows matching the WHERE clauses. Returns rows affected.

func (*Builder) Distinct

func (b *Builder) Distinct() *Builder

Distinct toggles DISTINCT.

func (*Builder) Exists

func (b *Builder) Exists(ctx context.Context) (bool, error)

Exists returns true if at least one row matches.

func (*Builder) From

func (b *Builder) From(table string) *Builder

From sets the table.

func (*Builder) Get

func (b *Builder) Get(ctx context.Context) (*sql.Rows, error)

Get executes the SELECT and returns the rows.

func (*Builder) GroupBy

func (b *Builder) GroupBy(cols ...string) *Builder

GroupBy adds GROUP BY columns.

func (*Builder) Having

func (b *Builder) Having(col, op string, value any) *Builder

Having adds an AND HAVING.

func (*Builder) Insert

func (b *Builder) Insert(ctx context.Context, values map[string]any) (sql.Result, error)

Insert inserts a single row. Returns the *sql.Result.

func (*Builder) InsertBatch

func (b *Builder) InsertBatch(ctx context.Context, rows []map[string]any) (sql.Result, error)

InsertBatch performs a multi-row insert.

func (*Builder) InsertGetID

func (b *Builder) InsertGetID(ctx context.Context, values map[string]any, pk string) (int64, error)

InsertGetID inserts and returns the auto-incremented ID. For Postgres this appends RETURNING <pk>.

func (*Builder) Join

func (b *Builder) Join(table, on string, args ...any) *Builder

Join adds an INNER JOIN.

func (*Builder) Latest

func (b *Builder) Latest(col ...string) *Builder

Latest orders by the column descending. Default column is "created_at".

func (*Builder) LeftJoin

func (b *Builder) LeftJoin(table, on string, args ...any) *Builder

LeftJoin adds a LEFT JOIN.

func (*Builder) Limit

func (b *Builder) Limit(n int) *Builder

Limit sets the row limit.

func (*Builder) LockForUpdate

func (b *Builder) LockForUpdate() *Builder

LockForUpdate appends FOR UPDATE on supported dialects.

func (*Builder) Max

func (b *Builder) Max(ctx context.Context, col string) (float64, error)

Max returns the maximum value.

func (*Builder) Min

func (b *Builder) Min(ctx context.Context, col string) (float64, error)

Min returns the minimum value.

func (*Builder) Offset

func (b *Builder) Offset(n int) *Builder

Offset sets the row offset.

func (*Builder) Oldest

func (b *Builder) Oldest(col ...string) *Builder

Oldest orders by the column ascending. Default column is "created_at".

func (*Builder) OrWhere

func (b *Builder) OrWhere(args ...any) *Builder

OrWhere appends an OR condition.

func (*Builder) OrderBy

func (b *Builder) OrderBy(col, dir string) *Builder

OrderBy adds an ORDER BY.

func (*Builder) OrderByRaw

func (b *Builder) OrderByRaw(expr string) *Builder

OrderByRaw adds a raw ORDER BY clause.

func (*Builder) Select

func (b *Builder) Select(cols ...string) *Builder

Select replaces the column list.

func (*Builder) SetExecutor

func (b *Builder) SetExecutor(e database.Executor) *Builder

SetExecutor lets a Tx wrap the builder so it runs inside a transaction.

func (*Builder) SharedLock

func (b *Builder) SharedLock() *Builder

SharedLock appends FOR SHARE on supported dialects.

func (*Builder) Sum

func (b *Builder) Sum(ctx context.Context, col string) (float64, error)

Sum returns the sum of a column.

func (*Builder) ToSQL

func (b *Builder) ToSQL() (string, []any, error)

ToSQL compiles the builder into a SELECT statement and its bound args.

func (*Builder) Truncate

func (b *Builder) Truncate(ctx context.Context) error

Truncate empties the table.

func (*Builder) Update

func (b *Builder) Update(ctx context.Context, values map[string]any) (int64, error)

Update performs an UPDATE with the current WHERE clauses.

func (*Builder) Where

func (b *Builder) Where(args ...any) *Builder

Where appends an AND condition.

Where("name", "=", "Ada") | Where("name", "Ada") | Where(func(q *Builder) { ... })

func (*Builder) WhereBetween

func (b *Builder) WhereBetween(col string, lo, hi any) *Builder

WhereBetween appends a BETWEEN constraint.

func (*Builder) WhereIn

func (b *Builder) WhereIn(col string, values any) *Builder

WhereIn appends an IN constraint.

func (*Builder) WhereNotIn

func (b *Builder) WhereNotIn(col string, values any) *Builder

WhereNotIn appends a NOT IN constraint.

func (*Builder) WhereNotNull

func (b *Builder) WhereNotNull(col string) *Builder

WhereNotNull appends an IS NOT NULL constraint.

func (*Builder) WhereNull

func (b *Builder) WhereNull(col string) *Builder

WhereNull appends an IS NULL constraint.

func (*Builder) WhereRaw

func (b *Builder) WhereRaw(expr string, args ...any) *Builder

WhereRaw appends a raw expression.