> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peerdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# PeerDB Lua Scripting

PeerDB uses [Gopher Lua](https://github.com/yuin/gopher-lua) for scripting

See [examples](https://github.com/PeerDB-io/examples) for sample scripts

Scripts can be added & edited in UI:

<img src="https://mintcdn.com/peerdb/L54DxDXK99_p-wL9/images/scripts_overview.png?fit=max&auto=format&n=L54DxDXK99_p-wL9&q=85&s=21f2c7eb51101b88248450d236e03bba" alt="scripts overview" width="3800" height="1080" data-path="images/scripts_overview.png" />

<img src="https://mintcdn.com/peerdb/L54DxDXK99_p-wL9/images/scripts_editor.png?fit=max&auto=format&n=L54DxDXK99_p-wL9&q=85&s=4140e121e9b748867b17bab3c01d2aad" alt="scripts editor" width="3790" height="1814" data-path="images/scripts_editor.png" />

PeerDB Streams supports an `onRecord` function for complete control of message content. Result may be a table instead of a string to specify partition key, metadata, etc. See queue specific pages for supported fields. If multiple return values are given, multiple records will be written

For qrep mirrors `transformRow` can be defined. Row fields can be set to transform row. Schema may not be modified

For cdc mirrors `transformRow` will be called on the record's rows by default, unless `tranformRecord` is defined. The latter can be useful for comparing old & new field values

# `peerdb` functions

The set of functions in global `peerdb` table are:

#### `RowColumns(row) table`

Returns array of row's column names

#### `RowColumnKind(row, column) string`

Returns underlying `Kind` of row column, see [qvalue/kind.go](https://github.com/PeerDB-io/peerdb/blob/main/flow/model/qvalue/kind.go) for list of kinds

#### `Now() [Time]`

Returns current time as `[Time]`

#### `UUID(string?) [UUID]`

Returns random `[UUID]`, or parses passed in string

#### `Decimal(string | number)`

Returns Decimal based on passed in value

#### `type(any) string`

Returns `fmt.Sprintf("%T", value)` on underlying value of UserData. Returns `nil` for other types

#### `tostring(any) string`

Returns `fmt.Sprint(value)` on underlying value of UserData. Returns `nil` for other types

# types

PeerDB exposes records as UserData:

## `Record`

Represents a CDC change

#### `kind`

One of `insert`, `update`, `delete`, or `relation`. You will likely want to ignore `relation` messages

#### `row`

Canonical row values of change. For `update` this is the new row. Keep in mind that Postgres does not send unchanged toast column values in CDC updates

#### `old`

Previous row values, `nil` for insert

#### `new`

New row values, `nil` for delete

#### `checkpoint`

LSN of CDC message

#### `commit_time`

CommitTime of record's preceding BeginMessage

#### `target`

Destination table of record defined by mirror

#### `source`

Source table of record

#### `unchanged_columns`

Update records have a table mapping unchanged [toast](https://www.postgresql.org/docs/current/storage-toast.html) columns to `true`

## `Row`

PeerDB row values which cannot be represented as Lua numbers or strings are wrapped in UserData. All of these types implement `__tostring`. Available types:

#### `I64` / `U64`

Represents signed/unsigned 64 bit integers. Implements comparisons with each other & `__tostring` support. There are 3 conversion properties:

* `i64` cast to `[I64]`
* `u64` cast to `[U64]`
* `float64` cast to lua number
* `hi` returns highest 32 bits as an unsigned number
* `lo` returns lowest 32 bits as an unsigned number

## `Time`

Has properties for durations since Unix epoch. These are `[I64]` results, except `unix` which is a lua number

* unix\_nano
* unix\_micro
* unix\_milli
* unix\_second
* unix

& properties for datetime components as numbers:

* year
* month
* day
* yearday
* hour
* minute
* second
* nanosecond

## `UUID`

Index with `[0..16)` to access bytes *(first element at index 0)*

## `BigInt`

#### `sign`

`1`, `0`, or `-1` depending on sign of value

#### `bytes`

string of `*big.Int` Bytes method

#### `int64`

value as `[I64]`

#### `is64`

whether value can be represented by `int64`

## `Decimal`

#### `coefficient`

`[BigInt]` representing digits

#### `coefficient64`

`[I64]` representing digits

#### `exponent`

Exponent, value of decimal is `coefficient * (10 ^ exponent)`

#### `bigint`

Value of decimal as a `BigInt`

#### `int64`

Value of decimal as a `[I64]`

#### `float`

Value of decimal as a number

# package.preload

PeerDB offers some preloaded libraries, accessible via `require`:

| library                                             | description                                                                     |
| --------------------------------------------------- | ------------------------------------------------------------------------------- |
| [bit32](https://github.com/PeerDB-io/gluabit32)     | [bit32 API included in Lua 5.2](https://www.lua.org/manual/5.2/manual.html#6.7) |
| [json](https://github.com/PeerDB-io/gluajson)       | [JSON](https://json.org) encoding/decoding                                      |
| [msgpack](https://github.com/PeerDB-io/gluamsgpack) | [msgpack](https://msgpack.org) encoding                                         |
| [utf8](https://github.com/PeerDB-io/gluautf8)       | [utf8 API included in Lua 5.3](https://www.lua.org/manual/5.3/manual.html#6.5)  |