Adapters

Destination adapters store queryable audit records. Reliability adapters own journals and DLQs. Pair a destination below with FileReliabilityAdapter or CloudflareReliabilityAdapter for durable mode.

AuditLogger.query() throws if the logger is shut down or not initialized. Built-in destination adapters throw from query / bulkInsert / prune if they are closed or not initialized — they do not return an empty page as if no rows existed.

Adapter query is newest-first (ORDER BY id DESC). pagination.limit is required on IAdapter.query. nextCursor is the last row’s id when another page exists.

BunSQLiteAdapter

import { BunSQLiteAdapter } from 'logbun/adapters/bun-sqlite';

const adapter = new BunSQLiteAdapter({
  path: '.logbun/audit.db',
  synchronous: 'FULL',     // FULL | NORMAL | OFF — default FULL
  busyTimeoutMs: 5_000,    // default 5000
});

Not multi-writer HA. Multiple processes must not share one SQLite file as concurrent writers.

Invalid synchronous throws BunSQLiteAdapter: synchronous must be FULL, NORMAL, or OFF. Invalid busyTimeoutMs throws BunSQLiteAdapter: busyTimeoutMs must be a finite integer >= 0.

TursoAdapter

import { TursoAdapter } from 'logbun/adapters/turso';

const adapter = new TursoAdapter({
  url: 'libsql://my-db.turso.io',
  authToken: process.env.TURSO_TOKEN!,
});

Config: { url: string; authToken: string }.

ClickHouseAdapter

import { ClickHouseAdapter } from 'logbun/adapters/clickhouse';

const adapter = new ClickHouseAdapter({
  url: 'http://localhost:8123',
  database: 'analytics',     // default 'default'
  username: 'default',
  password: process.env.CH_PASSWORD,
  retentionDays: 90,         // TTL on CREATE TABLE only; safe integer 1..365000
  queryFinal: true,          // default true — deduped reads
});

• CREATE TABLE IF NOT EXISTS does not migrate an existing MergeTree engine. Old installs need a manual migration to ReplacingMergeTree.
• retentionDays TTL is applied only at CREATE TABLE time. Changing the option later does not ALTER an existing table’s TTL.
• tenant_id is String DEFAULT '' (not nullable); empty round-trips as omitted tenantId on read ('' → undefined).
• Prefer a shared ClickHouse database (not one DB per tenant).
• Invalid retentionDays throws ClickHouseAdapter: retentionDays must be a safe integer in 1..365000.

Exported helpers:

import {
  toClickHouseDateTime,
  fromClickHouseDateTime,
} from 'logbun/adapters/clickhouse';

CloudflareAnalyticsEngineAdapter — Workers Analytics Engine (destination)

Workers-only destination. For the analytics_engine_datasets binding. This is not a reliability adapter and does not use D1/R2/KV or Durable Object SQLite — that is CloudflareReliabilityAdapter (Durable Object journal/DLQ). See the Cloudflare guide for how they pair. Use AE for the warehouse, use the DO adapter for durability.

import { CloudflareAnalyticsEngineAdapter } from 'logbun/adapters/cloudflare-analytics-engine';

const adapter = new CloudflareAnalyticsEngineAdapter({
  binding: env.AUDIT_AE,    // writeDataPoint binding — required for bulkInsert
  dataset: 'logbun_audit',  // SQL dataset — required for query
  accountId: env.ACCOUNT_ID,   // 32-char account id — required for query
  apiToken: env.AE_API_TOKEN,  // Account Analytics Read token — required for query
  // apiBaseUrl: 'https://api.cloudflare.com/client/v4', // default
});

Workers durable stack: pair this destination with CloudflareReliabilityAdapter inside the same Durable Object. The DO owns the journal/DLQ (durability); AE owns the dataset (queryability). Outside a DO, AE alone is volatile. Same idea as ClickHouse/Turso + FileReliabilityAdapter, moved to Workers.

Write-only is expected. binding alone is enough for bulkInsert; dataset + accountId + apiToken alone is enough for query. Provide just the binding where you write, and add the SQL creds where you query. query without creds throws dataset, accountId, and apiToken are required for query.

Fixed schema (one AE data point):

• ≤ 250 writeDataPoint calls per Worker invocation. bulkInsert throws before writing when a batch exceeds 250, so an oversized recovery wave DLQs instead of silently dropping overflow. Hosts must keep maxRecoveryBatch ≤ 250 (the default batcher maxSize is already 100).
• Index ≤ 96 bytes; total blob bytes ≤ 16 KiB per point. Oversized points throw on write.
• Ingest is asynchronous and may be sampled — AE is not a compliance-grade unique store. The DO journal is the durable admission log.
• Shared dataset only — no adapterFactory / database_per_tenant.
• No DELETE: prune is a no-op; the platform retains ~3 months. query always bounds WHERE timestamp >= NOW() - INTERVAL '91' DAY.

Exported helpers:

import {
  ANALYTICS_ENGINE_SCHEMA,
  toAnalyticsEngineDataPoint,
  fromAnalyticsEngineRow,
} from 'logbun/adapters/cloudflare-analytics-engine';

toAnalyticsEngineDataPoint maps a record to the fixed slot schema. fromAnalyticsEngineRow is the inverse used on SQL API rows. Empty string fields round-trip as omitted (undefined), same as ClickHouse tenant_id.