zephyr.db

Per-module structured storage. Tables are declared in the module's schema file, and every function operates only on the calling module's own data. All functions require the `storage` permission.

10 functions

insert

storage

zephyr.db.insert(table, row)

Insert a row into a declared table.

Parameters

tablestring

Name of a table declared in the module schema.

rowtable

Column/value pairs to insert. Keys must match the table's declared columns.

Returns

nil

Nothing. Raises a Lua error if the row violates the schema.

Raises an error if

the storage permission is not granted
a column is missing or does not match the schema

Example

lua

zephyr.db.insert("warnings", {
  user_id = interaction.user.id,
  reason = reason,
})

get

storage

zephyr.db.get(table, key)

Fetch a single row by primary key.

Parameters

tablestring

Name of a table declared in the module schema.

keyany

Primary-key value to look up.

Returns

Row?

The matching row, or nil when no row has that key.

Raises an error if

the storage permission is not granted

Example

lua

local user = zephyr.db.get("users", interaction.user.id)
if user ~= nil then
  -- ...
end

list

storage

zephyr.db.list(table, limit?)

List rows from a table.

Parameters

tablestring

Name of a table declared in the module schema.

limitnumberoptional

Maximum rows to return. Defaults to 50.

Returns

Row[]

An array of rows. Empty when the table has no rows.

Raises an error if

the storage permission is not granted

Example

lua

for _, warning in ipairs(zephyr.db.list("warnings", 10)) do
  print(warning.reason)
end

select

storage

zephyr.db.select(table, selector?)

Return all rows matching a selector.

Parameters

tablestring

Name of a table declared in the module schema.

selectortableoptional

Query selector (equality filters, plus optional limit and order). Omit to return up to 50 rows.

Returns

Row[]

An array of matching rows.

Raises an error if

the storage permission is not granted

Example

lua

local open = zephyr.db.select("tickets", { status = "open" })

first

storage

zephyr.db.first(table, selector?)

Return the first row matching a selector.

Parameters

tablestring

Name of a table declared in the module schema.

selectortableoptional

Query selector. Omit to return the first row in the table.

Returns

Row?

The first matching row, or nil when nothing matches.

Raises an error if

the storage permission is not granted

Example

lua

local ticket = zephyr.db.first("tickets", { channel_id = channel.id })

delete

storage

zephyr.db.delete(table, key)

Delete a single row by primary key.

Parameters

tablestring

Name of a table declared in the module schema.

keyany

Primary-key value of the row to delete.

Returns

boolean

true if a row was deleted, false if no row had that key.

Raises an error if

the storage permission is not granted

Example

lua

zephyr.db.delete("sessions", session_id)

delete_where

storage

zephyr.db.delete_where(table, selector)

Delete every row matching a selector.

Parameters

tablestring

Name of a table declared in the module schema.

selectortable

Query selector identifying the rows to delete.

Returns

number

The number of rows deleted.

Raises an error if

the storage permission is not granted

Example

lua

local removed = zephyr.db.delete_where("warnings", { user_id = user.id })

update

storage

zephyr.db.update(table, key, patch)

Update columns of a single row by primary key.

Parameters

tablestring

Name of a table declared in the module schema.

keyany

Primary-key value of the row to update.

patchtable

Column/value pairs to write. Keys must match declared columns; columns left out of the patch keep their current value.

Returns

boolean

true if a row was updated, false if no row had that key.

Raises an error if

the storage permission is not granted
a column is not in the schema or its value does not match the column type

Example

lua

zephyr.db.update("members", member.id, { xp = member.xp, level = member.level })

upsert

storage

zephyr.db.upsert(table, row)

Insert a row, or update it in place when its primary key already exists.

Parameters

tablestring

Name of a table declared in the module schema.

rowtable

Column/value pairs to write. Must include the primary key; on conflict the non-key columns are overwritten. One atomic statement, unlike a delete-then-insert.

Returns

nil

Nothing. Raises a Lua error if the row omits the primary key or violates the schema.

Raises an error if

the storage permission is not granted
the primary key column is missing, or a column does not match the schema

Example

lua

zephyr.db.upsert("members", {
  id = member.id,
  guild_id = member.guild_id,
  user_id = member.user_id,
  xp = member.xp,
  level = member.level,
})

increment

storage

zephyr.db.increment(table, key, deltas)

Atomically add to one or more numeric columns of a single row.

Parameters

tablestring

Name of a table declared in the module schema.

keyany

Primary-key value of the row to adjust.

deltastable

Column/amount pairs to add. Each column must be integer or real; amounts may be negative to subtract.

Returns

Row?

The updated row, or nil when no row has that key. The read-modify-write runs inside SQLite, so concurrent increments cannot lose updates.

Raises an error if

the storage permission is not granted
a target column is missing or is not numeric

Example

lua

local row = zephyr.db.increment("members", member.id, { xp = gain, messages = 1 })