# 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<Value>, Vec<Value>>; params: Vec<Value>; }
```

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<M55.Value>, Vec<M55.Value>>`
- `params`: `Vec<M55.Value>`

### `Changed`

```gizlang
type Changed = { keys: Vec<Value>; 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<M55.Value>`
- `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<Db, DbError>
```

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<Relay.Relay>, name: string): Result<Db, DbError>
```

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<Model.Shape>): Result<bool, Model.Rejection>
```

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<string>): Result<bool, Model.Rejection>
```

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<Policy.Write>, conflict: string): Result<i64, Model.Rejection>
```

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<Value>): Result<Policy.Write, Model.Rejection>
```

One statement from SQL text, with its parameters $1...

Effects: fail.

### `guarded`

```gizlang
function guarded(text: string, params: Vec<Value>, rows: i64): Result<Policy.Write, Model.Rejection>
```

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<Model.Row>): Result<Policy.Write, Model.Rejection>
```

Insert rows of a stored Shape in one statement (Model.insertRowsSql).

Effects: fail.

### `insert`

```gizlang
function insert<T>(shape: Model.Shape, v: T): Result<Policy.Write, Model.Rejection>
```

Insert the record `v` of a stored Shape.

### `find`

```gizlang
function find<R>(d: Db, shape: Model.Shape, filter: string, keys: Vec<string>, of: (row: Vec<Value>) => R effects { fail }): Result<Vec<R>, 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<R>(d: Db, shape: Model.Shape, filter: string, keys: Vec<string>, of: (row: Vec<Value>) => R effects { fail }, missing: string): Result<R, Model.Rejection>
```

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<Scoped, Model.Rejection>
```

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<Model.Shape>): Result<bool, Model.Rejection>
```

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<Value>, tail: string): Result<Readable, Model.Rejection>
```

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<Value>, tail: string): Result<Vec<Vec<Value>>, 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<Value>): Result<i64, Model.Rejection>
```

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<Value>): Result<Policy.Condition, Model.Rejection>
```

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<Value>): Result<Vec<Value>, 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<Value>): Result<Vec<Value>, 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<Value>): Result<Vec<Value>, 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<Value>, at: i64, value: Value, expected: Option<Value>): Result<bool, Model.Rejection>
```

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<Value>): Result<bool, Model.Rejection>
```

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<Value>): Result<bool, Model.Rejection>
```

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<string>): Result<string, Model.Rejection>
```

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<Changed, Model.Rejection>
```

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<bool, DbError>
```

End the connection.

Effects: fail, read, write, console, io.

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<Value>, Vec<Value>>; params: Vec<Value>; }

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<M55.Value>, Vec<M55.Value>>
params: Vec<M55.Value>

`Changed`

gizlang

type Changed = { keys: Vec<Value>; 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<M55.Value>
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<Db, DbError>

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<Relay.Relay>, name: string): Result<Db, DbError>

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<Model.Shape>): Result<bool, Model.Rejection>

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<string>): Result<bool, Model.Rejection>

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<Policy.Write>, conflict: string): Result<i64, Model.Rejection>

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<Value>): Result<Policy.Write, Model.Rejection>

One statement from SQL text, with its parameters $1...

Effects: fail.

`guarded`

gizlang

function guarded(text: string, params: Vec<Value>, rows: i64): Result<Policy.Write, Model.Rejection>

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<Model.Row>): Result<Policy.Write, Model.Rejection>

Insert rows of a stored Shape in one statement (Model.insertRowsSql).

Effects: fail.

`insert`

gizlang

function insert<T>(shape: Model.Shape, v: T): Result<Policy.Write, Model.Rejection>

Insert the record v of a stored Shape.

`find`

gizlang

function find<R>(d: Db, shape: Model.Shape, filter: string, keys: Vec<string>, of: (row: Vec<Value>) => R effects { fail }): Result<Vec<R>, 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<R>(d: Db, shape: Model.Shape, filter: string, keys: Vec<string>, of: (row: Vec<Value>) => R effects { fail }, missing: string): Result<R, Model.Rejection>

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<Scoped, Model.Rejection>

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<Model.Shape>): Result<bool, Model.Rejection>

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<Value>, tail: string): Result<Readable, Model.Rejection>

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<Value>, tail: string): Result<Vec<Vec<Value>>, 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<Value>): Result<i64, Model.Rejection>

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<Value>): Result<Policy.Condition, Model.Rejection>

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<Value>): Result<Vec<Value>, 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<Value>): Result<Vec<Value>, 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<Value>): Result<Vec<Value>, 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<Value>, at: i64, value: Value, expected: Option<Value>): Result<bool, Model.Rejection>

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<Value>): Result<bool, Model.Rejection>

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<Value>): Result<bool, Model.Rejection>

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<string>): Result<string, Model.Rejection>

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<Changed, Model.Rejection>

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<bool, DbError>

End the connection.

Effects: fail, read, write, console, io.