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.
Chaining methods (Where, OrderBy, Limit, ...) mutate and return the receiver, so a Builder is single-use: build it, execute once, discard. The terminal aggregate helpers (Count, Exists, Sum, ...) are the exception — they operate on an internal clone so they never disturb the receiver's clause state and may be called mid-chain.
Index ¶
- Constants
- type Builder
- func (b *Builder) Avg(ctx context.Context, col string) (float64, error)
- func (b *Builder) Clone() *Builder
- 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
- func (b *Builder) WrapWheres() *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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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) Clone ¶ added in v0.20.0
Clone returns a deep copy of the builder. Callers that want to branch a query (e.g. run First() and then Get() off the same base) use this to avoid the receiver's single-use mutation semantics leaking across calls.
func (*Builder) Connection ¶
func (b *Builder) Connection() *database.Connection
Connection returns the underlying connection.
func (*Builder) Count ¶
Count returns the COUNT(*) for the current WHERE/JOIN state. When the query has a GROUP BY, a plain COUNT(*) would return only the first group's count; in that case the grouped query is wrapped in a subquery so the result is the number of groups.
func (*Builder) Exists ¶
Exists returns true if at least one row matches. It operates on a clone so the receiver's state is not mutated.
func (*Builder) Having ¶
Having adds an AND HAVING. The operator is whitelisted (see normalizeOp); an unsupported operator panics rather than being concatenated into the SQL.
func (*Builder) InsertBatch ¶
InsertBatch performs a multi-row insert.
func (*Builder) InsertGetID ¶
InsertGetID inserts and returns the auto-incremented ID. For Postgres this appends RETURNING <pk>.
func (*Builder) LockForUpdate ¶
LockForUpdate appends FOR UPDATE on supported dialects. SQLite has no row locking syntax, so the clause is a no-op there.
func (*Builder) OrderBy ¶
OrderBy adds an ORDER BY. The direction is whitelisted to ASC/DESC; any other value (e.g. an injection attempt) panics rather than being emitted into the SQL.
func (*Builder) OrderByRaw ¶
OrderByRaw adds a raw ORDER BY clause.
func (*Builder) SetExecutor ¶
SetExecutor lets a Tx wrap the builder so it runs inside a transaction.
func (*Builder) SharedLock ¶
SharedLock appends FOR SHARE on supported dialects. SQLite has no row locking syntax, so the clause is a no-op there.
func (*Builder) Where ¶
Where appends an AND condition.
Where("name", "=", "Ada") | Where("name", "Ada") | Where(func(q *Builder) { ... })
func (*Builder) WhereBetween ¶
WhereBetween appends a BETWEEN constraint.
func (*Builder) WhereNotIn ¶
WhereNotIn appends a NOT IN constraint.
func (*Builder) WhereNotNull ¶
WhereNotNull appends an IS NOT NULL constraint.
func (*Builder) WrapWheres ¶ added in v0.27.0
WrapWheres groups the current WHERE conditions in parentheses when they contain an OR, so conditions appended afterwards (scopes, cursors, key lookups) apply to the whole filter instead of binding only to the last OR branch. Without OR the conditions are left untouched.
Source Files