Host API

Complete SDK function reference for all four runtimes — database, HTTP, VFS, KV store, config, events.

The Host API is the interface between plugins and RaisFast. All functions are permission-gated — access is denied unless declared in [permissions].

Database

Raw SQL

Function	Description
`dbQuery(sql, params?)`	SELECT query, returns array of objects
`dbExec(sql, params?)`	INSERT / UPDATE / DELETE, returns `{ rows_affected }`
`dbBegin()`	Begin transaction
`dbCommit()`	Commit transaction
`dbRollback()`	Rollback transaction

const rows = dbQuery("SELECT * FROM products WHERE price > ?", [100]);
const result = dbExec("UPDATE products SET stock = stock - 1 WHERE id = ?", [id]);

Note: dbQuery returns integer columns as null. Use CAST(col AS TEXT) and then parseInt().

High-Level DB API

Function	Returns	Description
`dbInsert(table, data, options?)`	`{ rows_affected }`	Insert a row
`dbFetchOne(table, where?, options?)`	`data` or `null`	Fetch single row
`dbFetchAll(table, where?, options?)`	`{ data, total }`	Fetch multiple rows
`dbUpdate(table, data, where?, options?)`	`{ rows_affected }`	Update rows
`dbDelete(table, where?, options?)`	`{ rows_affected }`	Delete rows
`dbCount(table, where?, options?)`	`{ count }`	Count rows
`dbIncrement(table, cols, where?, options?)`	`{ rows_affected }`	Atomic increment/decrement
`dbSum(table, column, where?, options?)`	`{ sum }`	SUM aggregate
`dbGroupBy(table, options?)`	`{ data, total }`	GROUP BY with aggregates

dbInsert("orders", { title: "New Deal", amount: 5000 });

const deal = dbFetchOne("orders", { id: "abc123" });

const { data } = dbFetchAll("orders",
  { status: "active" },
  { order_by: "amount DESC", limit: 10, offset: 0 }
);

dbUpdate("orders", { status: "closed" }, { id: "abc123" });

dbDelete("orders", { status: "cancelled" });

const { count } = dbCount("orders", { status: "active" });

dbIncrement("orders", { view_count: 1 }, { id: "abc123" });

const { sum } = dbSum("orders", "amount", { status: "closed" });

const { data } = dbGroupBy("orders", {
  group_by: "status",
  count: true,
  sum: "amount"
});

Options

Key	Description
`order_by`	Sort: `"col ASC"` or `"col1 ASC, col2 DESC"`
`limit`	Max rows to return
`offset`	Number of rows to skip
`tenant`	`"some_id"` (explicit), `false` (disabled), omitted (auto)

SQL Placeholder

Use dbPh(idx) to get the correct placeholder for the current database:

SQLite / MySQL: ?
PostgreSQL: $1, $2, ...

const ph = dbPh(1); // "?" on SQLite, "$1" on PostgreSQL

Transactions

dbBegin();
try {
  dbExec("INSERT INTO orders ...");
  dbExec("UPDATE products SET stock = stock - 1 ...");
  dbCommit();
} catch (e) {
  dbRollback();
}

HTTP

Function	Returns	Description
`httpGet(url)`	`string` or `null`	HTTP GET, raw response
`httpGetJson(url)`	`object` or `null`	HTTP GET, parsed JSON
`httpPost(url, body)`	`string` or `null`	HTTP POST, raw response
`httpPostJson(url, body)`	`object` or `null`	HTTP POST, parsed JSON

Requires http permission. 10-second timeout, 1 MB max response body.

const data = httpGetJson("https://api.example.com/v1/products");
const result = httpPostJson("https://api.example.com/webhook", { event: "test" });

Virtual Filesystem (VFS)

Function	Returns	Description
`vfsRead(path)`	`string` or `null`	Read file content
`vfsWrite(path, content)`	`bool`	Write file (auto-creates dirs)
`vfsDelete(path)`	`bool`	Delete file
`vfsExists(path)`	`bool`	Check if file exists
`vfsList(path)`	`string[]`	List directory
`vfsStat(path)`	`object` or `null`	File metadata

Requires filesystem permission. Each plugin has an isolated sandbox at {VFS_ROOT}/{plugin_id}/. Path traversal (..) is blocked.

vfsWrite("/reports/daily.json", JSON.stringify(report));
const data = JSON.parse(vfsRead("/reports/daily.json"));
const exists = vfsExists("/reports/daily.json");
const files = vfsList("/reports");
const stat = vfsStat("/reports/daily.json");
// { size: 1024, is_dir: false, modified: 1700000000 }

Quotas: single file max PLUGIN_VFS_MAX_FILE_SIZE (default 1 MB), total max PLUGIN_VFS_MAX_TOTAL_SIZE (default 10 MB).

KV Store

Function	Returns	Description
`storeGet(key)`	`string` or `null`	Read value
`storeSet(key, value)`	`bool`	Write value (upsert)

Data is scoped by plugin ID — plugins cannot access each other's data.

storeSet("last_sync", "2026-01-01");
const val = storeGet("last_sync");

Config

Function	Returns	Description
`configGet(key)`	`string` or `null`	Read config value

Requires config permission. Available keys: app.host, app.port, app.env, app.base_url, jwt.access_expires, jwt.refresh_expires, upload.dir, upload.max_size, plugin.max_memory_mb, plugin.default_timeout_ms.

Content Query

Function	Returns	Description
`getPost(slug)`	`object` or `null`	Get post by slug

Requires read:posts database permission.

Utility

Function	Returns	Description
`ok(data)`	any	Return success data
`fail(status, msg)`	error object	Return HTTP error
`extractJson(input, field?)`	any	Parse JSON and extract field (supports dot path: `"params.id"`)
`logInfo(msg)`	—	Log at info level
`logWarn(msg)`	—	Log at warn level
`logError(msg)`	—	Log at error level
`newId()`	`string`	Generate UUID v7
`eventEmit(type, data)`	—	Emit custom event

Runtime Function Name Mapping

JS and Lua use camelCase. Rhai uses snake_case. WASM uses kebab-case in WIT.

JS / Lua	Rhai	WASM (WIT)
`dbQuery`	`db_query`	`db-query`
`dbExec`	`db_execute`	`db-execute`
`dbBegin`	`db_begin`	`db-begin`
`dbCommit`	`db_commit`	`db-commit`
`dbRollback`	`db_rollback`	`db-rollback`
`dbInsert`	`db_insert`	—
`dbFetchOne`	`db_fetch_one`	—
`dbFetchAll`	`db_fetch_all`	—
`dbUpdate`	`db_update`	—
`dbDelete`	`db_delete`	—
`dbCount`	`db_count`	—
`dbIncrement`	`db_increment`	—
`dbSum`	`db_sum`	—
`dbGroupBy`	`db_group_by`	—
`httpGet`	`http_get`	`http-get`
`httpPost`	`http_post`	`http-post`
`getConfig`	`get_config`	`get-config`
`storeGet` / `getData`	`get_data`	`get-data`
`storeSet` / `setData`	`set_data`	`set-data`
`getPost`	`get_post`	`get-post`
`vfsRead`	`vfs_read`	`vfs-read`
`vfsWrite`	`vfs_write`	`vfs-write`
`vfsDelete`	`vfs_delete`	`vfs-delete`
`vfsExists`	`vfs_exists`	`vfs-exists`
`vfsList`	`vfs_list`	`vfs-list`
`vfsStat`	`vfs_stat`	`vfs-stat`
`emitEvent`	`emit_event`	`emit-event`
`newId`	`new_id`	—
`log`	`log`	`log`
`dbPh`	`db_ph`	—

Runtime-Specific Functions

Rhai Only

Function	Description
`parse_json(str)`	Parse JSON to Rhai value
`to_json(val)`	Convert Rhai value to JSON
`to_upper(str)`	Uppercase
`to_lower(str)`	Lowercase
`replace(str, from, to)`	String replace
`remove(map, key)`	Remove key from map

Lua Only

Function	Description
`Host.jsonEncode(val)`	Encode Lua value to JSON
`Host.jsonDecode(str)`	Decode JSON to Lua value

Lua's sandbox has no native JSON support, so these are provided as host functions.

WASM Limitations

The WIT interface currently provides only raw SQL (db-query, db-execute). High-level DB API (dbInsert, dbFetchOne, etc.), newId, and dbPh are not yet available in WASM.