dialect

Documentation

Overview

Package dialect defines the SQL-dialect contract liteorm's core depends on. It is driver-free: each backend implements Dialect; the internal query builder consumes it. Kept deliberately lean (the hot SQL-generation methods only); optional SQL capabilities are expressed as Feature flags rather than interface methods.

Index

• type AllColumnsIntrospector
• type ColumnIntrospector
• type Dialect
• type Feature
  • func (f Feature) Has(bits Feature) bool
• type Field
• type ForeignKeyIntrospector
• type IndexIntrospector
• type Introspector
• type SearchKind
• type SearchProvisioner
• type SearchRowSyncer
• type SearchSpec
  • func (s SearchSpec) RowidKeyed() bool
• type SearchStmt
• type TableLister

Types

type AllColumnsIntrospector

type AllColumnsIntrospector interface {
	AllColumnsFullQuery() string
}

AllColumnsIntrospector returns rich column metadata for EVERY base table of the connected schema in a single query — so a schema browser scales to hundreds of tables without one round-trip per table. AllColumnsFullQuery returns SQL yielding the ColumnIntrospector five-column shape prefixed with the table name, the FIXED six-column shape:

tbl     TEXT     -- table name
name    TEXT     -- column name
type    TEXT     -- declared/affinity type
notnull INTEGER  -- 1 if NOT NULL, else 0
dflt    TEXT     -- default expression, or NULL
pk      INTEGER  -- 0 if not part of the primary key, else its 1-based position

type ColumnIntrospector

type ColumnIntrospector interface {
	ColumnsFullQuery(table string) string
}

ColumnIntrospector is an optional capability returning richer per-column metadata than Introspector. ColumnsFullQuery returns SQL yielding, per column, the FIXED five-column shape:

name    TEXT     -- column name
type    TEXT     -- declared/affinity type
notnull INTEGER  -- 1 if NOT NULL, else 0
dflt    TEXT     -- default expression, or NULL
pk      INTEGER  -- 0 if not part of the primary key, else its 1-based position

so a single driver-neutral scan reads it on every dialect that implements it.

type Dialect

type Dialect interface {
	Name() string
	Features() Feature
	// AppendPlaceholder writes the bind var for parameter #n (1-based) into b.
	AppendPlaceholder(b []byte, n int) []byte
	// QuoteIdent writes a safely-quoted identifier, escaping the quote char.
	QuoteIdent(b []byte, ident string) []byte
	// ColumnType returns the SQL column type for a planned column.
	ColumnType(f *Field) string
	// AutoIncrement returns the autoincrement/identity DDL fragment, or "".
	AutoIncrement(f *Field) string
	// DefaultSchema is the implicit schema name ("public"/"main"/"dbo"/"").
	DefaultSchema() string
}

Dialect is the contract each backend implements. AppendPlaceholder is an explicit, position-aware bind-var writer (sqlite/mysql -> "?", pg -> "$n", mssql -> "@pN"), so a generics-first builder emits the right placeholder directly with no rewrite pass.

type Feature

type Feature uint64

Feature is a bitset of optional SQL capabilities a Dialect advertises: a dialect opts into what it supports instead of growing the interface.

const (
	// FeatReturning: RETURNING clause at statement end (Postgres, SQLite).
	FeatReturning Feature = 1 << iota
	// FeatOutput: T-SQL OUTPUT clause instead of RETURNING (MSSQL). Unlike
	// RETURNING (which trails the statement), OUTPUT is positional — after the
	// column list on INSERT, after SET on UPDATE, after the table on DELETE.
	FeatOutput
	// FeatInsertOnConflict: ON CONFLICT (...) DO UPDATE upsert (Postgres, SQLite).
	FeatInsertOnConflict
	// FeatOnDuplicateKey: ON DUPLICATE KEY UPDATE upsert (MySQL).
	FeatOnDuplicateKey
	// FeatMerge: MERGE-based upsert (MSSQL).
	FeatMerge
	// FeatOffsetFetch: OFFSET .. FETCH pagination instead of LIMIT/OFFSET (MSSQL).
	FeatOffsetFetch
	// FeatCTE: WITH common table expressions (incl. recursive). All four dialects
	// support them.
	FeatCTE
	// FeatJSON: native JSON/JSONB column type.
	FeatJSON
	// FeatArray: native array column type (Postgres).
	FeatArray
	// FeatIdentity: IDENTITY/SERIAL/AUTO_INCREMENT autoincrement.
	FeatIdentity
	// FeatLastInsertID: driver returns a usable LastInsertId (SQLite, MySQL).
	FeatLastInsertID
	// FeatJSONB: Postgres binary-JSON containment operators (@>, <@) — narrower
	// than FeatJSON, which only means a native JSON type exists (SQLite/MySQL
	// have JSON but not these operators).
	FeatJSONB
	// FeatRowLocking: SELECT ... FOR UPDATE / FOR SHARE, with optional SKIP LOCKED
	// / NOWAIT (Postgres, MySQL 8). SQLite has no row locks; MSSQL uses table hints
	// instead, so neither advertises this.
	FeatRowLocking
	// FeatDistinctOn: SELECT DISTINCT ON (cols) (Postgres only).
	FeatDistinctOn
	// FeatIntersectExcept: INTERSECT / EXCEPT compound set operators (SQLite,
	// Postgres, MSSQL; MySQL only since 8.0.31, so it is left off there).
	FeatIntersectExcept
	// FeatLateral: LATERAL joins — a joined subquery may reference columns from
	// earlier FROM items (Postgres; MySQL 8.0.14+ uses the same keyword but is left
	// off conservatively).
	FeatLateral
	// FeatUpdateFrom: correlated UPDATE … FROM <source> WHERE … (Postgres, SQLite
	// 3.33+, and T-SQL's UPDATE … FROM on MSSQL). MySQL uses UPDATE … JOIN instead,
	// so it is left off.
	FeatUpdateFrom
)

func (Feature) Has

func (f Feature) Has(bits Feature) bool

Has reports whether f includes all of the given feature bits.

type Field

type Field struct {
	Name          string
	GoType        string // canonical Go type, e.g. "int64", "string", "time.Time"
	Nullable      bool
	PrimaryKey    bool
	AutoIncrement bool
	Size          int
}

Field describes a planned column for type mapping and DDL generation. Name identifies the column; the remaining fields drive ColumnType/AutoIncrement.

type ForeignKeyIntrospector

type ForeignKeyIntrospector interface {
	ForeignKeysQuery() string
}

ForeignKeyIntrospector returns the foreign keys of EVERY base table of the connected schema in a single query (so model-less schema browsers get foreign-key navigation without per-table queries). ForeignKeysQuery returns SQL yielding one row per foreign-key column, the FIXED four-column shape:

tbl        TEXT  -- the referencing table
from_col   TEXT  -- the referencing column in tbl
ref_table  TEXT  -- the referenced table
ref_col    TEXT  -- the referenced column

type IndexIntrospector

type IndexIntrospector interface {
	IndexesQuery(table string) string
}

IndexIntrospector is an optional capability (checked separately from Introspector) for listing an existing table's index names. IndexesQuery returns SQL yielding one row per index with a single `name` column. It powers auto-migrate's additive index sync: an index a model gained is created, but a missing index name is simply created — dropping one is left to a reviewable migration.

type Introspector

type Introspector interface {
	ColumnsQuery(table string) string
}

Introspector is implemented by dialects that can describe an existing table's columns. ColumnsQuery returns SQL yielding rows of (name, type). It powers auto-migrate's additive column sync and the diff→migration generator.

type SearchKind

type SearchKind int

SearchKind distinguishes the sidecar kinds a SearchProvisioner builds.

const (
	// SearchFullText is a full-text sidecar (e.g. SQLite FTS5).
	SearchFullText SearchKind = iota
	// SearchVector is a nearest-neighbour vector sidecar (e.g. sqlite-vec vec0).
	SearchVector
)

type SearchProvisioner

type SearchProvisioner interface {
	ProvisionSearchSQL(spec SearchSpec) ([]string, error)
	DropSearchSQL(spec SearchSpec) ([]string, error)
}

SearchProvisioner is an optional capability: a backend that supports search sidecars (full-text / vector) returns the DDL to create or drop one. The methods only build SQL — the caller (orm's AutoMigrate) executes it — so the dialect stays free of any session or orm dependency. Creation DDL must be idempotent (IF NOT EXISTS); drop DDL must tolerate a missing sidecar.

type SearchRowSyncer

type SearchRowSyncer interface {
	UpsertSearchRowSQL(spec SearchSpec, key any, value any) ([]SearchStmt, error)
	DeleteSearchRowSQL(spec SearchSpec, key any) ([]SearchStmt, error)
}

SearchRowSyncer is an optional capability for keeping a hook-synced sidecar in step from the ORM write path — used when a sidecar is not trigger-synced (e.g. a vector whose embedding is sidecar-only, not a stored base column). value carries the indexed payload for the row: a vector embedding as []float32, or a pre-encoded []byte.

type SearchSpec

type SearchSpec struct {
	Kind     SearchKind
	Name     string   // sidecar table name
	Table    string   // base table the sidecar mirrors
	Columns  []string // indexed columns (text columns for full-text; the embedding column for vector)
	PKColumn string   // base-table primary-key column the sidecar is keyed by
	PKType   string   // canonical Go type of the PK ("int64", "string", …)
	Sync     string   // resolved sync strategy: "triggers" or "hooks"

	// Full-text options.
	Tokenizer string
	Prefix    []int
	Detail    string // "full" | "column" | "none"
	Content   string // "external" (default) | "intable" | "contentless"

	// Vector options.
	Dim      int
	Metric   string // distance token: "l2" | "cosine" | "l1" | "hamming"
	Encoding string // "float32" (default) | "int8" | "bit"
}

SearchSpec is a dialect-neutral description of one search sidecar, resolved from a model's declared index (columns already mapped to their SQL names). It is the hand-off type between the orm front-end and a SearchProvisioner backend, so the dialect package needs no dependency on orm.

func (SearchSpec) RowidKeyed

func (s SearchSpec) RowidKeyed() bool

RowidKeyed reports whether the sidecar is keyed by the table's implicit integer rowid — true for any integer primary key (int, int32, uint, …, not just int64), since SQLite aliases an integer PK to the rowid. A non-integer PK (e.g. string) is keyed by an explicit key column instead.

type SearchStmt

type SearchStmt struct {
	SQL  string
	Args []any
}

SearchStmt is one SQL statement plus its bind arguments, produced by a SearchRowSyncer to maintain a sidecar for a single row.

type TableLister

type TableLister interface {
	TablesQuery() string
}

TableLister is an optional capability for enumerating the base tables of the connected database (default schema). TablesQuery returns SQL yielding one row per table with a single `name` column. It powers schema browsers and admin tooling such as liteorm.org/studio.