Plugins

Three hooks wrapped around every adapter call. The same surface that powers observability, multi-tenancy, and audit. Zero overhead when nothing is registered.

#The shape

A plugin is an object with a name and an initialize function. The engine calls initialize once with a PluginContext the plugin uses to attach hooks.

12 lines


1import type { ZanithPlugin } from 'zanith';
2 
3const audit: ZanithPlugin = {
4  name: 'audit',
5  initialize(ctx) {
6    ctx.onResult(({ sql, rowCount, elapsedMs }) => {
7      auditLog.write({ sql, rowCount, elapsedMs });
8    });
9  },
10};
11 
12await createZanith({ adapter, models, plugins: [audit] });

#The three hooks

Hook	Fires	Can it mutate?
`onQuery`	Before every `execute` / `executeRaw`	Yes — return a `{ sql, params }` to replace the query.
`onResult`	After a successful query	No — observation only.
`onError`	When a query throws	No — observation only. The error is rethrown to the caller after every hook runs.

Hooks are async. The engine awaits each one in registration order, so a slow hook slows the query. Use fire-and-forget inside the hook body if you need to ship to a remote sink.

#Hook payloads

#QueryHookInfo

6 lines


1interface QueryHookInfo {
2  sql: string;
3  params: unknown[];
4  kind: 'execute' | 'executeRaw';
5  dialect: string; // 'postgres' | 'sqlite' | …
6}

#ResultHookInfo

8 lines


1interface ResultHookInfo {
2  sql: string;
3  params: unknown[];
4  rowCount: number;
5  elapsedMs: number;
6  /** First five rows — for sample logging. */
7  sampleRows?: unknown[];
8}

#ErrorHookInfo

6 lines


1interface ErrorHookInfo {
2  sql: string;
3  params: unknown[];
4  error: Error;
5  elapsedMs: number;
6}

#onQuery — interception

onQuery can return a replacement { sql, params }. Each registered hook sees the previous hook's output, so transformations compose. The multi-tenancy plugins use this to inject tenant_id = $N into every WHERE clause.

9 lines


1const sqlComment: ZanithPlugin = {
2  name: 'sql-comment',
3  initialize(ctx) {
4    ctx.onQuery(({ sql, params }) => ({
5      sql: `/* ${process.env.SERVICE_NAME ?? 'app'} */ ${sql}`,
6      params,
7    }));
8  },
9};

#Registration

11 lines


1import { createZanith, consoleLogger, slowQueryLogger } from 'zanith';
2 
3await createZanith({
4  adapter,
5  models,
6  plugins: [
7    consoleLogger({ slowMs: 200 }),
8    slowQueryLogger({ thresholdMs: 1000, onSlow: (info) => sentry.captureMessage('slow query', { extra: info }) }),
9    audit,
10  ],
11});

Plugin names must be unique. Registering two plugins with the same name throws at startup.

#What plugins do not see

Operation	Hooks fire?
`adapter.execute(query)`	Yes — `onQuery`, `onResult` / `onError`.
`adapter.executeRaw(sql, params)`	Yes.
Inside `db.transaction(...)`	Yes — every query in the tx runs through hooks.
`adapter.stream(query)`	Only `onQuery` fires. `onResult` would have to wait for full materialisation, which defeats streaming.
Migrations (`zanith migrate up`)	Yes — they run through the same adapter.

#Built on the same surface

Every plugin Zanith ships uses this exact API — see Observability for the four loggers and Multi-tenancyfor the three isolation strategies. There's no privileged interface — your audit plugin and openTelemetryPlugin see the same payloads.