v1.2.0

walq 1.2.0

walq 1.2 adds managed SQLite connections with opt-in storage worker threads. Synchronous SQLite calls can now run outside the main event loop without changing queue handlers.

Packages

All public packages are released at 1.2.0:

• @walq/core — version alignment; no core API changes
• @walq/sqlite-common — shared connection lifecycle and worker RPC
• @walq/better-sqlite3 — managed factory and optional worker execution
• @walq/sqlite — managed factory and optional worker execution

Highlights

• Both adapters export an always-async createStorage({ filename, worker? }) factory that opens and owns the connection.
• worker: true runs synchronous SQLite operations in one dedicated thread per storage instance. Worker execution is currently verified on Node.js only.
• Worker mode prevents SQLite execution and lock waits from directly blocking the main thread; it does not promise higher throughput or remove SQLite write locks. Queue handlers still run in the main thread.
• worker defaults to false; direct mode still executes synchronous SQLite work in the calling thread.
• Both modes expose an idempotent close() that rejects new calls, drains accepted operations, and closes the connection.
• Worker mode bounds outstanding calls with maxPending (default 1024); calls beyond the limit reject.
• Worker failures reject outstanding calls. Mutations are never automatically replayed because their commit outcome may be unknown.
• Default connection settings are WAL, synchronous = FULL, and a 5000-millisecond busy timeout. Override them with the initialization SQL option.

Install

Using the built-in SQLite adapter:

pnpm add @walq/core@1.2.0 @walq/sqlite@1.2.0

Using better-sqlite3:

pnpm add @walq/core@1.2.0 @walq/better-sqlite3@1.2.0 better-sqlite3

@walq/sqlite-common is installed automatically by the adapters.

Managed storage

import { Queue } from '@walq/core'
import { createStorage } from '@walq/sqlite'

const storage = await createStorage({
  filename: './queue.sqlite',
  worker: true,
})

const queue = new Queue<{ to: string }>('email', { storage })
const processor = queue.process(async ({ to }) => console.log(`Email ${to}`))
await queue.add({ to: 'user@example.com' })

// On shutdown, stop processors before closing storage.
await processor.close()
await storage.close()

For better-sqlite3, import createStorage from @walq/better-sqlite3 instead.

Compatibility

Existing externally owned betterSqlite3(db) and sqlite(db) APIs remain unchanged. Their callers still configure and close the connections themselves.

This release does not change the database format: both adapters continue using schema v12. Existing databases can be reopened without a format conversion. Stop processors and back up file-backed databases before upgrading.

See the @walq/sqlite README and @walq/better-sqlite3 README for connection settings and shutdown guidance.