Documentation
¶
Overview ¶
Package dialect renders the database-specific pieces of SQL. The planner never writes a quote or a placeholder itself.
Index ¶
- Variables
- func IsValueFunction(name string) bool
- func Literal(text string) string
- func QuoteWith(q string, ident string) string
- type Dialect
- type MySQL
- func (MySQL) ClockOperand(col string, _ int) string
- func (MySQL) ColumnFunction(name, col string, arg func(int) string) (string, bool)
- func (MySQL) ContainsBinary(col string, value func(string) string) string
- func (MySQL) DecodesStyle(s string) bool
- func (MySQL) ForceIndex(name string) string
- func (MySQL) Fulltext(cols []string, value func(string) string, boolean bool) (string, bool)
- func (MySQL) HandlesStyle(s string) bool
- func (MySQL) HostNow() bool
- func (MySQL) InsertReturningID() bool
- func (MySQL) Like(col, ph string) string
- func (MySQL) Limit(offset, count int) string
- func (MySQL) LimitParams(offset, count string) string
- func (MySQL) Name() string
- func (MySQL) Now(precision int) string
- func (MySQL) NullsOrder(bool) string
- func (MySQL) Placeholder(int) string
- func (MySQL) Quote(ident string) string
- func (MySQL) Random() string
- func (MySQL) ReadExpr(col string, styles []string, ph func() string) (string, int)
- func (MySQL) ReadTime(col string, _ int) string
- func (MySQL) ReadUUID(col string) string
- func (MySQL) RestartIdentity(table, _ string) string
- func (MySQL) RowLock(mode string) (string, bool)
- func (MySQL) RowNumber(partition, orderBy string) string
- func (MySQL) TupleIn(cols []string, rows [][]string, negate bool) string
- func (MySQL) Upsert(_ []string, assigns string) string
- func (MySQL) ValueFunction(name string, arg, _ func() string) (string, bool)
- func (MySQL) WriteExpr(ph func() string, styles []string) (string, int)
- func (MySQL) WriteTime(ph string) string
- func (MySQL) WriteUUID(ph string) string
- type Postgres
- func (Postgres) ClockOperand(col string, _ int) string
- func (Postgres) ColumnFunction(name, col string, arg func(int) string) (string, bool)
- func (Postgres) ContainsBinary(col string, value func(string) string) string
- func (Postgres) DecodesStyle(string) bool
- func (Postgres) ForceIndex(string) string
- func (Postgres) Fulltext(cols []string, value func(string) string, boolean bool) (string, bool)
- func (Postgres) HandlesStyle(string) bool
- func (Postgres) HostNow() bool
- func (Postgres) InsertReturningID() bool
- func (Postgres) Like(col, ph string) string
- func (Postgres) Limit(offset, count int) string
- func (Postgres) LimitParams(offset, count string) string
- func (Postgres) Name() string
- func (Postgres) Now(int) string
- func (Postgres) NullsOrder(desc bool) string
- func (Postgres) Placeholder(n int) string
- func (Postgres) Quote(ident string) string
- func (Postgres) Random() string
- func (Postgres) ReadExpr(col string, _ []string, _ func() string) (string, int)
- func (Postgres) ReadTime(col string, precision int) string
- func (Postgres) ReadUUID(col string) string
- func (Postgres) RestartIdentity(table, column string) string
- func (Postgres) RowLock(mode string) (string, bool)
- func (Postgres) RowNumber(partition, orderBy string) string
- func (Postgres) TupleIn(cols []string, rows [][]string, negate bool) string
- func (Postgres) Upsert(conflict []string, assigns string) string
- func (Postgres) ValueFunction(name string, arg, now func() string) (string, bool)
- func (Postgres) WriteExpr(ph func() string, _ []string) (string, int)
- func (Postgres) WriteTime(ph string) string
- func (Postgres) WriteUUID(ph string) string
- type SQLite
- func (SQLite) ClockOperand(col string, precision int) string
- func (SQLite) ColumnFunction(name, col string, arg func(int) string) (string, bool)
- func (SQLite) ContainsBinary(col string, value func(string) string) string
- func (SQLite) DecodesStyle(string) bool
- func (SQLite) ForceIndex(name string) string
- func (SQLite) Fulltext([]string, func(string) string, bool) (string, bool)
- func (SQLite) HandlesStyle(string) bool
- func (SQLite) HostNow() bool
- func (SQLite) InsertReturningID() bool
- func (SQLite) Like(col, ph string) string
- func (SQLite) Limit(offset, count int) string
- func (SQLite) LimitParams(offset, count string) string
- func (SQLite) Name() string
- func (SQLite) Now(int) string
- func (SQLite) NullsOrder(bool) string
- func (SQLite) Placeholder(int) string
- func (SQLite) Quote(ident string) string
- func (SQLite) Random() string
- func (SQLite) ReadExpr(col string, _ []string, _ func() string) (string, int)
- func (SQLite) ReadTime(col string, _ int) string
- func (SQLite) ReadUUID(col string) string
- func (SQLite) RestartIdentity(table, column string) string
- func (SQLite) RowLock(mode string) (string, bool)
- func (SQLite) RowNumber(partition, orderBy string) string
- func (SQLite) TupleIn(cols []string, rows [][]string, negate bool) string
- func (SQLite) Upsert(conflict []string, assigns string) string
- func (SQLite) ValueFunction(name string, arg, now func() string) (string, bool)
- func (SQLite) WriteExpr(ph func() string, _ []string) (string, int)
- func (SQLite) WriteTime(ph string) string
- func (SQLite) WriteUUID(ph string) string
Constants ¶
This section is empty.
Variables ¶
var ColumnFunctionArity = map[string]int{
"day_of_week": 0, "year": 0, "month": 0, "date": 0,
}
ColumnFunctionArity is the number of function arguments (not counting the compared value) each column function takes.
var ColumnFunctionTypes = map[string][]string{
"day_of_week": {"date", "datetime"},
"year": {"date", "datetime"},
"month": {"date", "datetime"},
"date": {"date", "datetime"},
}
ColumnFunctionTypes lists the column types each ORM column function accepts.
var ValueFunctionUnits = map[string]string{
"seconds_ago": "second", "minutes_ago": "minute", "hours_ago": "hour", "days_ago": "day", "months_ago": "month",
"seconds_later": "second", "minutes_later": "minute", "hours_later": "hour", "days_later": "day", "months_later": "month",
}
ValueFunctionUnits maps relative value functions to their interval unit.
Functions ¶
func IsValueFunction ¶
IsValueFunction reports whether name is a value function.
Types ¶
type Dialect ¶
type Dialect interface {
Name() string
// Quote an identifier.
Quote(ident string) string
// Placeholder for the n-th (1-based) bind.
Placeholder(n int) string
// Like renders the case-insensitive col LIKE pattern of contains.
Like(col, ph string) string
// Limit renders LIMIT/OFFSET.
Limit(offset, count int) string
// LimitParams renders a paged read whose offset and count are bound placeholders.
LimitParams(offset, count string) string
// ForceIndex renders an index hint or "" when unsupported.
ForceIndex(name string) string
// RowNumber renders ROW_NUMBER() OVER (PARTITION BY p ORDER BY o).
RowNumber(partition, orderBy string) string
// InsertReturningID reports whether INSERT … RETURNING pk is used (else last insert id).
InsertReturningID() bool
// Upsert renders the ON DUPLICATE/ON CONFLICT clause for the given conflict columns and assignments.
Upsert(conflict []string, assigns string) string
// ReadExpr wraps SQL-side stages for a style pipeline and returns the bind count.
ReadExpr(col string, styles []string, ph func() string) (string, int)
// WriteExpr wraps a bound value for a style pipeline on write.
WriteExpr(ph func() string, styles []string) (string, int)
// ReadTime reads a time(p) column as its value text `HH:MM:SS` with exactly p
// fraction digits, which the database writes (MySQL CAST AS CHAR, PostgreSQL
// to_char); SQLite stores that text.
ReadTime(col string, precision int) string
// WriteTime binds a time(p) value as its text: PostgreSQL casts the text to time.
WriteTime(ph string) string
// ReadUUID reads a uuid column as its text: PostgreSQL casts the uuid to text.
ReadUUID(col string) string
// WriteUUID binds a uuid value as its text: PostgreSQL casts the text to uuid.
WriteUUID(ph string) string
// Now renders the database clock that is written to a column, with precision fractional digits:
// MySQL uses CURRENT_TIMESTAMP(p) if p > 0, and CURRENT_TIMESTAMP otherwise.
Now(precision int) string
// HandlesStyle reports whether the write applies the codec stage in this dialect's SQL
// (MySQL: ip). The other stages, including hex, are applied by the executor.
HandlesStyle(style string) bool
// DecodesStyle reports whether the read undoes the codec stage in this dialect's SQL (MySQL: ip).
// No dialect undoes hex in SQL: UNHEX accepts odd lengths and returns NULL for cells with spaces,
// so the executor reads it correctly with HostDecode (docs/spec/codec.md).
DecodesStyle(style string) bool
// HostNow reports that the clock the ORM writes comes from the executor (a `now`
// slot truncated to the column's fraction digits): SQLite has no sub-second clock
// function, and a PostgreSQL clock rounds into timestamp(p < 6)
// (postgres.now.precision_rounds). The update time, soft deletion and every omitted
// `default now` column of an insert bind the slot (docs/spec/protocol.md "Clock").
HostNow() bool
// ClockOperand is a datetime(p) column as it compares with the six-digit clock of a
// value function: SQLite compares text, so a column with p < 6 is extended with
// zeros to six fraction digits; MySQL and PostgreSQL compare values.
ClockOperand(col string, precision int) string
// RowLock renders a row lock suffix. An empty suffix with true means the
// executor owns a portable adapter-level lock implementation.
RowLock(mode string) (string, bool)
// ColumnFunction renders an ORM column function applied to col; arg(i)
// returns a new placeholder bound to the i-th function argument.
ColumnFunction(name, col string, arg func(int) string) (string, bool)
// ValueFunction renders an ORM value function; arg returns a placeholder
// for the interval amount and now binds the executor clock. Both are called
// in SQL text order.
ValueFunction(name string, arg, now func() string) (string, bool)
// ContainsBinary renders a case-sensitive substring match; value returns a
// placeholder whose bound value gets the named transform.
ContainsBinary(col string, value func(transform string) string) string
// Fulltext renders a full-text match of the columns cols against value, in the boolean mode when boolean is set; value
// returns a placeholder whose bound value gets the named transform. ok is false when the dialect has no full-text search.
Fulltext(cols []string, value func(transform string) string, boolean bool) (sql string, ok bool)
// TupleIn renders a multi-column IN or NOT IN list.
TupleIn(cols []string, rows [][]string, negate bool) string
// Random renders the random ordering function.
Random() string
// NullsOrder renders the clause that sorts NULL before every value ascending and after every value descending:
// MySQL and SQLite do so natively and render nothing, PostgreSQL sorts NULL last ascending and needs it.
NullsOrder(desc bool) string
// RestartIdentity is the statement that restarts a table's identity column from the value after the largest key.
// If the table is empty, the next key is 1.
RestartIdentity(table, column string) string
}
type MySQL ¶
type MySQL struct{}
MySQL is the primary dialect. Style expressions are defined to preserve the stored byte representation AES and hex are host-side; IP packing remains SQL-side.
func (MySQL) ColumnFunction ¶
func (MySQL) ContainsBinary ¶
ContainsBinary renders plain LIKE: every orm character column is utf8mb4_0900_bin, under which LIKE compares code points (probe mysql.like.binary_collation_code_point), and LIKE BINARY is deprecated since MySQL 8.0.27.
func (MySQL) DecodesStyle ¶
func (MySQL) ForceIndex ¶
func (MySQL) Fulltext ¶ added in v0.0.19
Fulltext renders MATCH … AGAINST; the boolean mode binds the value through the transform fulltext_boolean (DIA-6).
func (MySQL) HandlesStyle ¶
AES is host-side so row version metadata can select the key before decode, and hex is host-side so every dialect writes and reads the same text (docs/spec/dialects.md, Rules that keep the three databases identical). ip remains SQL-side: INET6_ATON packs the address into the binary column.
func (MySQL) InsertReturningID ¶
func (MySQL) Like ¶
Like folds the ASCII letters of both operands to lower case and leaves every other character as it is, so LIKE under the binary collation utf8mb4_0900_bin matches as PostgreSQL ILIKE under "C" and SQLite LIKE do (the probes mysql.like.binary_collation_case_sensitive and mysql.like.ascii_fold_replace).
func (MySQL) LimitParams ¶ added in v0.0.19
func (MySQL) NullsOrder ¶
func (MySQL) Placeholder ¶
func (MySQL) ReadExpr ¶
ReadExpr applies SQL-side stages. AES is handled by the executor so it can select the key from the row's version metadata.
func (MySQL) RestartIdentity ¶
RestartIdentity: InnoDB sets AUTO_INCREMENT to the largest column value if that is at most it, and otherwise to that largest value plus 1; since 1 is always the value after the largest key, DDL commits an open transaction.
func (MySQL) ValueFunction ¶
type Postgres ¶
type Postgres struct{}
Postgres: "quoted" identifiers, $n placeholders, ILIKE for the case-insensitive LIKE MySQL gives by collation, ON CONFLICT upserts with RETURNING ids. AES and HEX have no SQL-side stage here: those styles stay client-side (host AES, S6).
func (Postgres) ClockOperand ¶ added in v0.0.19
func (Postgres) ColumnFunction ¶
func (Postgres) ContainsBinary ¶
func (Postgres) DecodesStyle ¶
func (Postgres) ForceIndex ¶
func (Postgres) Fulltext ¶ added in v0.0.19
Fulltext renders a simple-configuration tsvector match of the columns; the boolean mode uses websearch_to_tsquery (DIA-6).
func (Postgres) HandlesStyle ¶
HandlesStyle is false: the packed bytes for the bytea column, including the ip stage, are made by the executor.
func (Postgres) InsertReturningID ¶
func (Postgres) LimitParams ¶ added in v0.0.19
func (Postgres) NullsOrder ¶
func (Postgres) Placeholder ¶
func (Postgres) RestartIdentity ¶
RestartIdentity: sets the identity sequence to the largest key plus 1 and sets is_called to false, so that the next nextval returns that value. The first argument of pg_get_serial_sequence is read as an identifier, so it is the quoted table name; the second argument is the column name as is.
func (Postgres) ValueFunction ¶
ValueFunction binds the executor clock on PostgreSQL, so one statement has one clock: now() is the transaction start and statement_timestamp() the statement start (postgres.now.transaction_start).
type SQLite ¶
type SQLite struct{}
SQLite (3.35+ for RETURNING, 3.25+ for window functions). No fulltext outside FTS5 virtual tables, so `match` is rejected at compile time rather than approximated. Every style stage is client-side here (host AES, packed inet).
func (SQLite) ClockOperand ¶ added in v0.0.19
ClockOperand extends a datetime(p < 6) text to six fraction digits, so it compares with the six-digit clock as the value it is: `col || '.000000'` for p = 0 and the missing zeros for 0 < p < 6.
func (SQLite) ColumnFunction ¶
func (SQLite) ContainsBinary ¶
ContainsBinary uses instr because SQLite LIKE ignores case for ASCII.
func (SQLite) DecodesStyle ¶
func (SQLite) ForceIndex ¶
func (SQLite) Fulltext ¶ added in v0.0.19
Fulltext reports no full-text search: SQLite has no full-text index on a table (DIA-187).
func (SQLite) HandlesStyle ¶
func (SQLite) InsertReturningID ¶
func (SQLite) LimitParams ¶ added in v0.0.19
func (SQLite) NullsOrder ¶
func (SQLite) Placeholder ¶
func (SQLite) RestartIdentity ¶
RestartIdentity: the next key of an AUTOINCREMENT table is the seq in sqlite_sequence plus 1, so seq is set to the largest key. A table that has not yet received rows has no sqlite_sequence row, so the next key is already the one after the largest key.
func (SQLite) RowLock ¶
SQLite has no row-lock clause. Each executor implements the common lock modes with an ORM-owned transaction-scoped lock row; the SQL suffix remains empty because the physical lock is acquired by the adapter.
func (SQLite) ValueFunction ¶
ValueFunction binds the executor clock on SQLite and applies the interval with datetime modifiers; `floor` keeps the last valid day of the month. datetime returns seconds, so the relative form appends six fractional digits from the second clock slot. Within one statement the two slots are equal.
Source Files