dialects

package
v0.26.0 Latest Latest
Warning

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

Go to latest
Published: Sep 13, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package dialects defines the query ASTs that describe SQL statements and the Dialect interface that renders them into RawQueries.

The query structs (SelectQuery, InsertQuery, UpdateQuery, DeleteQuery, CreateTableQuery, DropTableQuery, and AlterTableQuery) are plain data with no database-specific knowledge. They are produced by the higher-level builder, schema, migrate, and model packages and encoded by a Dialect into a RawQuery, which pairs a SQL string with its positional bind values.

The generic package provides a database-agnostic encoder built on a small Core interface, and the sqlite, mysql, and postgres packages implement that interface for their respective databases. Each registers itself with Register so New can construct the right dialect for a database driver name:

d, err := dialects.New("sqlite3")
query, err := d.EncodeSelectQuery(q)

MultiQuery and EncodeMultiQuery batch several queries together so they can be sent to the database as one multi-statement SQL string.

Index

Constants

View Source
const (
	// ForUpdateDefault locks the selected rows, waiting for other transactions
	// that hold the locks to commit.
	ForUpdateDefault = ForUpdate("default")
	// ForUpdateSkipLocked locks the selected rows but skips any rows already
	// locked by other transactions.
	ForUpdateSkipLocked = ForUpdate("skip-locked")
)

Variables

View Source
var (
	// DataTypeBlob is a binary large object type.
	DataTypeBlob = DataType{Name: "blob"}
	// DataTypeString is a variable length string type. Use Size to set the
	// maximum length where the database supports it.
	DataTypeString = DataType{Name: "string"}
	// DataTypeText is a long string type.
	DataTypeText = DataType{Name: "text"}
	// DataTypeEnum is an enumerated string type.
	DataTypeEnum = DataType{Name: "enum"}

	// DataTypeBoolean is a boolean type.
	DataTypeBoolean = DataType{Name: "bool"}

	// DataTypeDate is a calendar date type.
	DataTypeDate = DataType{Name: "date"}
	// DataTypeDateTime is a date and time type.
	DataTypeDateTime = DataType{Name: "date-time"}

	// DataTypeFloat32 is a 32-bit floating point type.
	DataTypeFloat32 = DataType{Name: "float32"}
	// DataTypeFloat64 is a 64-bit floating point type.
	DataTypeFloat64 = DataType{Name: "float64"}

	// DataTypeInt8 is an 8-bit signed integer type.
	DataTypeInt8 = DataType{Name: "int8"}
	// DataTypeInt16 is a 16-bit signed integer type.
	DataTypeInt16 = DataType{Name: "int16"}
	// DataTypeInt32 is a 32-bit signed integer type.
	DataTypeInt32 = DataType{Name: "int32"}
	// DataTypeInt64 is a 64-bit signed integer type.
	DataTypeInt64 = DataType{Name: "int64"}

	// DataTypeUInt8 is an 8-bit unsigned integer type.
	DataTypeUInt8 = DataType{Name: "uint8"}
	// DataTypeUInt16 is a 16-bit unsigned integer type.
	DataTypeUInt16 = DataType{Name: "uint16"}
	// DataTypeUInt32 is a 32-bit unsigned integer type.
	DataTypeUInt32 = DataType{Name: "uint32"}
	// DataTypeUInt64 is a 64-bit unsigned integer type.
	DataTypeUInt64 = DataType{Name: "uint64"}

	// DataTypeJSON is a JSON document type.
	DataTypeJSON = DataType{Name: "json"}
)
View Source
var ErrNotRegistered = errors.New("no dialect registered")

ErrNotRegistered is returned by New when the given driver name has not been registered with Register.

Functions

func Register

func Register(driver string, factory func() Dialect)

Register associates a dialect factory with a database driver name. Concrete dialect packages call Register (typically from their init function) so that New can construct them by name.

Types

type AlterTableQuery

type AlterTableQuery struct {
	Table         string
	DropColumns   []string
	ModifyColumns []ColumnDefinition
	AddColumns    []ColumnDefinition
	ForeignKeys   []ForeignKey
	Indexes       []Index
}

AlterTableQuery describes changes to a table: columns to drop, modify, or add, plus foreign keys and indexes to add.

type AlterTableQueryBuilder

type AlterTableQueryBuilder interface {
	AlterTableQuery() *AlterTableQuery
}

AlterTableQueryBuilder is implemented by anything that produces an AlterTableQuery.

type Column

type Column struct {
	Column   string
	Function *FunctionCall
	SubQuery QueryBuilder
	Raw      string

	As string
}

Column is an expression in a query: a column name, a function call, a subquery, or raw SQL. As is an optional alias.

type ColumnDefinition

type ColumnDefinition struct {
	Name               string
	Datatype           DataType
	Nullable           bool
	Primary            bool
	AutoIncrement      bool
	DefaultValue       any
	Unique             bool
	DefaultCurrentTime bool
}

ColumnDefinition describes a single column of a table: its name, data type, and constraints such as nullability, primary key, default value, and auto-increment. DefaultCurrentTime makes the default the current timestamp.

type Condition

type Condition struct {
	Column   Column
	Operator string
	Value    any
	Or       bool
}

Condition is a single predicate on a column or expression. Operator is a comparison such as "=" or "!=" and Value is the value compared against. Or joins the condition to the previous one with OR instead of AND.

type CreateTableQuery

type CreateTableQuery struct {
	IfNotExists bool
	Temporary   bool
	Table       string
	Columns     []ColumnDefinition
	PrimaryKeys []string
	ForeignKeys []ForeignKey
	Indexes     []Index
}

CreateTableQuery describes a CREATE TABLE statement, its columns, composite primary key and foreign keys, and any indexes to create alongside it.

type CreateTableQueryBuilder

type CreateTableQueryBuilder interface {
	CreateTableQuery() *CreateTableQuery
}

CreateTableQueryBuilder is implemented by anything that produces a CreateTableQuery.

type DataType

type DataType struct {
	Name string
	Size int
}

DataType is a canonical, database-independent column type. Size optionally carries a length for types that support it, such as string.

func (DataType) IsValid

func (d DataType) IsValid() bool

IsValid reports whether the DataType name is one of the known data type names.

type DataTyper

type DataTyper interface {
	DataType() DataType
}

DataTyper is implemented by types that report their own DataType. It must not be implemented on an interface.

type DeleteQuery

type DeleteQuery struct {
	Table  string
	Wheres []Condition
}

DeleteQuery describes a DELETE statement. Wheres selects the rows to delete.

type DeleteQueryBuilder

type DeleteQueryBuilder interface {
	DeleteQuery() *DeleteQuery
}

DeleteQueryBuilder is implemented by anything that produces a DeleteQuery.

type Dialect

type Dialect interface {
	EncodeSelectQuery(q *SelectQuery) (RawQuery, error)
	EncodeInsertQuery(q *InsertQuery) (RawQuery, error)
	EncodeUpdateQuery(q *UpdateQuery) (RawQuery, error)
	EncodeDeleteQuery(q *DeleteQuery) (RawQuery, error)
	EncodeCreateTableQuery(q *CreateTableQuery) (RawQuery, error)
	EncodeDropTableQuery(q *DropTableQuery) (RawQuery, error)
	EncodeAlterTableQuery(q *AlterTableQuery) (RawQuery, error)
	Features() Features
}

Dialect encodes dialect query ASTs into RawQueries.

func New

func New(driverName string) (Dialect, error)

New returns the dialect registered for driverName. It returns ErrNotRegistered wrapped if no dialect is registered for the name.

type DropTableQuery

type DropTableQuery struct {
	Table    string
	IfExists bool
}

DropTableQuery describes a DROP TABLE statement. IfExists drops the table without error if it does not exist.

type DropTableQueryBuilder

type DropTableQueryBuilder interface {
	DropTableQuery() *DropTableQuery
}

DropTableQueryBuilder is implemented by anything that produces a DropTableQuery.

type Features

type Features struct {
	// Returning indicates the dialect supports the RETURNING clause on INSERT,
	// UPDATE, and DELETE statements.
	Returning bool
}

Features describes the SQL capabilities supported by a dialect.

type ForUpdate

type ForUpdate string

ForUpdate is a row locking clause for SELECT statements.

type ForeignKey

type ForeignKey struct {
	Name           string
	Columns        []string
	ForeignTable   string
	ForeignColumns []string
}

ForeignKey describes a FOREIGN KEY constraint. Columns are the local columns, and ForeignTable with ForeignColumns is the referenced table.

type FunctionCall

type FunctionCall struct {
	Name      string
	Arguments string
}

FunctionCall is a SQL function applied to Arguments, for example "count" with arguments "*".

type Index

type Index struct {
	Name    string
	Table   string
	Columns []string
	Unique  bool
}

Index describes a CREATE INDEX statement on the columns of a table. Unique makes it a UNIQUE index.

type InsertQuery

type InsertQuery struct {
	Table     string
	Values    []map[string]any
	Returning []string
}

InsertQuery describes an INSERT statement. Values is a list of rows, each a map of column names to values, and Returning is the list of columns to return if the dialect supports RETURNING.

type InsertQueryBuilder

type InsertQueryBuilder interface {
	InsertQuery() *InsertQuery
}

InsertQueryBuilder is implemented by anything that produces an InsertQuery.

type Join

type Join struct {
	Direction  string
	Table      string
	Conditions []Condition
}

Join is a single join clause. Direction is a join keyword such as "LEFT" or "INNER", Table is the table being joined, and Conditions are the ON conditions.

type Limit

type Limit struct {
	Limit  int
	Offset int
}

Limit is the LIMIT and OFFSET of a query.

type MultiQuery

type MultiQuery struct {
	// contains filtered or unexported fields
}

MultiQuery holds exactly one query of any kind. It is created with the Add methods of MultiQueryBuilderImpl.

type MultiQueryBuilder

type MultiQueryBuilder interface {
	MultiQuery() []MultiQuery
}

MultiQueryBuilder is implemented by anything that produces a set of MultiQueries.

type MultiQueryBuilderImpl

type MultiQueryBuilderImpl struct {
	// contains filtered or unexported fields
}

MultiQueryBuilderImpl accumulates queries in order. Each Add method appends a query and returns the builder so calls can be chained.

func NewMultiQueryBuilder

func NewMultiQueryBuilder() *MultiQueryBuilderImpl

NewMultiQueryBuilder returns a new empty MultiQueryBuilderImpl.

func (*MultiQueryBuilderImpl) AddAlterTableQuery

func (b *MultiQueryBuilderImpl) AddAlterTableQuery(q *AlterTableQuery) *MultiQueryBuilderImpl

AddAlterTableQuery appends an ALTER TABLE query to the batch.

func (*MultiQueryBuilderImpl) AddCreateTableQuery

func (b *MultiQueryBuilderImpl) AddCreateTableQuery(q *CreateTableQuery) *MultiQueryBuilderImpl

AddCreateTableQuery appends a CREATE TABLE query to the batch.

func (*MultiQueryBuilderImpl) AddDeleteQuery

AddDeleteQuery appends a DELETE query to the batch.

func (*MultiQueryBuilderImpl) AddDropTableQuery

AddDropTableQuery appends a DROP TABLE query to the batch.

func (*MultiQueryBuilderImpl) AddInsertQuery

AddInsertQuery appends an INSERT query to the batch.

func (*MultiQueryBuilderImpl) AddSelectQuery

AddSelectQuery appends a SELECT query to the batch.

func (*MultiQueryBuilderImpl) AddUpdateQuery

AddUpdateQuery appends an UPDATE query to the batch.

func (*MultiQueryBuilderImpl) MultiQuery

func (b *MultiQueryBuilderImpl) MultiQuery(q *UpdateQuery) []MultiQuery

MultiQuery returns the queries that have been added to the batch.

type OrderColumn

type OrderColumn struct {
	Column     string
	Descending bool
}

OrderColumn is a single column in an ORDER BY clause. Descending makes the sort descending.

type QueryBuilder

type QueryBuilder interface {
	Query() *SelectQuery
}

QueryBuilder is implemented by anything that produces a SelectQuery, such as the query builders used as subqueries.

type RawQuery

type RawQuery struct {
	SQL      string
	Bindings []any
}

RawQuery is a SQL statement together with the positional bind values it needs.

func EncodeMultiQuery

func EncodeMultiQuery(d Dialect, queries []MultiQuery) (RawQuery, error)

EncodeMultiQuery encodes each query with the dialect and joins the results into a single multi-statement query with JoinQueries.

func JoinQueries

func JoinQueries(results []RawQuery) RawQuery

JoinQueries combines several RawQueries into a single multi-statement query, separating each statement with a space and semicolon and concatenating the bindings in order.

func Raw

func Raw(sql string, bindings ...any) RawQuery

Raw returns a RawQuery from a SQL string and its optional bind values.

type RawString

type RawString string

RawString is a raw SQL fragment that can be used as a value in conditions.

type Select

type Select struct {
	Distinct bool
	Columns  []Column
}

Select is the SELECT clause of a query: an optional DISTINCT followed by the columns to select.

func NewSelect

func NewSelect() Select

NewSelect returns a Select with its column slice initialized.

type SelectQuery

type SelectQuery struct {
	Select    Select
	From      string
	Joins     []Join
	Wheres    []Condition
	Havings   []Condition
	GroupBys  []string
	OrderBys  []OrderColumn
	Limit     Limit
	ForUpdate ForUpdate
}

SelectQuery describes a SELECT statement with its columns, source table, joins, conditions, grouping, ordering, limit, and locking clause.

func NewSelectQuery

func NewSelectQuery() SelectQuery

NewSelectQuery returns a SelectQuery with its slices initialized.

type UpdateQuery

type UpdateQuery struct {
	Table     string
	Values    map[string]any
	Returning []Column
	Wheres    []Condition
}

UpdateQuery describes an UPDATE statement. Values maps column names to their new values, Returning is the list of columns to return, and Wheres selects the rows to update.

type UpdateQueryBuilder

type UpdateQueryBuilder interface {
	UpdateQuery() *UpdateQuery
}

UpdateQueryBuilder is implemented by anything that produces an UpdateQuery.

Directories

Path Synopsis
Package generic provides a database-agnostic implementation of the dialects.Dialect interface.
Package generic provides a database-agnostic implementation of the dialects.Dialect interface.
Package mysql implements the dialects.Dialect interface for MySQL.
Package mysql implements the dialects.Dialect interface for MySQL.
Package postgres implements the dialects.Dialect interface for PostgreSQL.
Package postgres implements the dialects.Dialect interface for PostgreSQL.
Package sqlite implements the dialects.Dialect interface for SQLite.
Package sqlite implements the dialects.Dialect interface for SQLite.

Jump to

Keyboard shortcuts

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