Documentation
¶
Overview ¶
Package sqlbuild assembles the handful of SQL statement shapes FSC's storage drivers need, together with their positional parameters.
It is deliberately not a query builder: there is no support for joins, aliases, DISTINCT, GROUP BY, HAVING or subqueries. Callers write the static parts of their statement as plain strings and use this package only for the parts that vary — parameter numbering, value tuples, WHERE conditions and pagination suffixes.
Placeholders are always $N, numbered in write order. Both PostgreSQL and modernc.org/sqlite bind $N by number, so the same statement text works on both.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoValues = errors.New("insert statements must have at least one set of values or select clause")
ErrNoValues reports an INSERT with no rows to insert. Callers return it instead of building the statement; Builder.WriteTuples panics if they do not. The message is squirrel's, so the error a caller surfaces for an empty insert is unchanged from before this package existed.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder accumulates a SQL statement and its positional parameters. The zero value is not usable; call New.
func (*Builder) Build ¶
Build returns the accumulated statement and its parameters. The parameter slice is nil when the statement takes no parameters.
func (*Builder) WritePaging ¶
WritePaging appends the ORDER BY, LIMIT and OFFSET clauses p calls for, in that order. LIMIT and OFFSET are written as literals rather than parameters, so they do not appear in the parameters Builder.Build returns.
func (*Builder) WriteParam ¶
WriteParam appends the next placeholder ($1, $2, …) and records v as its value.
func (*Builder) WriteString ¶
WriteString appends raw SQL text verbatim. The text is never escaped or inspected, so it must not contain caller-supplied values — use Builder.WriteParam for those.
func (*Builder) WriteTuples ¶
WriteTuples appends the VALUES rows of an INSERT as ($1,$2),($3,$4), with no spaces around the separators. It panics when rows is empty: there is no SQL for a VALUES clause with no rows, so callers reject that with ErrNoValues before they start building.
func (*Builder) WriteWhere ¶
WriteWhere appends " WHERE " followed by the non-nil conditions joined with " AND ", or nothing at all when none are given. The conditions are joined without wrapping parentheses; use And where a bracketed group is needed.
type CondFunc ¶
type CondFunc func(*Builder)
CondFunc adapts a function to Condition. Use it for the rare fragment the constructors in this package do not cover, such as a scalar subquery.
type Condition ¶
type Condition interface {
WriteTo(*Builder)
}
Condition is a fragment of a WHERE clause. Implementations write themselves into a Builder, taking their placeholder numbers from it.
func And ¶
And renders "(a AND b AND …)", keeping the parentheses even for a single condition. nil conditions are skipped, so optional bounds can be passed through directly. With nothing left it renders the always-true "(1=1)".
type Paging ¶
type Paging struct {
// OrderBy is the column to sort ascending by, or "" for no ORDER BY.
OrderBy string
// Limit caps the rows returned. A nil Limit — or one pointing at a negative
// value — writes no LIMIT clause.
Limit *int
// Offset is the number of rows to skip. It is written only when Limit is
// set and Offset is positive.
Offset int
// Where is the keyset cursor condition, or nil.
Where Condition
}
Paging is the contribution a pagination makes to a SELECT statement.
The zero value contributes nothing, which is why Limit is a pointer rather than an int with a sentinel: forgetting to set it yields an unpaginated read rather than a silently empty result set. LIMIT 0 stays expressible as new(0), because it is a meaningful query that returns no rows.
Where is not written by Builder.WritePaging: it has to be merged into the statement's WHERE clause, which comes before ORDER BY, so the caller passes it to Builder.WriteWhere alongside its own conditions.
Source Files