Documentation
¶
Overview ¶
Package frag builds and flattens SQL fragments with bound arguments.
A Fragment yields query text chunks and args via Fragment.Frag. Collect concatenates them into a final query string and argument list for database/sql execution. [builder] statements are Fragments; this package is the low-level composition layer underneath.
q, args := frag.Collect(ctx, frag.Query("SELECT * FROM t WHERE id = ?", 1))
// q = "SELECT * FROM t WHERE id = ?" args = [1]
Core types ¶
- Fragment: IsNil + Frag(ctx) → Iter
- Iter: yields (query piece, args) pairs
- Collect / Stringify: flatten a Fragment for execution or debug
- IsNil / NonNil: nil checks and filtering
Constructors ¶
Query: template with `?` positional and `@name` named placeholders (NamedArg / NamedArgs). Nested Fragments, slices, and sequences expand in place (e.g. `IN (?)` with []int → `IN (?,?,?)`).
Arg / ArgIter / ArgIterFunc / Values: expand a value into placeholders; supports CustomValueArg, driver.Valuer, slices, seqs
Func: wrap a context-aware iterator factory as a Fragment
frag.Query("IN (?)", []int{1, 2, 3}) // IN (?,?,?) [1 2 3]
frag.Query("time > @min AND time < @max", sql.Named("min", 10), sql.Named("max", 20)) // time > ? AND time < ? [10, 20]
Composition ¶
- Compose / ComposeSeq: join fragments with a separator (skips nil)
- Block: wrap a fragment in parentheses
- BlockWithoutBrackets: join fragments with commas, no surrounding ()
Other ¶
- Alias: stable short alias for table__column names
Index ¶
- func Alias(table, column string) string
- func Collect(ctx context.Context, f Fragment) (string, []any)
- func IsNil(e Fragment) bool
- func NonNil[F Fragment](seq iter.Seq[F]) iter.Seq[Fragment]
- func Stringify(f Fragment) string
- type CustomValueArg
- type Fragment
- func Arg(v any) Fragment
- func ArgIterFunc(v any) Fragment
- func Block(f Fragment) Fragment
- func BlockWithoutBrackets(seq iter.Seq[Fragment]) Fragment
- func Compose(sep string, frags ...Fragment) Fragment
- func ComposeSeq(sep string, frags iter.Seq[Fragment]) Fragment
- func Empty() Fragment
- func Func(f func(context.Context) Iter) Fragment
- func Lit(q string) Fragment
- func Query(query string, args ...any) Fragment
- type Iter
- type NamedArg
- type NamedArgs
- type Values
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Alias ¶
Alias generates a deterministic alias name for a given table and column. If the combined length is shorter than 64 characters (minus separators), it returns a simple "table__column" alias. Otherwise, it generates a hashed form using a cached SHA1-based abbreviation to keep the alias short and stable.
Types ¶
type CustomValueArg ¶
type CustomValueArg interface {
ValueEx() string
}
CustomValueArg supports replacing ? to some sql snippet eg: ? => UPPER(?)
type Fragment ¶
type Fragment interface {
// IsNil reports whether the fragment is empty.
IsNil() bool
// Frag yields SQL text chunks and their bound arguments.
Frag(ctx context.Context) Iter
}
Fragment is a SQL fragment that yields query pieces and arguments.
func BlockWithoutBrackets ¶
BlockWithoutBrackets joins fragments with commas, without surrounding parentheses.
func ComposeSeq ¶
ComposeSeq joins an iterator of fragments with sep, skipping nil fragments.
type Iter ¶
Iter will yield a SQL fragment with a raw query(string with holder) and values eg:
query = INSERT INTO t_table (f_x,f_y,f_z) VALUES (?,?,?) args = 1, '2', 3.0
Source Files
Directories