# gizdb:schema One pure schema planner. Catalog readers and command executors belong to callers. ```gizlang import * as Schema from "gizdb:schema"; ``` ## Types ### `SchemaColumn` ```gizlang type SchemaColumn = { name: string; definition: string; nullable: bool; default: Option; earlier: Vec; } ``` A column of a table schema: its name, SQL definition, whether it takes NULL, its default, and its earlier names. - `name`: `string` - `definition`: `string` - `nullable`: `bool` - `default`: `_gizlang_sdk_core.Option` - `earlier`: `Vec` ### `Unique` ```gizlang type Unique = { name: string; columns: Vec; } ``` A unique constraint: its name and columns. - `name`: `string` - `columns`: `Vec` ### `Index` ```gizlang type Index = { name: string; columns: Vec; } ``` An index: its name and columns. - `name`: `string` - `columns`: `Vec` ### `DeleteAction` ```gizlang type DeleteAction = | { kind: "restrict"; } | { kind: "cascade"; } | { kind: "setNull"; } ``` What a foreign key does when the row that it refers to is deleted. - `restrict` - `cascade` - `setNull` ### `Reference` ```gizlang type Reference = { name: string; columns: Vec; table: string; targets: Vec; onDelete: DeleteAction; } ``` A foreign key: its name, columns, the table and columns that it refers to, and its delete action. - `name`: `string` - `columns`: `Vec` - `table`: `string` - `targets`: `Vec` - `onDelete`: `M57.DeleteAction` ### `Check` ```gizlang type Check = { name: string; sql: string; } ``` A check constraint: its name and SQL condition. - `name`: `string` - `sql`: `string` ### `Table` ```gizlang type Table = { name: string; columns: Vec; key: Vec; uniques: Vec; indexes: Vec; references: Vec; checks: Vec; } ``` A table schema: its name, columns, key, constraints and indexes. - `name`: `string` - `columns`: `Vec` - `key`: `Vec` - `uniques`: `Vec` - `indexes`: `Vec` - `references`: `Vec` - `checks`: `Vec` ### `Options` ```gizlang type Options = { nonEmpty: bool; allowDrop: Vec; allowCast: Vec; earlier: Vec; } ``` Earlier table names are newest first. Admission names source columns. nonEmpty describes the locked catalog snapshot. Use true if unknown. - `nonEmpty`: `bool` - `allowDrop`: `Vec` - `allowCast`: `Vec` - `earlier`: `Vec` ### `Migration` ```gizlang type Migration = | { kind: "createTable"; table: Table; } | { kind: "dropTable"; table: Table; } | { kind: "renameTable"; before: string; after: string; } | { kind: "renameColumn"; before: string; after: string; } | { kind: "addColumn"; column: SchemaColumn; } | { kind: "dropColumn"; column: SchemaColumn; } | { kind: "alterType"; name: string; before: string; after: string; lossless: bool; } | { kind: "notNull"; name: string; before: bool; after: bool; } | { kind: "defaultValue"; name: string; before: Option; after: Option; } | { kind: "addKey"; name: string; columns: Vec; } | { kind: "dropKey"; name: string; columns: Vec; } | { kind: "addUnique"; unique: Unique; } | { kind: "dropUnique"; unique: Unique; } | { kind: "addIndex"; index: Index; } | { kind: "dropIndex"; index: Index; } | { kind: "addReference"; reference: Reference; } | { kind: "dropReference"; reference: Reference; } | { kind: "addCheck"; check: Check; } | { kind: "dropCheck"; check: Check; } ``` Native session.giz executes create table (key, unique, references, checks), add column, rename column, create/drop index, and add primary/foreign key. Other ALTER operations, including add unique/check, return "not supported yet". Native AST lowering belongs to typed.giz. This module lowers PostgreSQL text. - `createTable` - `dropTable` - `renameTable` - `renameColumn` - `addColumn` - `dropColumn` - `alterType` - `notNull` - `defaultValue` - `addKey` - `dropKey` - `addUnique` - `dropUnique` - `addIndex` - `dropIndex` - `addReference` - `dropReference` - `addCheck` - `dropCheck` ### `Plan` ```gizlang type Plan = { changes: Vec; reversible: bool; destructive: Vec; } ``` The changes from one schema to another, whether they can be undone, and the data that they would drop. - `changes`: `Vec` - `reversible`: `bool` - `destructive`: `Vec` ## Functions ### `options` ```gizlang function options(): Options ``` The default options: the table may hold rows, and no drop or cast is allowed. ### `widening` ```gizlang function widening(before: string, after: string): bool ``` Preserve both fractional digits and integer digits. Effects: fail. ### `inverse` ```gizlang function inverse(change: Migration): Option ``` Restore the schema. Lossy casts and deleted data have no inverse. ### `plan` ```gizlang function plan(target: Table, existing: Option, admission: Options): Result ``` Plan from a locked catalog snapshot to a declaration. No effects or implicit drops. Effects: fail. ### `createSql` ```gizlang function createSql(t: Table, quote: (name: string) => string, suffix: string): Vec ``` CREATE TABLE IF NOT EXISTS, then CREATE INDEX IF NOT EXISTS for each index, in a dialect that writes an identifier with `quote`. `suffix` follows the table (SQLite's " WITHOUT ROWID"). Effects: fail, read, write, console, io. ### `sql` ```gizlang function sql(table: string, change: Migration): string ``` Use the table name at this step. After renameTable, use its after name. PostgreSQL text. Effects: fail, read, write, console, io. ### `planStatements` ```gizlang function planStatements(table: string, changes: Vec): Vec ``` PostgreSQL text for planned changes, in order, while tracking table renames. Effects: fail, read, write, console, io. ### `column` ```gizlang function column(name: string, definition: string, earlier: Vec): SchemaColumn ``` A column of a name-only catalog: nullable, no default. ### `changes` ```gizlang function changes(table: string, exists: bool, columns: Vec, fields: Vec): Result, string> ``` Name-only catalogs cannot prove drops or type changes. Retain unclaimed columns and use desired definitions for matches. All decisions still use plan; the result has only createTable, renameColumn and addColumn. Effects: fail.