Production

What is it?

Operator-focused guidance for deploying Wolbarg 0.6.0. This page prefers accuracy over marketing. For concurrency internals, see Architecture and Concurrency.

Choosing a backend

SQLite

Configuration

sqlite("./data/memory.db")
// or
{ provider: "sqlite", url: "./data/memory.db" }

Concurrency

• WAL + BEGIN IMMEDIATE + busy retries
• concurrency.multiProcess: true raises timeouts for multiple OS processes sharing one file
• Exhausted retries throw StorageLockedError (WOLBARG_STORAGE_LOCKED)
• DatabaseSync runs on the Node event loop — isolate heavy writers from latency-sensitive API processes, or prefer Postgres

Backups

• Stop writers or use SQLite online backup / filesystem snapshots of the DB and -wal / -shm consistently
• Prefer export() for portable bundles when the file contains a single organization
• Multi-org files: export/checkpoint/import/rollback refuse — split by organization first

Migrations

Schema migrations run automatically on open() / ready(). Do not edit wolbarg_meta by hand. Keep a backup before upgrading major/minor releases that mention schema changes.

Limitations

• No cross-process subscribe()
• File-level transfer cannot org-filter rows
• Under extreme lock contention, callers must handle StorageLockedError

PostgreSQL

Configuration

postgres({
  connectionString: process.env.DATABASE_URL!,
  schema: "wolbarg",      // recommended for shared DBs
  maxPoolSize: 20,        // default; raise only if the host allows
  // ssl: false,          // opt out of default require for remote (not recommended)
})

Install: npm install pg. Enable pgvector when you want HNSW ANN:

CREATE EXTENSION IF NOT EXISTS vector;

Without a usable vector type, Wolbarg falls back to blob cosine search.

SSL / TLS

• Non-loopback hosts without sslmode / ssl in the URL get sslmode=require
• Loopback (localhost, 127.0.0.1, ::1) is left unchanged for local Docker
• Overrides: ssl: false / "disable" (warns on remote), ssl: true / "require", "prefer"

Schema namespacing

schema creates a dedicated Postgres schema for tables, indexes, and a suffixed NOTIFY channel (wolbarg_events_<schema>). Use this when:

• Keeping Wolbarg out of shared public
• Running multiple deployments in one database
• Hosting different embedding dimensions side by side

Names: ^[A-Za-z_][A-Za-z0-9_$]*$, max 48 characters.

Pooling and timeouts

Session GUCs (via connection URL): statement_timeout=30000, lock_timeout=10000, idle_in_transaction_session_timeout=60000, plus HNSW search settings. Deadlock (40P01) and serialization (40001) retries use full-jitter backoff.

Backups

Use normal Postgres backup tooling (pg_dump, continuous WAL archiving, managed snapshots). Wolbarg does not ship a Postgres export/checkpoint API.

Migrations

DDL is applied on open. Catalog probes are schema-scoped. Prefer throwaway schemas in tests.

Hybrid search and rerank

Fail-closed since 0.6.0:

Configure keywordSearch: bm25() (or a custom provider) before enabling hybrid.

Telemetry

• SQLite telemetry DB only — Postgres telemetry is not implemented
• captureQueries defaults to false (privacy)
• Keep telemetry on a separate file from memory storage
• Studio (separate product) reads the telemetry database — see Observability

Security trust boundary

• organization is a data namespace, not proof of identity
• Authenticate/authorize in your app before constructing a tenant context
• Do not pass end-user-controlled embedding/LLM/rerank baseUrl values (SSRF)
• Keep API keys in process env / .wolbarg/.env (gitignored by wolbarg init)

Troubleshooting

Performance notes

• Insert coalescing amortizes commits (SQLite) / unnest batches (Postgres)
• Embedding cache cuts repeated provider calls; Postgres cache is L1-only
• HNSW is built lazily before first KNN (Postgres)
• Published website benchmark numbers are from a v0.4 mock suite — re-benchmark before citing 0.6.0 numbers

What Wolbarg does not provide

• Application authentication / authorization
• Hosted control plane
• Multi-process SQLite subscribe
• Postgres telemetry store
• Graph memory APIs (removed in 0.6.0)
• Guaranteed zero lock contention under arbitrary writer counts

Related pages

• What's New
• Limitations
• Configuration
• Concurrency
• Migration
• Observability