Lua procedure API

Copy Markdown View Source

Each procedure receives fresh Lua globals and an args value supplied by the caller. A procedure returns zero or one value. Supported values are nil, booleans, numbers, strings, arrays, and string-keyed tables.

Database

local row = db.one("SELECT id, state FROM jobs WHERE id = ?", {args.id})
local rows = db.all("SELECT id FROM jobs WHERE state = ?", {"ready"})
local result = db.exec("UPDATE jobs SET state = ? WHERE id = ?", {"done", args.id})

db.one returns nil, one string-keyed row, or fails if the query produces more than one row. db.all returns a bounded array. db.exec returns rows_affected and last_insert_rowid.

Use explicit values where Lua cannot preserve SQL storage semantics:

db.exec("INSERT INTO values(blob_value, null_value) VALUES (?, ?)", {
  db.blob(args.bytes),
  db.null()
})

All SQL parameters are bound; data must not be interpolated into SQL strings. Transaction-control statements are rejected because the host owns the complete call-tree transaction.

Composition

local result = procedures.call("reserve_inventory", {
  product_id = args.product_id,
  quantity = args.quantity
})

The child uses the same connection, transaction, caller policy, deadline, and aggregate budgets, but receives a fresh Lua VM.

Failure

if args.quantity <= 0 then
  fail("invalid_quantity", "quantity must be positive")
end

The failure code is safe metadata and the message is capped. Any unhandled or caught child/host failure prevents commit.