Documentation
¶
Overview ¶
Package dbschema is the portable model of a relational database's shape: tables, columns, keys, and enums. Orchard's SQL providers produce it by reading their database's catalog, `orchard schema pull` stores it as the body of a "database" snapshot, and plan-time checks (and editor tooling) read it back.
The model is database-neutral. Each column keeps its native type as the database spells it (varchar(100), numeric(10,2)) alongside a portable Kind, so checks can reason about kinds while tooling can show the real type.
Index ¶
- Constants
- Variables
- func CheckConflict(t *Table, mode string, columns []string, values cty.Value) error
- func CheckDelete(t *Table, where cty.Value) error
- func CheckInsert(t *Table, values cty.Value) error
- func CheckUpdate(t *Table, set, where cty.Value) error
- func CheckValue(c *Column, v cty.Value) error
- func ConflictKey(t *Table, columns []string) ([]string, error)
- func Diff(old, cur *Schema) []string
- func KindType(k Kind) cty.Type
- func TableKey(schema, name string) string
- type Column
- type ForeignKey
- type Kind
- type Schema
- type Table
Constants ¶
const ( ConflictError = "error" ConflictIgnore = "ignore" ConflictUpdate = "update" )
Conflict modes for an insert's on_conflict.
const ( // GeneratedIdentity is an identity column that always generates // its value (Postgres GENERATED ALWAYS AS IDENTITY). GeneratedIdentity = "identity" // GeneratedStored and GeneratedVirtual are computed columns. GeneratedStored = "stored" GeneratedVirtual = "virtual" )
Generated values for Column.Generated. Columns with any of these can't be set by an insert or update.
const SnapshotKind = "database"
SnapshotKind is the snapshot `kind` for a database schema body.
Variables ¶
var ErrNoTable = errors.New("no such table")
ErrNoTable is wrapped by Lookup's error for a table that doesn't exist, so callers can tell it apart from other failures.
Functions ¶
func CheckConflict ¶
CheckConflict validates an insert's conflict handling: mode is error (the default, ""), ignore or update; columns, defaulting to the primary key, must be the primary key or a unique key; and values must set every one of them, so the existing row can be found.
func CheckDelete ¶
CheckDelete validates a delete from t: where names existing columns.
func CheckInsert ¶
CheckInsert validates the values of an insert into t: every column exists, isn't generated, and takes its value; every required column (not nullable, no default, not generated) is set. values is an object or map and may contain unknown values (at plan time); those are checked by type when their type is known.
func CheckUpdate ¶
CheckUpdate validates an update of t: set names writable columns and takes their values, and where names existing columns.
func CheckValue ¶
CheckValue reports whether v can be stored in column c: null only in a nullable column, and otherwise a value that converts to the column kind's type (so "5" from a string variable fits an integer column), integers whole, and enums one of their members. Unknown values are checked by type only; unknown types aren't checked.
func ConflictKey ¶
ConflictKey resolves an insert's conflict columns: the given columns if they're the primary key or a unique key (in any order), or the primary key when none are given.
func Diff ¶
Diff lists how cur differs from old, one human-readable line per change: tables and columns added or removed, and changes to a column's type, nullability, default, generated status or enum values, or to a table's primary or foreign keys. Comments are ignored; they don't affect what an action may do. The result is sorted by table and empty when the schemas match.
Types ¶
type Column ¶
type Column struct {
Name string `json:"name"`
// Type is the native type as the database spells it.
Type string `json:"type"`
Kind Kind `json:"kind"`
Nullable bool `json:"nullable"`
// HasDefault is true when the database supplies a value if the
// column is omitted: a DEFAULT, a sequence, AUTO_INCREMENT, an
// identity, or SQLite's rowid.
HasDefault bool `json:"has_default,omitempty"`
// Generated is one of the Generated* constants, or empty.
Generated string `json:"generated,omitempty"`
// Enum lists the allowed values of an enum column, in order.
Enum []string `json:"enum,omitempty"`
Comment string `json:"comment,omitempty"`
}
Column is one column.
type ForeignKey ¶
type ForeignKey struct {
Columns []string `json:"columns"`
References string `json:"references"`
ReferencedColumns []string `json:"referenced_columns"`
}
ForeignKey is a foreign key from Columns to ReferencedColumns of the table named by References (a TableKey).
type Kind ¶
type Kind string
Kind is a column's portable type family.
const ( KindInteger Kind = "integer" KindDecimal Kind = "decimal" KindFloat Kind = "float" KindBoolean Kind = "boolean" KindText Kind = "text" KindUUID Kind = "uuid" KindEnum Kind = "enum" KindDate Kind = "date" KindTime Kind = "time" KindTimestamp Kind = "timestamp" KindJSON Kind = "json" KindBinary Kind = "binary" // KindOther covers types with no portable kind (arrays, intervals, // geometry, ...). Values for them aren't type-checked. KindOther Kind = "other" )
Column kinds. Each SQL provider maps its native types onto these.
type Schema ¶
type Schema struct {
// Dialect is the database family: "postgres", "mysql" or "sqlite".
Dialect string `json:"dialect"`
// Database is the database name (for SQLite, the file name). It
// never includes a host, user or password.
Database string `json:"database"`
// DefaultSchema is the namespace unqualified table names resolve
// against (Postgres's current_schema()). Empty for databases with
// a single namespace.
DefaultSchema string `json:"default_schema,omitempty"`
// Namespaces lists the schemas the capture was limited to (`schema
// pull --schemas`), so a later comparison captures the same scope.
// Empty means everything.
Namespaces []string `json:"namespaces,omitempty"`
// Tables is keyed by TableKey.
Tables map[string]*Table `json:"tables"`
}
Schema is one database's tables.
func (*Schema) Lookup ¶
Lookup returns the table named by name: "table" or "schema.table". An unqualified name resolves against DefaultSchema when the database has namespaces. The error suggests a close match when there is one.
func (*Schema) TableNames ¶
TableNames returns the keys of s.Tables in sorted order.
type Table ¶
type Table struct {
// Schema is the table's namespace, empty for databases with one.
Schema string `json:"schema,omitempty"`
Name string `json:"name"`
Comment string `json:"comment,omitempty"`
// Columns are in the table's declared order.
Columns []Column `json:"columns"`
PrimaryKey []string `json:"primary_key,omitempty"`
ForeignKeys []ForeignKey `json:"foreign_keys,omitempty"`
// UniqueKeys lists the column sets of the table's unique
// constraints and unique indexes, besides the primary key. Partial
// and expression indexes are left out: they can't identify a row
// from column values alone.
UniqueKeys [][]string `json:"unique_keys,omitempty"`
}
Table is one table.
Source Files