# gizdb:data A stored application's typed records, by their Model.Shape: on a GizDB engine this process serves, or on a SQL store. Actions, packages and the platform write and read them here; one transaction is one Connection.begin. A page follows them with Data.follow and Web.live (web/app.giz). ```gizlang import * as Data from "gizdb:data"; ``` ## Types ### `Db` ```gizlang type Db = { source: Source.Source; ops: Ops; } ``` A database and the operations of its store, which every call of this module takes. - `source`: `M61.Source` - `ops`: `M49.Ops` ### `Scoped` ```gizlang type Scoped = { db: Db; scope: Gate.Scope; } ``` A Db with the Scope of the actor that uses it. - `db`: `M49.Db` - `scope`: `M50.Scope` ### `Readable` ```gizlang type Readable = { query: Query.Prepared, Vec>; params: Vec; } ``` The query of the rows of `shape` that the actor may read and `filter` selects, with the fields that the actor may not read as NULL, and its parameters. `tail` is an ORDER BY, LIMIT or OFFSET made from checked names and numbers; it replaces the order by key. - `query`: `M58.Prepared, Vec>` - `params`: `Vec` ### `Changed` ```gizlang type Changed = { keys: Vec; lost: bool; follow: string; } ``` What changed in a followed selection: the first key of each row that came, went or changed, and the id to follow on with. `lost` is true when the follow is unknown or expired: render the selection again with a new follow. - `keys`: `Vec` - `lost`: `bool` - `follow`: `string` ## Functions ### `db` ```gizlang function db(connection: Access.Connection, name: string): Db ``` The database NAME of CONNECTION, on the GizDB engine. Effects: fail. ### `of` ```gizlang function of (engine: Store.Engine, name: string): Result ``` The typed records `name` of a GizDB engine this process serves (Store.Database.engine; its SQL and these records are one database): a connection of its own, one for each thread, that Db.close ends. Effects: fail, io. ### `connect` ```gizlang function connect(store: Store.Database, feed: Option, name: string): Result ``` The typed records `name` of any store: of its engine when this process serves one, else SQL on `store` itself. A SQL store needs a `feed` (Relay.feed) for `follow` and `changed`; without one they fail. Effects: fail, read, io. ### `install` ```gizlang function install(d: Db, shapes: Vec): Result ``` Make the tables and indexes of `shapes` that are not there. Effects: fail, read, write, console, io. ### `define` ```gizlang function define(d: Db, statements: Vec): Result ``` Run schema statements (SQL texts), one at a time: GizDB defines a table once in a transaction, so a table and its index are two. Each is idempotent (IF NOT EXISTS), so a run that stops midway is run again. Effects: fail, read, write, console, io. ### `write` ```gizlang function write(d: Db, writes: Vec, conflict: string): Result ``` Run the writes as one transaction; how many rows they changed. A guard that fails, or a key that exists already, is a 409 with `conflict`. Effects: fail, read, write, console, io. ### `statements` ```gizlang function statements(text: string, params: Vec): Result ``` One statement from SQL text, with its parameters $1... Effects: fail. ### `guarded` ```gizlang function guarded(text: string, params: Vec, rows: i64): Result ``` The same, where exactly `rows` rows must change, else the transaction is a conflict. Effects: fail. ### `insertRows` ```gizlang function insertRows(shape: Model.Shape, rows: Vec): Result ``` Insert rows of a stored Shape in one statement (Model.insertRowsSql). Effects: fail. ### `insert` ```gizlang function insert(shape: Model.Shape, v: T): Result ``` Insert the record `v` of a stored Shape. ### `find` ```gizlang function find(d: Db, shape: Model.Shape, filter: string, keys: Vec, of: (row: Vec) => R effects { fail }): Result, Model.Rejection> ``` The records of a stored Shape that `filter` selects, in key order (Model.select): SQL over its columns with text parameters $1.. for `keys`, as "target = $1"; an empty filter selects all. ### `one` ```gizlang function one(d: Db, shape: Model.Shape, filter: string, keys: Vec, of: (row: Vec) => R effects { fail }, missing: string): Result ``` The one record of a stored Shape that matches, or a 404 with `missing`. ### `as` ```gizlang function as(d: Db, space: string, actor: Security.Principal, now: i64): Result ``` The records as `actor` of the Space `space` may use them at `now` (ms since 1970). Effects: fail, io. ### `provision` ```gizlang function provision(s: Scoped, shapes: Vec): Result ``` Make the tables of `shapes` and the Policy tables, and place each table below the actor as its owner. Run it once for each Space; it can run again. Effects: fail, read, write, console, io. ### `readable` ```gizlang function readable(s: Scoped, shape: Model.Shape, filter: string, params: Vec, tail: string): Result ``` The query of the rows of SHAPE that the actor of S may read and FILTER selects, with PARAMS and TAIL (Readable). Effects: fail, read, write, console, io. ### `rows` ```gizlang function rows(s: Scoped, shape: Model.Shape, filter: string, params: Vec, tail: string): Result>, Model.Rejection> ``` The rows that `readable` selects. Effects: fail, read, write, console, io. ### `count` ```gizlang function count(s: Scoped, shape: Model.Shape, filter: string, params: Vec): Result ``` How many rows the actor may read that `filter` selects. Effects: fail, read, write, console, io. ### `keyed` ```gizlang function keyed(shape: Model.Shape, values: Vec): Result ``` The filter and parameters that select the row with these key values. Effects: fail. ### `row` ```gizlang function row(s: Scoped, shape: Model.Shape, key: Vec): Result, Model.Rejection> ``` The one row with these key values (only its key fields are read), as the actor may read it, or a 404. Effects: fail, read, write, console, io. ### `create` ```gizlang function create(s: Scoped, shape: Model.Shape, values: Vec): Result, Model.Rejection> ``` Create a row (all the fields in order): the actor needs the Shape's write role on its parent. The row is inserted and placed in one transaction. Effects: fail, read, write, console, io. ### `update` ```gizlang function update(s: Scoped, shape: Model.Shape, values: Vec): Result, Model.Rejection> ``` Notice a row to `values` (all the fields in order, the key as it is): the actor needs the write role on the row. Effects: fail, read, write, console, io. ### `patch` ```gizlang function patch(s: Scoped, shape: Model.Shape, key: Vec, at: i64, value: Value, expected: Option): Result ``` Change the field AT of the row with these key values to VALUE, as one UPDATE of one column: the actor needs the write role on the field. When EXPECTED is given the update holds only while the stored field still has that value (checked by the database inside the write), else it is a 409: two people who change one field never overwrite each other unseen. A value that is the stored one changes nothing. Effects: fail, read, write, console, io. ### `inTable` ```gizlang function inTable(store: Db, shape: Model.Shape, key: Vec): Result ``` Whether the row with these key values is in the table at all, whoever may read it (a trusted question: a host asks it to tell a removed row from one that a person may not read). Effects: fail, read, write, console, io. ### `remove` ```gizlang function remove(s: Scoped, shape: Model.Shape, key: Vec): Result ``` Remove the row with these key values: the actor needs the write role on it. Its place and grants go in the same transaction. Effects: fail, read, write, console, io. ### `follow` ```gizlang function follow(sys: System, d: Db, shape: Model.Shape, filter: string, keys: Vec): Result ``` Follow the records of a stored Shape that `filter` selects (as `find`); the follow's id. Open it before the page reads the records: a change in between is delivered again. Effects: fail, read, write, console, io. ### `changed` ```gizlang function changed(d: Db, id: string, waitMs: i64): Result ``` The changes of the follow `id` since its position, waiting up to `waitMs` for one; each read renews the watch's lease. Effects: fail, read, write, console, io. ## Methods ### `Db.close` ```gizlang function Db.close(self: Db): Result ``` End the connection. Effects: fail, read, write, console, io.