API Overview

A map of the public surface of github.com/akfaiz/quill/db. For signatures and doc comments, use pkg.go.dev or go doc:

go doc github.com/akfaiz/quill/db
go doc github.com/akfaiz/quill/db SelectBuilder.Where

Online: https://pkg.go.dev/github.com/akfaiz/quill/db

On this page: Package functions · Types · Options · Methods by area · Which builder has what

Package functions

Function	Purpose
db.Use(dialect, opts...)	Build-only *DB
db.New(conn, dialect, opts...)	Build-and-run *DB
db.From[T](conn)	Typed select, table from T.TableName()
db.As[T](selectBuilder)	Typed select over a builder you made
db.Raw(sql, args...)	Raw SQL expression
db.Row(structValue)	Struct to map[string]any using db tags
db.TableName[T]()	Table name of a Tabler type
db.ValueAs[T], db.PluckAs[T]	Scalar helpers
db.Stream[T]	Row iterator
db.CTEColumns, CTEMaterialized, CTENotMaterialized, CTEUnionDistinct	CTE options
db.WithPrefix, db.WithHook, db.WithLogArgs	Constructor options

There is no builder constructor besides the DB methods. Start with db.Use(dialect).Select() (or Insert, Update, Delete) when you only need SQL.

Types

Type	Purpose
db.Dialect	Postgres, MySQL, MariaDB, SQLite
db.DB	A dialect plus an optional connection. Starts statements
db.Conn	QueryContext and ExecContext. Satisfied by *sql.DB, *sql.Tx, *sql.Conn
db.SelectBuilder	A SELECT: where, joins, grouping, unions, CTEs, locks, readers
db.InsertBuilder	An INSERT: Values, Rows, Ignore, Using, Upsert, Returning
db.UpdateBuilder	An UPDATE: Set*, Increment*, FromJoins, where, joins, order, limit
db.DeleteBuilder	A DELETE: where, joins, order, limit
db.WhereClause	Conditions inside a WhereGroup callback
db.HavingClause	Conditions inside a HavingGroup callback
db.JoinClause	Conditions of one join, inside JoinFunc and friends
db.Expression	Raw SQL plus arguments
db.Query[T]	Typed, select-only query
db.Tabler	Interface: TableName() string
db.Option	A db.New / db.Use option
db.QueryEvent	SQL, NumArgs, Args, Duration, Err, passed to hooks
db.Stmt	SQL and Args of one statement (DB.TruncateSQL)
db.Page	Total, PerPage, CurrentPage, LastPage, From, To
db.SimplePage	PerPage, CurrentPage, HasMore
db.CursorPage	PerPage, HasMore, NextCursor
db.CursorOptions	Column (default "id"), Desc
db.Paged[T], db.SimplePaged[T], db.CursorPaged[T]	Page types with Items []T

Options

Option	Effect
db.WithPrefix(prefix)	Table prefix for table names, aliases and qualified columns
db.WithHook(fn)	fn(ctx, QueryEvent) after every statement
db.WithLogArgs()	Put bind values in QueryEvent.Args (off by default)

CTE options, passed after the query of With, WithRaw and WithRecursive:

Option	Effect
db.CTEColumns(cols...)	Name the CTE's columns
db.CTEMaterialized(), db.CTENotMaterialized()	AS [NOT] MATERIALIZED (PostgreSQL, SQLite)
db.CTEUnionDistinct()	UNION instead of UNION ALL in WithRecursive

Methods by area

db.DB

Delete, Dialect, Exec, Insert, Query, Select, Transaction, TransactionOpts, Truncate, TruncateSQL, Update, UpdateOrInsert

db.SelectBuilder

Area	Methods	Guide
Build SQL	ToSQL, ToRawSQL, MustSQL, MustRawSQL, ExistsSQL, AggregateSQL	Select Queries
Select and source	Select, AddSelect, SelectRaw, SelectSub, Distinct, From, FromRaw, FromSub, Prefix	Select Queries
Where	Where, OrWhere, WhereNot, WhereRaw, WhereColumn, WhereIn, WhereNotIn, WhereIntegerInRaw, WhereNull, WhereNotNull, WhereBetween, WhereBetweenColumns, WhereValueBetween, WhereLike, WhereNotLike, WhereNullSafeEquals, WhereAll, WhereAny, WhereNone, WhereRowValues, WhereExists, WhereNotExists, WhereGroup, WhereMap, WhereDate, WhereTime, WhereDay, WhereMonth, WhereYear (each with an Or variant where it makes sense)	Where Clauses
JSON	WhereJsonContains, WhereJsonDoesntContain, WhereJsonContainsKey, WhereJsonDoesntContainKey, WhereJsonLength, WhereJsonOverlaps, WhereJsonDoesntOverlap (each with an Or variant)	JSON Support
Group and having	GroupBy, GroupByRaw, Having, HavingBetween, HavingNull, HavingNotNull, HavingNotBetween, HavingRaw, HavingGroup (with Or variants)	Select Queries
Joins	Join, LeftJoin, RightJoin, CrossJoin, *Func, *Sub, *SubFunc, *Where, JoinLateral, LeftJoinLateral, StraightJoin	Joins
Ordering and paging	OrderBy, OrderByDesc, OrderByRaw, Latest, Oldest, InRandomOrder, Reorder, ReorderBy, Limit/Take, Offset/Skip, ForPage, ForPageAfterID, ForPageBeforeID	Select Queries
CTEs	With, WithRaw, WithRecursive	Subqueries, Unions and CTEs
Unions, locks, hints	Union, UnionAll, LockForUpdate, SharedLock, Lock, UseIndex, ForceIndex, IgnoreIndex	Select Queries
Control flow	Clone, Err, Tap, When, Unless	Core Concepts
Read	Get, First, Find, Sole, Value, Pluck, PluckMap, Exists, DoesntExist, Count, Sum, Avg, Min, Max, Aggregate, Paginate, SimplePaginate, CursorPaginate, Chunk, ChunkByID, Each	Reading Data, Pagination and Chunking

db.InsertBuilder

Values, Rows, Ignore, Using, Upsert, Returning, Exec, ExecGetID, Get, ToSQL, IDSQL, With, WithRaw, WithRecursive, Prefix, Clone, Err

db.UpdateBuilder

Set, SetMap, SetRow, Increment, Decrement, IncrementEach, DecrementEach, FromJoins, AllRows, Returning, Exec, Get, ToSQL, plus where, joins, ordering (OrderBy*, Latest, Oldest, Limit/Take), CTEs, Prefix, Clone, Err

db.DeleteBuilder

AllRows, Returning, Exec, Get, ToSQL, plus where, joins, ordering, Limit/Take, CTEs, Prefix, Clone, Err

Clause types

• db.WhereClause: every Where* and OrWhere* method, including groups and JSON conditions.
• db.HavingClause: Having* and OrHaving*.
• db.JoinClause: On, OrOn, OnGroup, OrOnGroup, Where, OrWhere, WhereIn, OrWhereIn, WhereNotIn, OrWhereNotIn, WhereNull, OrWhereNull, WhereNotNull, OrWhereNotNull, WhereRaw, OrWhereRaw.

db.Query[T]

Mirrors the SelectBuilder chain methods and returns *db.Query[T]. Readers return T values. Adds Apply, Builder and Stream. See Typed API.

Which builder has what

Capability	Select	Insert	Update	Delete
Where*	Yes	No	Yes	Yes
Join*	Yes	No	Yes	Yes
OrderBy*, Limit	Yes	No	Yes	Yes
Offset	Yes	No	No	No
GroupBy, Having*, Union*, locks	Yes	No	No	No
With* (CTEs)	Yes	Yes (needs Using)	Yes (not MariaDB)	Yes (not MariaDB)
Returning	No	Yes	Yes	Yes
AllRows	No	No	Yes	Yes
Exec	No	Yes	Yes	Yes
Get	Yes	With Returning	With Returning	With Returning