# gizlang:sqlite

SQLite through its C library (`giz bind` wrote the declarations, reviewed by hand). The same shape as gizlang:postgres: text parameters and values, SQL NULL as Option.none(), Result errors, and `transaction(work, failure)`. Calls block the calling thread while SQLite works.

```gizlang
import * as Sqlite from "gizlang:sqlite";
```

## Types

### `SqliteError`

```gizlang
type SqliteError = { code: i64; message: string; }
```

`code` is SQLite's extended result code (0 for this module's own errors).

- `code`: `i64`
- `message`: `string`

### `Rows`

```gizlang
type Rows = { columns: Vec<string>; rows: Vec<Vec<Option<string>>>; affected: i64; }
```

The result of a SQLite statement: the column names, the rows (NULL is none) and the rows changed.

- `columns`: `Vec<string>`
- `rows`: `Vec<Vec<_gizlang_sdk_core.Option<string>>>`
- `affected`: `i64`

### `Database`

```gizlang
type Database
```

An open SQLite database.

Opaque: create and use it through this module's functions.

## Functions

### `open`

```gizlang
function open(path: string): Database throws SqliteError
```

A file path, created when missing, or ":memory:".

Effects: fail, write, io.

## Methods

### `Database.close`

```gizlang
function Database.close(self: Database): bool
```

Closes the database. It does nothing after the first call.

Effects: fail, read, write, io.

### `Database.query`

```gizlang
function Database.query(self: Database, sql: string, params: Vec<Option<string>>): Rows throws SqliteError
```

One statement with text parameters ($1-style or ?), all its rows read.

Effects: fail, read, write, io.

### `Database.exec`

```gizlang
function Database.exec(self: Database, sql: string): bool throws SqliteError
```

A script of statements without parameters or results.

Effects: fail, read, io.

### `Database.transaction`

```gizlang
function Database.transaction<F, E>(self: Database, work: F, failure: (error: SqliteError) => E): ReturnType<F>
```

Work receives the same database and returns Result<T, E>; `failure`
projects this module's own SqliteError (BEGIN, COMMIT) into E. A
success commits, an error (or a failed commit) rolls back. Work that ends
the transaction itself is an error; transactions do not nest. It holds the
write lock from its start (BEGIN IMMEDIATE), waiting for it as the busy
timeout allows: in WAL mode a transaction that read first could not write
once another connection had committed.