Help us shape the future of Go! Take the 2026 Go Developer Survey

ir

package
v0.0.21 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package ir defines the wire form clients send (JSON, docs/spec/protocol.md) and validates it against the manifest. Validation is the only place the DSL's rules live; every client renders the same IR.

Index

Constants

View Source
const Version = 1

Variables

This section is empty.

Functions

func ConflictKey

func ConflictKey(ent *runtimemodel.Entity, set []Assign) (runtimemodel.Key, error)

ConflictKey returns the one key an insert with on_duplicate conflicts on. MySQL updates the row met on any unique key, while PostgreSQL and SQLite name one target and a meeting on another key is a unique violation, so no order of keys reproduces both: an upsert has exactly one key that can meet the inserted row, and the insert assigns every column of it. The candidates are the primary key, unless the insert leaves it out (an identity, or a key an IR executor assigns), and each unique key; a blind index column counts as assigned with its AES source.

func FunctionType

func FunctionType(name string, f *runtimemodel.Field) (string, bool)

FunctionType is the type of a column function's result on column f: the type of a parameter compared with it and of the output column it selects.

func IntervalType added in v0.0.19

func IntervalType(name string) string

IntervalType is the type of the interval of a relative time function: seconds take a fraction, the other units an integer.

func ItemConn added in v0.0.19

func ItemConn(item Item) string

ItemConn is the connector that joins an item to the item before it.

func OpAllowed

func OpAllowed(c *runtimemodel.Field, op string) bool

OpAllowed reports whether op is allowed for the field's type and codec.

func ParamUses

func ParamUses(m *runtimemodel.Model, r *Request) ([][]ParamUse, error)

ParamUses lists the uses of each parameter of a validated request, by parameter index: the compared or assigned column; a column function's result; i32, or f64 for seconds, for the interval of a relative time function; text for contains and contains_binary; the parent column for if_parent; the column for optimistic. An IR executor message writes each parameter in the form of its slot's type (docs/spec/protocol.md §5), so the client reads the type here.

func Validate

func Validate(m *runtimemodel.Model, r *Request) error

Validate checks an already-built request (in-process Go clients skip JSON).

Types

type Assign

type Assign struct {
	Column string `json:"column"`
	P      *int   `json:"p,omitempty"`
	Null   bool   `json:"null,omitempty"`
	PlusP  *int   `json:"plus_p,omitempty"`
	MinusP *int   `json:"minus_p,omitempty"`
}

Assign sets one column: exactly one of P (value), PlusP, MinusP, Null.

type ColFunc

type ColFunc struct {
	Column string `json:"column"`
	Fn     Func   `json:"fn"`
}

ColFunc applies a column function to a column of the query's entity.

type ColRef

type ColRef struct {
	Path   string `json:"path"`
	Column string `json:"column"`
}

ColRef points at a column on another entity in the same statement: Path is the relation path from the root ("" = root, "campaign", "campaign/service").

type Columns

type Columns struct {
	Mode   string             `json:"mode,omitempty"` // "" (default) | all | none
	Add    []string           `json:"add,omitempty"`
	Remove []string           `json:"remove,omitempty"`
	Fn     map[string]ColFunc `json:"fn,omitempty"`  // out name -> column function
	Sub    map[string]*Sub    `json:"sub,omitempty"` // out name -> scalar subquery
}

type Error

type Error struct {
	Code string `json:"code"`
	Msg  string `json:"msg"`
	// Cause is a driver error from the driver code, or the callback error of ROLLBACK and a rollback
	// error. It is not included in the JSON form.
	Cause error `json:"-"`
}

Error is a compile error with a stable code (docs/spec/errors.yaml).

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns Cause.

type Func

type Func struct {
	Name string `json:"name"`
	Ps   []int  `json:"ps,omitempty"`
}

Func names an ORM function and its bound arguments.

type Group

type Group struct {
	Conn string `json:"conn,omitempty"` // and | or
	// Not negates the whole nested group (`NOT (…)`). The top-level where and on groups are not negated.
	Not   bool   `json:"not,omitempty"`
	Items []Item `json:"items"`
}

Group is a parenthesised list. Conn joins the group to its previous sibling; the first item of a group has no connector.

type IfParent

type IfParent struct {
	Column string `json:"column"`
	P      int    `json:"p"`
}

type Item

type Item struct {
	Pred   *Pred      `json:"pred,omitempty"`
	Group  *Group     `json:"group,omitempty"`
	Joined *JoinedRef `json:"joined,omitempty"`
}

Item is exactly one of Pred, Group, Joined.

type Join

type Join struct {
	Rel   string `json:"rel"`
	Kind  string `json:"kind"` // inner | left
	Query *Query `json:"query"`
	Left  string `json:"left,omitempty"`
	Right string `json:"right,omitempty"`
}

Join adds a child table to the statement. Rel is the join name, and Left is the parent column, and Right is the child column.

type JoinedRef

type JoinedRef struct {
	Conn string `json:"conn,omitempty"`
	Join string `json:"join"`
}

JoinedRef places the where conditions of the join named Join as a group.

type KeyPair

type KeyPair struct {
	Left  string `json:"left"`
	Right string `json:"right"`
}

KeyPair is one component of a relation key: the parent column Left and the child column Right are equal. A relation of a composite key holds one pair per component, in key order.

type Limit

type Limit struct {
	Offset  int  `json:"offset,omitempty"`
	Count   int  `json:"count,omitempty"`
	OffsetP *int `json:"offset_p,omitempty"`
	CountP  *int `json:"count_p,omitempty"`
}

type Optimist

type Optimist struct {
	Column string `json:"column"`
	P      int    `json:"p"`
}

type Order

type Order struct {
	Column string `json:"column,omitempty"`
	Desc   bool   `json:"desc,omitempty"`
	Random bool   `json:"random,omitempty"`
	Fn     *Func  `json:"fn,omitempty"` // column function applied to Column
}

type ParamUse

type ParamUse struct {
	Type   string
	Column *runtimemodel.Field
	// Assign marks the assignment of Column (set, rows, on_duplicate): a non-null column
	// refuses NULL.
	Assign bool
}

ParamUse is one slot that a request parameter fills: the slot's logical type, a dbspec type kind, and for a column slot the compared or assigned column with its precision, scale, length and nullability.

type Pred

type Pred struct {
	Conn   string   `json:"conn,omitempty"`
	Column string   `json:"column,omitempty"`
	Op     string   `json:"op,omitempty"`
	P      *int     `json:"p,omitempty"`     // single value
	Ps     []int    `json:"ps,omitempty"`    // in, not_in, between, tuple rows
	Ref    *ColRef  `json:"ref,omitempty"`   // *_col operators
	Fn     *Func    `json:"fn,omitempty"`    // column function applied to Column
	Value  *Func    `json:"value,omitempty"` // value function compared with Column
	Cols   []string `json:"cols,omitempty"`  // tuple_in, tuple_not_in columns; Ps holds the rows in order
	Sub    *Sub     `json:"sub,omitempty"`   // in, not_in subquery
}

Values never travel inside the tree: a predicate references parameters by index (P, Ps) into the request's Params list. The plan is therefore value-independent and executors fill placeholders from their own Params.

type Query

type Query struct {
	Entity    string      `json:"entity"`
	Columns   *Columns    `json:"columns,omitempty"`
	On        *Group      `json:"on,omitempty"` // join children only
	Where     *Group      `json:"where,omitempty"`
	Joins     []*Join     `json:"joins,omitempty"`
	Relations []*Relation `json:"relations,omitempty"`
	Order     []Order     `json:"order,omitempty"`
	GroupBy   []string    `json:"group_by,omitempty"`
	Limit     *Limit      `json:"limit,omitempty"`
	ForceIdx  string      `json:"force_index,omitempty"`
	Lock      string      `json:"lock,omitempty"` // update, share, update_nowait or share_nowait; root row-select only

	// Relation-child options.
	KeyBy           string    `json:"key_by,omitempty"`
	Flatten         bool      `json:"flatten,omitempty"`
	LimitPerParent  int       `json:"limit_per_parent,omitempty"`
	IfParent        *IfParent `json:"if_parent,omitempty"`
	NoCascadeDelete bool      `json:"no_cascade_delete,omitempty"` // deleteCascade stops at this relation
}

Query is the shape shared by the root, join children and relation children.

func CloneQuery

func CloneQuery(q Query) Query

CloneQuery copies every mutable part of a query tree before it is attached to another request. Parameter values live outside this tree.

type Relation

type Relation struct {
	Rel   string    `json:"rel"`
	Query *Query    `json:"query"`
	Kind  string    `json:"kind,omitempty"` // one | many
	Keys  []KeyPair `json:"keys,omitempty"`
}

Relation reads rows with a separate statement. Rel is the result name, and Left, Right, Kind decide the key and the kind.

type Request

type Request struct {
	IRVersion int `json:"ir_version"`
	// ManifestHash is the manifestHash of the generated code that made the request.
	ManifestHash string `json:"manifest_hash"`
	Kind         string `json:"kind"` // one all count group_count sum avg paginate insert update delete restore restart_identity
	Query
	// Load means insert loads a row under the stored key as it is: it takes the value of the identity column,
	// and requires that value if the table has an identity. It is not used with on_duplicate.
	Load        bool     `json:"load,omitempty"`
	Set         []Assign `json:"set,omitempty"`
	OnDuplicate []Assign `json:"on_duplicate,omitempty"` // insert: assignments applied when the unique key already exists
	// Rows holds the parameters of each additional inserted row, in the
	// column order of Set. Every Set item is then a value assignment.
	Rows       [][]int   `json:"rows,omitempty"`
	Optimistic *Optimist `json:"optimistic,omitempty"`
	Agg        string    `json:"agg,omitempty"` // column for sum/avg
	// NParams is how many parameters the client holds. The engine only checks
	// indices against it; values never reach the engine.
	NParams int `json:"n_params"`
}

Request is one statement: a query (select/count/sum/avg), a write (insert/update/delete/restore), or a paginate (select + count).

func Decode

func Decode(m *runtimemodel.Model, b []byte) (*Request, error)

Decode parses and validates a request against the manifest.

type RestoreParts

type RestoreParts struct {
	// Key is the primary key, or the unique key, whose columns the request gives values.
	Key []string
	// Where is the where of the request with an eq condition for each set value of a key column.
	Where Group
	// Set holds the set values of the columns outside the key: the new values of the row.
	Set []Assign
}

RestoreParts are the parts of the statement of a restore request: the key that names its row, the conditions and the new values.

func RestoreKey

func RestoreKey(ent *runtimemodel.Entity, r *Request) (RestoreParts, error)

RestoreKey picks the key of a restore request (docs/spec/protocol.md 1.5) after the request hook. The set values with a parameter and the eq conditions with a parameter that the where joins with and give columns their values; the key is the primary key when they cover it, otherwise the first unique key in name order that they cover. A set value of a key column becomes a condition, every other set value is a new value, and the where keeps its other conditions, which narrow the restore further; the key still names at most one row.

type Sub

type Sub struct {
	Query  *Query `json:"query"`
	Column string `json:"column,omitempty"`
	Agg    string `json:"agg,omitempty"`
}

Sub is a subquery. Column selects one column (IN lists and scalar columns); Agg selects sum, avg, or count over Column for a scalar column. Refs with path "^" inside the subquery point at the enclosing query.

Jump to

Keyboard shortcuts

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