Documentation
¶
Overview ¶
Package r3sql translates r3 query types into SQL clauses: r3.Filters to WHERE with positional placeholders, r3.Sorts to ORDER BY, r3.PaginationSpec to LIMIT/OFFSET. Used by the SQL engine and drivers; rarely imported directly.
DB-specific variations (ILIKE, placeholder style, NULLS FIRST/LAST) are the engine layer's job via engine/sql.Flavor; this package emits generic SQL.
Index ¶
- Variables
- func AggregateExpr(a *r3.AggregateSpec) (string, error)
- func AggregateToSQL(a *r3.AggregateSpec) (string, error)
- func GroupByToSQL(fields r3.Fields) ([]string, error)
- func IsErrDialectorFailure(err error) bool
- func QuoteDottedIdentifier(path string) string
- func QuoteIdentifier(name string) string
- func SQLToField(col SQLColumn) *r3.FieldSpec
- func SQLToOperator(op SQLClauseOperator) (r3.FilterOperatorSpec, error)
- func SQLToPagination(p *SQLPagination) *r3.PaginationSpec
- func SQLToSort(s SQLSort) (*r3.SortSpec, error)
- func SafeColumnExpr(f *r3.FieldSpec) (string, error)
- type SQLClause
- type SQLClauseOperator
- type SQLClauses
- type SQLColumn
- type SQLPagination
- type SQLSort
Constants ¶
This section is empty.
Variables ¶
var ErrSQLDialectorFailed = errors.New("sql dialector failed")
ErrSQLDialectorFailed is the sentinel wrapping every r3sql failure.
Functions ¶
func AggregateExpr ¶ added in v0.0.3
func AggregateExpr(a *r3.AggregateSpec) (string, error)
AggregateExpr returns the bare, un-aliased SQL expression for an aggregate spec: COUNT(*), COUNT(DISTINCT "col"), SUM("col"), ... (field validated and quoted via SafeColumnExpr). HAVING must use this form, not the alias: PostgreSQL rejects select-list aliases in HAVING; expressions are portable.
func AggregateToSQL ¶ added in v0.0.3
func AggregateToSQL(a *r3.AggregateSpec) (string, error)
AggregateToSQL returns the select-list item, `COUNT(*) AS "alias"`, with the alias validated and quoted.
func GroupByToSQL ¶ added in v0.0.3
GroupByToSQL validates and quotes the group-by fields, returning one quoted column expression per field.
func IsErrDialectorFailure ¶
IsErrDialectorFailure reports whether err is a r3sql failure.
func QuoteDottedIdentifier ¶
QuoteDottedIdentifier quotes each segment of a dotted path and rejoins with dots: "user.name" => `"user"."name"`.
func QuoteIdentifier ¶
QuoteIdentifier double-quotes a SQL identifier, escaping embedded quotes by doubling them (ANSI standard). Safe for PostgreSQL, SQLite, and MySQL: the major ORMs all accept double-quoted identifiers.
QuoteIdentifier("id") => `"id"`
QuoteIdentifier(`col"name`) => `"col""name"` (escaped)
func SQLToField ¶
SQLToField converts an SQLColumn to a FieldSpec.
func SQLToOperator ¶
func SQLToOperator(op SQLClauseOperator) (r3.FilterOperatorSpec, error)
SQLToOperator converts an SQLClauseOperator back to a FilterOperatorSpec.
func SQLToPagination ¶
func SQLToPagination(p *SQLPagination) *r3.PaginationSpec
SQLToPagination converts SQLPagination to PaginationSpec.
func SafeColumnExpr ¶
SafeColumnExpr validates a FieldSpec and returns its quoted SQL expression - the SQL-injection defense used by FilterToSQL and SortToSQL. Two layers: r3.ValidateIdentifier restricts the name to safe characters, then each segment is double-quoted. Errors on an invalid name.
Types ¶
type SQLClause ¶
type SQLClause struct {
// Clause is the raw safe SQL string (e.g. "name = ?")
Clause string
// Args is a slice of arguments to be bound to the SQL clause.
// Len of arguments must match the number of placeholders in the clause.
Args []any
// Joins is a slice of joins that are required for the clause.
Joins []SQLColumn
}
SQLClause represents a r3.Filter that can be converted into SQL Clause (used by gorm, sqlx, squirrel, etc.)
func CursorToSQLClause ¶
func CursorToSQLClause(values r3.CursorValues, sorts r3.Sorts, direction r3.CursorDirection) (SQLClause, error)
CursorToSQLClause builds a keyset pagination WHERE clause from decoded cursor values and the sort spec. A single column (created_at DESC) gives:
WHERE "created_at" < ?
Multiple columns (created_at DESC, id ASC) give a compound condition:
WHERE ("created_at" < ?) OR ("created_at" = ? AND "id" > ?)
direction picks > (forward) or < (backward), flipped per column sort direction.
func FilterToSQL ¶
func FilterToSQL(cf *r3.FilterSpec) (SQLClause, error)
FilterToSQL converts a FilterSpec to an SQLClause.
func HavingToSQL ¶ added in v0.0.3
HavingToSQL converts Having filters (implicitly ANDed) into one SQLClause. Each leaf's name resolves through exprByName - aggregate aliases to their full expressions (SUM("col")), group fields to quoted columns - because HAVING cannot reference select-list aliases portably. An absent name is an error (the caller validates first via r3.Schema.ValidateAggregateQuery).
type SQLClauseOperator ¶
type SQLClauseOperator string
SQLClauseOperator represents a SQL operator. e.g. "=", "LIKE", "IN".
const ( SQLClauseOperatorEq SQLClauseOperator = "=" SQLClauseOperatorNe SQLClauseOperator = "!=" SQLClauseOperatorGt SQLClauseOperator = ">" SQLClauseOperatorGte SQLClauseOperator = ">=" SQLClauseOperatorLt SQLClauseOperator = "<" SQLClauseOperatorLte SQLClauseOperator = "<=" SQLClauseOperatorLike SQLClauseOperator = "LIKE" SQLClauseOperatorNotLike SQLClauseOperator = "NOT LIKE" SQLClauseOperatorILike SQLClauseOperator = "ILIKE" SQLClauseOperatorIn SQLClauseOperator = "IN" SQLClauseOperatorNotIn SQLClauseOperator = "NOT IN" )
List of supported SQL operators.
func OperatorToSQL ¶
func OperatorToSQL(op r3.FilterOperatorSpec) (SQLClauseOperator, error)
OperatorToSQL converts a FilterOperatorSpec to an SQLClauseOperator.
func (SQLClauseOperator) String ¶
func (op SQLClauseOperator) String() string
String implements fmt.Stringer.
func (SQLClauseOperator) ToSQL ¶
func (op SQLClauseOperator) ToSQL() string
ToSQL returns the operator as it appears in generated SQL.
type SQLClauses ¶
type SQLClauses []SQLClause
SQLClauses is a slice of SQLClause.
func FiltersToSQL ¶
func FiltersToSQL(filters r3.Filters) (SQLClauses, error)
FiltersToSQL translates a list of r3.Filters into SQLClauses.
func FiltersToSQLClauses
deprecated
func FiltersToSQLClauses(filters r3.Filters) (SQLClauses, error)
FiltersToSQLClauses is an alias for FiltersToSQL for backward compatibility.
Deprecated: Use FiltersToSQL instead.
func (SQLClauses) Joins ¶
func (cs SQLClauses) Joins() []SQLColumn
Joins is a combined getter for each SQLClause.Joins It will return duplicates-free list.
type SQLColumn ¶
type SQLColumn string
SQLColumn is a column name.
func FieldToSQL ¶
FieldToSQL converts a FieldSpec to a raw, unquoted SQLColumn. It does NOT validate or quote; use SafeColumnExpr for user-supplied field names.
type SQLPagination ¶
SQLPagination is LIMIT/OFFSET pagination.
func NewSQLPagination ¶
func NewSQLPagination(limit, offset int) *SQLPagination
NewSQLPagination creates a new SQLPagination with given limit and offset.
func PaginationToSQL ¶
func PaginationToSQL(p *r3.PaginationSpec) *SQLPagination
PaginationToSQL converts a PaginationSpec to SQLPagination.
func (*SQLPagination) String ¶
func (sp *SQLPagination) String() string
String returns the string representation of SQL pagination.
func (*SQLPagination) ToLimitOffset ¶
func (sp *SQLPagination) ToLimitOffset() (int, int)
ToLimitOffset returns the limit and offset values.
Source Files