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
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) 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.
Source Files