r3sql

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 6 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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

func GroupByToSQL(fields r3.Fields) ([]string, error)

GroupByToSQL validates and quotes the group-by fields, returning one quoted column expression per field.

func GroupByToSQLWith added in v0.9.0

func GroupByToSQLWith(fields r3.Fields, opts RenderOptions) ([]string, error)

GroupByToSQLWith is GroupByToSQL rendering JSON group fields through opts.

func IsErrDialectorFailure

func IsErrDialectorFailure(err error) bool

IsErrDialectorFailure reports whether err is a r3sql failure.

func QuoteDottedIdentifier

func QuoteDottedIdentifier(path string) string

QuoteDottedIdentifier quotes each segment of a dotted path and rejoins with dots: "user.name" => `"user"."name"`.

func QuoteIdentifier

func QuoteIdentifier(name string) string

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

func SQLToField(col SQLColumn) *r3.FieldSpec

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 SQLToSort

func SQLToSort(s SQLSort) (*r3.SortSpec, error)

SQLToSort converts an SQLSort string back to a SortSpec.

func SafeColumnExpr

func SafeColumnExpr(f *r3.FieldSpec) (string, error)

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.

func SafeFieldExpr added in v0.9.0

func SafeFieldExpr(f *r3.FieldSpec, opts RenderOptions) (string, error)

SafeFieldExpr is SafeColumnExpr that also renders a JSON field through opts.JSONPathExpr after validating it. Filters, sorts, cursors and group-by render their fields through it.

Types

type JSONPathExprFunc added in v0.9.0

type JSONPathExprFunc func(quotedCol string, path []string, numeric bool) (string, error)

JSONPathExprFunc renders the extraction of a key path from a JSON column. quotedCol is the already ANSI-quoted column; path segments are already validated identifiers. numeric selects a numeric comparison over text.

type RenderOptions added in v0.9.0

type RenderOptions struct {
	// JSONPathExpr renders a JSON field (see [r3.JSONField]); nil rejects one.
	JSONPathExpr JSONPathExprFunc
}

RenderOptions carries the flavor-specific rendering this flavor-neutral dialect cannot do itself. The zero value renders plain fields only and rejects a JSON field with r3.ErrJSONFieldNotSupported.

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 CursorToSQLClauseWith added in v0.9.0

func CursorToSQLClauseWith(
	values r3.CursorValues, sorts r3.Sorts, direction r3.CursorDirection, opts RenderOptions,
) (SQLClause, error)

CursorToSQLClauseWith is CursorToSQLClause rendering JSON sort fields through opts.

func FilterToSQL

func FilterToSQL(cf *r3.FilterSpec) (SQLClause, error)

FilterToSQL converts a FilterSpec to an SQLClause. A JSON field is rejected; use FilterToSQLWith with a flavor's RenderOptions to render one.

func FilterToSQLWith added in v0.9.0

func FilterToSQLWith(cf *r3.FilterSpec, opts RenderOptions) (SQLClause, error)

FilterToSQLWith is FilterToSQL rendering JSON fields through opts.

func HavingToSQL added in v0.0.3

func HavingToSQL(having r3.Filters, exprByName map[string]string) (SQLClause, error)

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. A JSON field is rejected; use FiltersToSQLWith to render one.

func FiltersToSQLClauses deprecated

func FiltersToSQLClauses(filters r3.Filters) (SQLClauses, error)

FiltersToSQLClauses is an alias for FiltersToSQL for backward compatibility.

Deprecated: Use FiltersToSQL instead.

func FiltersToSQLWith added in v0.9.0

func FiltersToSQLWith(filters r3.Filters, opts RenderOptions) (SQLClauses, error)

FiltersToSQLWith is FiltersToSQL rendering JSON fields through opts.

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

func FieldToSQL(f *r3.FieldSpec) SQLColumn

FieldToSQL converts a FieldSpec to a raw, unquoted SQLColumn. It does NOT validate or quote; use SafeColumnExpr for user-supplied field names.

func (SQLColumn) String

func (sc SQLColumn) String() string

String returns the column name as a string.

type SQLPagination

type SQLPagination struct {
	Limit  int
	Offset int
}

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.

type SQLSort

type SQLSort string

SQLSort is a SQL sort clause, e.g. "name ASC", "created_at DESC NULLS LAST".

func SortToSQL

func SortToSQL(s *r3.SortSpec) (SQLSort, error)

SortToSQL converts a SortSpec to an SQLSort. A JSON field is rejected; use SortToSQLWith to render one.

func SortToSQLWith added in v0.9.0

func SortToSQLWith(s *r3.SortSpec, opts RenderOptions) (SQLSort, error)

SortToSQLWith is SortToSQL rendering a JSON field through opts.

func SortsToSQL

func SortsToSQL(ss r3.Sorts) ([]SQLSort, error)

SortsToSQL converts a slice of SortSpec to a slice of SQLSort.

func SortsToSQLWith added in v0.9.0

func SortsToSQLWith(ss r3.Sorts, opts RenderOptions) ([]SQLSort, error)

SortsToSQLWith is SortsToSQL rendering JSON fields through opts.

func (SQLSort) String

func (ss SQLSort) String() string

String returns the SQL sort expression as a string.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL