Honker Documentation

The honker-node binding provides typed JavaScript wrappers for high-level Honker features. Use these wrappers instead of raw SQL for better type safety and developer experience. Supported wrappers include:

• Queues: For enqueue → claim → ack workflows.
• Streams
• Locks
• Pub/Sub: For updateEvents() and tx.notify() patterns.
• Scheduler

If you need to execute raw SQL, you can still use the db.query(...) or tx.query(...) methods.

Honker provides several primitives for SQLite-backed applications:

• Pub/Sub: Ephemeral notify() / listen() semantics.
• Streams: Durable streams with per-consumer offsets.
• Queues: At-least-once queues with retries, delayed jobs, priority, visibility timeouts, and dead-letter rows.
• Scheduling: Time-trigger scheduling using cron or @every <duration> expressions.
• Concurrency Control: Named locks and rate limits.
• Transactional Outbox: Ability to enqueue work within the same transaction as business data updates.

Before using the JVM binding, you must build the native extension using Cargo.

cargo build -p honker-extension

Honker does not provide specific plugins for ORMs. To integrate, load the Honker extension on your existing ORM connection, execute honker_bootstrap(), and call the Honker SQL functions within your ORM's transaction blocks.

Supported frameworks include:

• SQLAlchemy, SQLModel, Django, Drizzle, Kysely, sqlx, GORM, ActiveRecord, Ecto, Hibernate, jOOJ, MyBatis, and Exposed.

Honker is available across multiple ecosystems. Use the following commands to install the respective bindings:

• Python: pip install honker
• Node.js: npm install @russellthehippo/honker-node
• Ruby: gem install honker
• .NET / C#: dotnet add package Honker

By default, honker-rs uses polling. You can opt into experimental core backends using OpenOptions.

Note: Explicitly requesting a backend that is not enabled via Cargo features will cause the application to fail loudly.

• kernel: Requires the kernel-watcher feature.
• shm: Requires the shm-fast-path feature and SQLite WAL mode.

let opts = honker::OpenOptions::default().watcher_backend("kernel")?;
let db = honker::Database::open_with_options("app.db", opts)?;

You can initialize a database, create a queue, and process jobs using the following pattern. Jobs are enqueued with JSON payloads and claimed by workers using a unique identifier.

let db = honker::Database::open("app.db", "./libhonker_ext.dylib")?;
let q = db.queue("emails");

q.enqueue(serde_json::json!({ "to": "alice@example.com" }))?;

if let Some(job) = q.claim_one("worker-1")? {
    send_email(&job.payload);
    job.ack()?;
}

Install the Honker NuGet package to use durable queues, streams, pub/sub, and time-trigger scheduling on SQLite in your C# applications.

The package includes bundled Honker SQLite extensions for the following platforms:

• linux-x64
• linux-arm64
• osx-x64
• osx-arm64
• win-x64

dotnet add package Honker

To run the provided examples in the honker-node package, ensure you have installed dependencies and built the native bindings if you haven't already. You can then execute specific example files using node.

npm install
npx napi build --platform --release    # if you haven't already
node examples/<name>.js

Before building or using honker-cpp, ensure you have Zig 0.15+, a C++17 compiler, SQLite development headers, nlohmann-json headers, and the Honker SQLite extension installed. The C++ binding requires SQLite to be built with loadable extension support.

# macOS with Homebrew
brew install sqlite nlohmann-json

# macOS with MacPorts
sudo port install sqlite3 nlohmann-json

# Ubuntu / Debian
sudo apt-get install libsqlite3-dev nlohmann-json3-dev

# Fedora
sudo dnf install sqlite-devel json-devel

# Arch
sudo pacman -S sqlite nlohmann-json