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
- Variables
- func Register(driver string, factory func() Dialect)
- type AlterTableQuery
- type AlterTableQueryBuilder
- type Column
- type ColumnDefinition
- type Condition
- type CreateTableQuery
- type CreateTableQueryBuilder
- type DataType
- type DataTyper
- type DeleteQuery
- type DeleteQueryBuilder
- type Dialect
- type DropTableQuery
- type DropTableQueryBuilder
- type Features
- type ForUpdate
- type ForeignKey
- type FunctionCall
- type Index
- type InsertQuery
- type InsertQueryBuilder
- type Join
- type Limit
- type MultiQuery
- type MultiQueryBuilder
- type MultiQueryBuilderImpl
- func (b *MultiQueryBuilderImpl) AddAlterTableQuery(q *AlterTableQuery) *MultiQueryBuilderImpl
- func (b *MultiQueryBuilderImpl) AddCreateTableQuery(q *CreateTableQuery) *MultiQueryBuilderImpl
- func (b *MultiQueryBuilderImpl) AddDeleteQuery(q *DeleteQuery) *MultiQueryBuilderImpl
- func (b *MultiQueryBuilderImpl) AddDropTableQuery(q *DropTableQuery) *MultiQueryBuilderImpl
- func (b *MultiQueryBuilderImpl) AddInsertQuery(q *InsertQuery) *MultiQueryBuilderImpl
- func (b *MultiQueryBuilderImpl) AddSelectQuery(q *SelectQuery) *MultiQueryBuilderImpl
- func (b *MultiQueryBuilderImpl) AddUpdateQuery(q *UpdateQuery) *MultiQueryBuilderImpl
- func (b *MultiQueryBuilderImpl) MultiQuery(q *UpdateQuery) []MultiQuery
- type OrderColumn
- type QueryBuilder
- type RawQuery
- type RawString
- type Select
- type SelectQuery
- type UpdateQuery
- type UpdateQueryBuilder
Constants ¶
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 ¶
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"} )
var ErrNotRegistered = errors.New("no dialect registered")
ErrNotRegistered is returned by New when the given driver name has not been registered with Register.
Functions ¶
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 ¶
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 ¶
DataType is a canonical, database-independent column type. Size optionally carries a length for types that support it, such as string.
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 ¶
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.
type DropTableQuery ¶
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 ForeignKey ¶
ForeignKey describes a FOREIGN KEY constraint. Columns are the local columns, and ForeignTable with ForeignColumns is the referenced table.
type FunctionCall ¶
FunctionCall is a SQL function applied to Arguments, for example "count" with arguments "*".
type Index ¶
Index describes a CREATE INDEX statement on the columns of a table. Unique makes it a UNIQUE index.
type InsertQuery ¶
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 ¶
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 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 ¶
func (b *MultiQueryBuilderImpl) AddDeleteQuery(q *DeleteQuery) *MultiQueryBuilderImpl
AddDeleteQuery appends a DELETE query to the batch.
func (*MultiQueryBuilderImpl) AddDropTableQuery ¶
func (b *MultiQueryBuilderImpl) AddDropTableQuery(q *DropTableQuery) *MultiQueryBuilderImpl
AddDropTableQuery appends a DROP TABLE query to the batch.
func (*MultiQueryBuilderImpl) AddInsertQuery ¶
func (b *MultiQueryBuilderImpl) AddInsertQuery(q *InsertQuery) *MultiQueryBuilderImpl
AddInsertQuery appends an INSERT query to the batch.
func (*MultiQueryBuilderImpl) AddSelectQuery ¶
func (b *MultiQueryBuilderImpl) AddSelectQuery(q *SelectQuery) *MultiQueryBuilderImpl
AddSelectQuery appends a SELECT query to the batch.
func (*MultiQueryBuilderImpl) AddUpdateQuery ¶
func (b *MultiQueryBuilderImpl) AddUpdateQuery(q *UpdateQuery) *MultiQueryBuilderImpl
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 ¶
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 ¶
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 ¶
JoinQueries combines several RawQueries into a single multi-statement query, separating each statement with a space and semicolon and concatenating the bindings in order.
type RawString ¶
type RawString string
RawString is a raw SQL fragment that can be used as a value in conditions.
type Select ¶
Select is the SELECT clause of a query: an optional DISTINCT followed by the columns to select.
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.
Source Files
¶
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. |