---
title: "Migrate from 0.2"
description: "Breaking changes from logbun 0.2.1 to 1.0 — reliability subpaths, DLQ ids, host maintenance."
---

> Documentation Index
> Fetch the complete documentation index at: https://logbun-docs.abshahin.workers.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from 0.2

Logbun 1.0 is runtime-agnostic: the root package is pure ES2022 / Web API code. Filesystem and Cloudflare durability live on explicit subpaths.

## 1. Durable mode requires a persistent `reliability` adapter

**Before (0.2.x):**

```ts
new AuditLogger({
  namespace: 'app',
  mode: 'durable',
  dataDir: '.logbun',
  wal: { fsync: true },
  dlqFsync: true,
  encryptionKey: '...',
  instanceLock: true,
  adapter,
});
```

**After (1.0):**

```ts
import { FileReliabilityAdapter } from 'logbun/durability/filesystem';

new AuditLogger({
  namespace: 'app',
  mode: 'durable',
  reliability: new FileReliabilityAdapter({
namespace: 'app',
dataDir: '.logbun',
wal: { fsync: true },
dlq: { fsync: true },
encryptionKey: '...',
instanceLock: true,
  }),
  adapter,
});
```

Missing or non-persistent reliability throws **synchronously** in the constructor when `mode: 'durable'`.

## 2. Filesystem config moved off root `LogbunConfig`

| 0.2.x config | 1.0 location |
|--------------|--------------|
| `dataDir` | `FileReliabilityAdapter({ dataDir })` |
| `wal.*` | `FileReliabilityAdapter({ wal })` |
| `dlqFsync` | `FileReliabilityAdapter({ dlq: { fsync } })` |
| `maxWalBytes` / `walSoftLimitBytes` | `FileReliabilityAdapter({ maxWalBytes })` |
| `maxDlqFiles` | `FileReliabilityAdapter({ dlq: { maxEntries } })` |
| `encryptionKey` | `FileReliabilityAdapter({ encryptionKey })` |
| `instanceLock` | `FileReliabilityAdapter({ instanceLock })` |

## 3. DLQ uses opaque IDs (not paths)

```ts
const dead = await audit.listDlq({ includeDead: true });
await audit.requeueDead(dead[0]!.id);
await audit.deleteDead(dead[0]!.id);
```

Filesystem paths may appear in `metadata.path` for diagnostics only.

## 4. Host-scheduled maintenance

Removed: `RetentionConfig.cronExpression`, `RetryConfig.scanIntervalMs` / `initialDelayMs`, internal `Bun.cron` retention and recurring DLQ scan timers.

Added: `flush()`, `runMaintenance()`, `retryDlqNow()`. Short batching `flushInterval` timers remain.

## 5. Bun SQLite path rename

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

`logbun/adapters/sqlite` is removed in 1.0.

## 6. Path helpers and instance lock leave the root export

```ts
import {
  FileReliabilityAdapter,
  resolveLogbunDir,
  resolveDataDir,
  InstanceLock,
  InstanceLockError,
} from 'logbun/durability/filesystem';
```

Root still exports pure helpers: `sanitizeNamespace`, `sanitizeTenantKey`, `isTenantIdPresent`, crypto (`INTEGRITY_GENESIS`, `verifyIntegrityChain`, `normalizeEncryptionKey`), and UUIDv7. 1.0 also exports `MemoryReliabilityAdapter`, `DurableAdmissionSchedulingError`, and `isDurableAdmissionSchedulingError`.

## 7. Deno permissions

```sh
deno run --allow-read=./.logbun --allow-write=./.logbun --allow-sys=uid,gid your_app.ts
```

Add `--allow-run` when automatic recovery of a crashed process’s instance lock is required.

## 8. Cloudflare Workers

Import `CloudflareReliabilityAdapter` from `logbun/durability/cloudflare` inside a Durable Object. Standard Workers call a **DO binding**; do not put journal/DLQ on D1. Pass `waitUntil` via `LogbunRequestContext`. Volatile request runtimes: `await fireAsync(...); await flush()`.

## Preserved

- `AuditLogger`, `IAdapter`, batching, tenancy, events, safety, integrity chain
- `fire` / `fireAsync` / query / retry semantics (minus timer scheduling)
- Optional peers: Turso, ClickHouse, Hono, Elysia
- npm package name `logbun`; Deno consumes the npm artifact

Source: https://logbun-docs.abshahin.workers.dev/migration/index.mdx