SDK modules

Besides the globals in the Handler API, MicroHost ships four optional modules. They are reserved import specifiers served by the host, written in plain JavaScript, versioned with the SDK API version (currently 1), and loaded lazily: a handler that imports none of them does no extra work.

Module (import)	Manifest `sdk` name	Purpose	Needs	Engines
`microhost/sql`	`sql`	The `sql` tagged template for composable, parameterized SQL.	nothing by itself	Wasm, native, Linux
`microhost/db` (alias `db`)	`db`	Object rows, table objects, paging, `all`/`one`/`run`/`tx`, `id()`, `now()`.	the database grant	Wasm, native, Linux
`microhost/auth`	`auth`	`hashPassword`, `verifyPassword` (Argon2id).	no database grant	Wasm, native, Linux
`microhost/session`	`session`	Cookie sessions stored in your database.	the database grant, a `site_sessions` table	all engines (see below)

Reference pages: Database SDK for sql and db, Auth and sessions for auth and session.

Status: session on native and Linux. Implemented once in the shared SDK layer for every engine. Verified end to end on Wasm (dev VM, 2026-10-25); native and Linux load the same module and dispatch, but a full cycle against real SQLite is not yet tested there. microhost/auth, microhost/sql and microhost/db work on all three engines.

Importing

import { sql } from "microhost/sql";
import { all, one, run, tx, id, now, tasks, tables } from "microhost/db";   // same as: from "db"
import { hashPassword, verifyPassword } from "microhost/auth";
import { create, get, destroy, destroyAll } from "microhost/session";

The names are matched exactly. db is an exact alias of microhost/db. Your own files can never shadow them, because your relative imports must start with ./ or ../ and end in .js.
Only static import works; dynamic import() does not.
microhost/db imports microhost/sql internally. You do not need to list sql separately when you list db.
The module named microhost (with defineSite, route, ...) is not a handler module. It exists only inside microhost.config.js.

Requesting modules in the manifest

List the modules your release uses in the manifest's sdk array:

{ "schemaVersion": 1, "sdk": ["db", "auth", "session"], "permissionsRequested": { "database": true } }

or, in microhost.config.js, defineSite({ sdk: ["db"], ... }).

Rules (checked at deploy; a bad list rejects the manifest):

Allowed names: auth, db, session, sql. Names must be unique; unknown names are rejected. The stored list is sorted.
db also enables sql internally.
Current behaviour when the list is absent: a manifest without an sdk key leaves every module importable (subject to the site switch below). Once an sdk list is present, only the listed modules (plus sql for db) can be imported; others fail with sdk_module_disabled. Treat the list as required documentation of intent and do not rely on omission. The resolved-manifest builder drops an empty sdk array, so an empty list from microhost.config.js is the same as omitting it.

The per-site module switch

An administrator can disable a module for a site without redeploying:

GET /admin/api/v1/sites/{id}/sdk-modules returns { site_id, release_id, version, requested, disabled, effective, editable }.
PATCH /admin/api/v1/sites/{id}/sdk-modules with { "expected_version": <n>, "disabled": ["session"] } replaces the disabled list. Unknown or duplicate names give 400 invalid_sdk_modules; a stale version gives 409 sdk_modules_version_conflict. It needs site write access, and it is audited.
The effective set is requested minus disabled: the intersection of what the release asked for and what the site allows. Disabling sql also disables db; the db switch and the db alias are the same switch.
The change applies to the next request. It does not change the release.
If a module is disabled (or not requested while an sdk list exists), importing it fails with sdk_module_disabled. Visitors see HTTP 500; the code appears in operator diagnostics. The check happens before any schema or source is read.

The switch is a developer convenience, not authorization. It never grants anything. In particular, ctx.db is governed only by the database grant: disabling db does not remove raw ctx.db, and enabling db does not give database access. Every SDK database call goes through the same broker checks as ctx.db.

Versioning

The SDK API version (SDK_API_VERSION = 1) is pinned in each release record. Module behaviour for existing releases does not change when the platform upgrades. A behaviour change requires a new SDK version and new release pinning. Table exports of microhost/db come from the release's sealed schema snapshot (see Migrations); a release created before snapshots existed gets none until it is redeployed, but raw ctx.db keeps working for it.