# gizdb:workbench

Interactive SQL sessions reuse Source adapters and the SQL parser. Products own connection records, credential access, authorization and saved work.

```gizlang
import * as Workbench from "gizdb:workbench";
```

## Types

### `ResultSet`

```gizlang
type ResultSet = { columns: Vec<string>; rows: Vec<Vec<Option<string>>>; truncated: bool; }
```

A query's column names and rows (null as none); `truncated` when more rows than the limit matched.

- `columns`: `Vec<string>`
- `rows`: `Vec<Vec<_gizlang_sdk_core.Option<string>>>`
- `truncated`: `bool`

### `Admission`

```gizlang
type Admission = { privateNetwork: bool; localFiles: bool; driverStrings: bool; }
```

Local files and raw driver connection strings require explicit host admission.

- `privateNetwork`: `bool`
- `localFiles`: `bool`
- `driverStrings`: `bool`

### `Session`

```gizlang
type Session = { source: Source.Source; close: () => void; execute: (sql: string, expected: Option<i64>) => Result<i64, string>; }
```

An open SQL session: its Source, how to close it and, when writable, how to run a change expecting a row count.

- `source`: `M85.Source`
- `close`: `() => void`
- `execute`: `(sql: string, expected: _gizlang_sdk_core.Option<i64>) => _gizlang_sdk_core.Result<i64, string>`

## Functions

### `readOnly`

```gizlang
function readOnly(sql: string): string throws string
```

`sql` without trailing semicolons when it is one SELECT, WITH or VALUES statement.

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

### `reachable`

```gizlang
function reachable(sys: System, location: string, admission: Admission): Pg.Options throws string
```

The PostgreSQL options of `location`, its host resolved and admitted by `admission`.

Effects: fail, io.

### `open`

```gizlang
function open(sys: System, location: string, dialect: string, admission: Admission, writable: bool = false): Session throws string
```

A session on the database at `location` (postgres://, mysql://, odbc: or a local file), read-only unless `writable`.

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

### `held`

```gizlang
function held(database: Store.Database, writable: bool = false): Session throws string
```

A session on the open store `database`, read-only unless `writable`; closing the session closes the database.

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

### `query`

```gizlang
function query(session: Session, sql: string, limit: i64 = ROWS): ResultSet throws string
```

The first `limit` rows of the read-only statement `sql`.

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

### `tables`

```gizlang
function tables(session: Session): ResultSet throws string
```

The tables and views of the session's database: schema, name and type.

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

### `columns`

```gizlang
function columns(session: Session, schema: string, table: string): ResultSet throws string
```

The columns of `schema`.`table`: name, type, nullability and default.

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

## Constants

### `ROWS`

```gizlang
const ROWS = 1000
```

The most rows a query returns.

### `BYTES`

```gizlang
const BYTES = 16777216
```

The most bytes a query reads.