Honker

https://honker.dev/
Admin
Honker provides durable queues, streams, pub/sub, and time-trigger scheduling functionality, all...
Tokens:42,097
Snippets:488
Trust Score:5.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Honker Go Binding

Source: https://honker.dev/languages/go

Use 'go get' to install the Honker Go binding. Ensure the compiled Honker extension library is available on disk.

```go
go get github.com/russellromney/honker-go

```

--------------------------------

### Full Loop Example

Source: https://honker.dev/reference/extension

An example demonstrating a full producer-consumer loop using Honker functions within raw SQLite.

```APIDOC
## Example: full loop from raw SQLite

```sql
.load ./libhonker_ext
SELECT honker_bootstrap();


-- Producer
SELECT honker_enqueue('emails', '{"to":"alice"}', NULL, NULL, 0, 3, NULL);
SELECT honker_enqueue('emails', '{"to":"bob"}', NULL, 30, 0, 3, NULL);


-- Consumer
SELECT honker_claim_batch('emails', 'worker-1', 32, 300);
-- → [{"id":1,"queue":"emails","payload":"{\"to\":\"alice\"}","worker_id":"worker-1","attempts":1,"claim_expires_at":1700000300}]


-- Ack
SELECT honker_ack(1, 'worker-1');  -- 1

```
```

--------------------------------

### Python: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, creates a queue, enqueues a job, and claims it for processing in Python. Ensure the 'honker' library is installed.

```python
import honker

db = honker.open("app.db")        # opens or creates the file
q = db.queue("greetings")

q.enqueue({"name": "world"})

job = q.claim_one("worker-1")
print(f"hello, {job.payload['name']}!")
job.ack()
```

--------------------------------

### Install Honker Node Package

Source: https://honker.dev/languages/node

Install the Honker Node.js package using npm. This command installs the package and its native bindings.

```bash
npm install @russellthehippo/honker-node
```

--------------------------------

### Install Honker Bun Package

Source: https://honker.dev/languages/bun

Use `bun add` to install the Honker package for Bun. This command installs the necessary dependencies for using Honker with Bun.

```bash
bun add @russellthehippo/honker-bun
```

--------------------------------

### Enqueue a Job

Source: https://honker.dev/reference/extension

Add a job to the 'emails' queue. This example enqueues a job with immediate execution and another with a 30-second delay.

```sql
SELECT honker_enqueue('emails', '{"to":"alice"}', NULL, NULL, 0, 3, NULL);
SELECT honker_enqueue('emails', '{"to":"bob"}', NULL, 30, 0, 3, NULL);

```

--------------------------------

### Install Honker with pip

Source: https://honker.dev/languages/python

Install the Honker Python package using pip. The wheel includes native extensions on supported platforms.

```bash
pip install honker
```

--------------------------------

### Bootstrap Honker Extension

Source: https://honker.dev/guides/orm/elixir

Run the `honker_bootstrap()` SQL function once when your application starts. This ensures the Honker extension is properly initialized.

```elixir
def start(_type, _args) do
  children = [MyApp.Repo, ...]
  {:ok, pid} = Supervisor.start_link(children, strategy: :one_for_one)
  Ecto.Adapters.SQL.query!(MyApp.Repo, "SELECT honker_bootstrap()", [])
  {:ok, pid}
end

```

--------------------------------

### Worker Example for TypedQueue with SQLModel

Source: https://honker.dev/guides/orm/python

A worker process example demonstrating how to consume jobs from a Honker queue using `TypedQueue`. It shows claiming jobs, parsing the Pydantic payload, performing an action (sending email), and acknowledging the job.

```python
import asyncio, honker

db = honker.open("app.db")


async def run():
    async for job in db.queue("emails").claim("worker-1"):
        email: EmailJob = emails.parse(job.payload)  # validated
        await send(email.to, email.subject, email.body)
        job.ack()

asyncio.run(run())

```

--------------------------------

### Example Usage of Queue and Notify with SQLAlchemy

Source: https://honker.dev/guides/orm/python

Demonstrates how to use the `Queue` class and `notify` function within a SQLAlchemy session and transaction. This shows enqueuing an email job and notifying about a new order.

```python
from sqlalchemy.orm import Session
from yourapp.honker_ext import Queue, notify


emails = Queue("emails")


with Session(engine) as s, s.begin():
    s.add(Order(user_id=42))
    emails.enqueue(s, {"to": "alice@example.com"})
    notify(s, "orders", {"id": 42})

```

--------------------------------

### Subscribe with Auto-Offset Save (C++)

Source: https://honker.dev/guides/streams

This C++ example shows how to subscribe to a stream and process events. It uses a subscription object that handles offset saving automatically.

```cpp
#include "honker.hpp"


#include <chrono>
#include <thread>


int main() {
    honker::Database db{"app.db", "./libhonker_ext.dylib"};
    auto s = db.stream("orders");
    auto sub = s.subscribe("email-worker", 1000, std::chrono::milliseconds(100));


    for (;;) {
        if (auto event = sub.next()) {
            send_order_email(event->payload());
        }
    }
}
```

--------------------------------

### Get Honker for Go

Source: https://honker.dev/getting-started

Fetch the Honker Go binding. Requires Go 1.25+. You also need the compiled libhonker_ext.{dylib,so,dll} on disk.

```bash
go get github.com/russellromney/honker-go
```

--------------------------------

### Install Honker Gem

Source: https://honker.dev/languages/ruby

Install the Honker gem using RubyGems. Ensure your sqlite3 build supports loadable extensions for full functionality.

```ruby
gem install honker
```

--------------------------------

### Install Honker .NET Package

Source: https://honker.dev/languages/dotnet

Add the Honker package to your .NET project using the dotnet CLI. This package integrates with Microsoft.Data.Sqlite and includes the Honker extension.

```csharp
dotnet add package Honker

```

--------------------------------

### Example Usage of TypedQueue with SQLModel and Pydantic

Source: https://honker.dev/guides/orm/python

Illustrates using the `TypedQueue` with a Pydantic model for typed payloads in SQLModel. It shows enqueuing an email job with structured data.

```python
from pydantic import BaseModel, EmailStr
from sqlmodel import Session
from yourapp.honker_ext import TypedQueue


class EmailJob(BaseModel):
    to: EmailStr
    subject: str
    body: str


emails = TypedQueue("emails", EmailJob)


with Session(engine) as s, s.begin():
    s.add(Order(user_id=42))
    emails.enqueue(s, EmailJob(
        to="alice@example.com", subject="Hi", body="..."
    ))

```

--------------------------------

### SQL: Your First Queue

Source: https://honker.dev/getting-started

Demonstrates enqueuing and claiming jobs using SQL commands. Requires the Honker extension to be loaded.

```sql
.load ./libhonker_ext
SELECT honker_bootstrap();


SELECT honker_enqueue('greetings', '{"name":"world"}',
                      NULL, NULL, 0, 3, NULL);


SELECT honker_claim_batch('greetings', 'worker-1', 1, 300);
-- Then ack the claimed job id from the JSON result above.
SELECT honker_ack(1, 'worker-1');
```

--------------------------------

### Go: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, creates a queue, enqueues a job, and claims it for processing in Go. Requires the 'honker-go' package and the extension library.

```go
package main


import (
    "fmt"
    honker "github.com/russellromney/honker-go"
)


func main() {
    db, _ := honker.Open("app.db", "./libhonker_ext.dylib")
    defer db.Close()


    q := db.Queue("greetings", honker.QueueOptions{})
    q.Enqueue(map[string]any{"name": "world"}, honker.EnqueueOptions{})


    job, _ := q.ClaimOne("worker-1")
    var p map[string]any
    job.UnmarshalPayload(&p)
    fmt.Printf("hello, %s!\n", p["name"])
    job.Ack()
}
```

--------------------------------

### Java: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, creates a queue, enqueues a job, and claims it for processing in Java. Uses the Honker library and requires the extension library.

```java
import dev.honker.Honker;


try (var db = Honker.open("app.db")) {
    var q = db.queue("greetings");


    q.enqueue("{\"name\":\"world\"}");


    var job = q.claimOne("worker-1").orElseThrow();
    System.out.println("claimed " + job.payloadJson());
    job.ack();
}
```

--------------------------------

### Watcher Panic Message Example

Source: https://honker.dev/reference/watcher-backends

This is an example of the panic message generated by the watcher when the database file identity changes. It indicates the expected and found file identifiers and advises to close and reopen the database.

```text
honker: database file replaced: expected (dev=X, ino=Y), found (dev=X, ino=Z)
at "/path/to/app.db". The watcher cannot recover; close the Database
and reopen with honker.open().
```

--------------------------------

### .NET: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, creates a queue, enqueues a job, and claims it for processing in C#. Uses the Honker NuGet package.

```csharp
using Honker;


using var db = Database.Open("app.db");
var q = db.Queue("greetings");

q.Enqueue(new { name = "world" });


var job = q.ClaimOne("worker-1");
Console.WriteLine($"hello, {job!.Payload.GetProperty("name").GetString()}!");
job.Ack();
```

--------------------------------

### C++: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, creates a queue, enqueues a job, and claims it for processing in C++. Uses the honker C++ library and requires the extension library.

```cpp
#include "honker.hpp"


#include <iostream>


int main() {
    honker::Database db{"app.db", "./libhonker_ext.dylib"};
    auto q = db.queue("greetings");


    q.enqueue(R"({"name":"world"})");


    if (auto job = q.claim_one("worker-1")) {
        auto payload = nlohmann::json::parse(job->payload());
        std::cout << "hello, " << payload["name"].get<std::string>() << "!\n";
        job->ack();
    }
}
```

--------------------------------

### Initialize Honker Database Connection (C++)

Source: https://honker.dev/languages/cpp

Establishes a connection to the Honker database. Ensure the extension library path and shared memory name are correctly specified.

```cpp
#include "honker.hpp"


honker::Database db{"app.db", "./libhonker_ext.dylib", "shm"};

```

--------------------------------

### Node.js: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, creates a queue, enqueues a job, and claims it for processing in Node.js. Requires the '@russellthehippo/honker-node' package.

```javascript
const { open } = require('@russellthehippo/honker-node');
const db = open('app.db');
const q = db.queue('greetings');

q.enqueue({ name: 'world' });

const job = q.claimOne('worker-1');
console.log(`hello, ${job.payload.name}!`);
job.ack();
```

--------------------------------

### Rust: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, creates a queue, enqueues a job, and claims it for processing in Rust. Uses serde_json for payload handling. Ensure the 'honker' crate is added as a dependency.

```rust
use honker::{Database, QueueOpts, EnqueueOpts};
use serde_json::json;


fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Database::open("app.db")?;
    let q = db.queue("greetings", QueueOpts::default());


    q.enqueue(&json!({"name": "world"}), EnqueueOpts::default())?;


    if let Some(job) = q.claim_one("worker-1")? {
        let payload: serde_json::Value = serde_json::from_slice(&job.payload)?;
        println!("hello, {}!", payload["name"]);
        job.ack()?;
    }


    Ok(())
}
```

--------------------------------

### Initialize Kysely with better-sqlite3 and Honker Extension

Source: https://honker.dev/guides/orm/javascript

This snippet shows how to set up a Kysely database instance using better-sqlite3, load the Honker SQLite extension, and run the bootstrap function.

```javascript
import Database from 'better-sqlite3';
import { Kysely, SqliteDialect } from 'kysely';


const sqlite = new Database('app.db');
sqlite.loadExtension('/path/to/libhonker_ext');
sqlite.prepare('SELECT honker_bootstrap()').run();


export const db = new Kysely<DB>({ dialect: new SqliteDialect({ database: sqlite }) });
```

--------------------------------

### Kotlin: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, creates a queue, enqueues a job, and claims it for processing in Kotlin. Uses the honker Kotlin extension and requires the extension library.

```kotlin
import dev.honker.kotlin.honker


honker("app.db").use { db ->
    val q = db.queue("greetings")


    q.enqueueJson("{\"name\":\"world\"}")


    val job = q.claimOne("worker-1").orElseThrow()
    println("claimed ${job.payloadJson()}")
    job.ack()
}
```

--------------------------------

### Load Honker Extension and Bootstrap

Source: https://honker.dev/reference/extension

Load the Honker extension library and initialize the necessary database tables. This should be called once per database connection.

```sql
.load ./libhonker_ext
SELECT honker_bootstrap();

```

--------------------------------

### Initialize Drizzle ORM with SQLite and Load Extension

Source: https://honker.dev/guides/orm/javascript

Set up the Drizzle ORM instance by connecting to a SQLite database file and loading a native extension. Ensure the extension is loaded before initializing Drizzle.

```javascript
import Database from 'better-sqlite3';
import { drizzle } from 'drizzle-orm/better-sqlite3';


const sqlite = new Database('app.db');
sqlite.loadExtension('/path/to/libhonker_ext');
sqlite.prepare('SELECT honker_bootstrap()').run();


export const db = drizzle(sqlite);
```

--------------------------------

### Queue Operations

Source: https://honker.dev/languages/go

Demonstrates creating a queue, enqueuing a job with payload, claiming a job for processing, and acknowledging its completion.

```go
q := db.Queue("emails", honker.QueueOptions{})
_, _ = q.Enqueue(map[string]any{"to": "alice@example.com"}, honker.EnqueueOptions{})


job, _ := q.ClaimOne("worker-1")
if job != nil {
    _ = job.Ack()
}

```

--------------------------------

### Honker Queue Usage Example

Source: https://honker.dev/guides/orm/javascript

Demonstrates enqueuing a job with specific data into a Honker queue using a transaction. Ensure the job interface matches the expected payload structure.

```typescript
interface EmailJob { to: string; subject: string }


const emails = new Queue<EmailJob>(db, 'emails');


const createOrder = db.transaction((userId: number, email: EmailJob) => {
  db.prepare('INSERT INTO orders (user_id) VALUES (?)').run(userId);
  emails.enqueue(email);
});
createOrder(42, { to: 'alice@example.com', subject: 'Hi' });

```

--------------------------------

### Open Honker with different watcher backends (Python)

Source: https://honker.dev/reference/watcher-backends

Demonstrates opening a Honker database with the default polling backend, the experimental kernel backend, and the experimental shm backend.

```python
db = honker.open("app.db")                              # polling, the default
db = honker.open("app.db", watcher_backend="kernel")    # experimental: OS file events
db = honker.open("app.db", watcher_backend="shm")       # experimental: mmap WAL index, WAL only

```

--------------------------------

### SQL Interface for Honker Operations

Source: https://honker.dev/

Illustrates direct SQL commands for initializing Honker, enqueuing jobs, and claiming/acknowledging batches. Assumes the Honker extension is loaded.

```sql
.load ./libhonker_ext
SELECT honker_bootstrap();


BEGIN;
INSERT INTO orders (id, total) VALUES (42, 99);
SELECT honker_enqueue('emails', '{"to":"alice","order_id":42}',
                      NULL, NULL, 0, 3, NULL);
COMMIT;


SELECT honker_claim_batch('emails', 'worker-1', 32, 300);
SELECT honker_ack_batch('[1,2,3]', 'worker-1');
```

--------------------------------

### Ruby: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, creates a queue, enqueues a job, and claims it for processing in Ruby. Requires the 'honker' gem and the extension library.

```ruby
require "honker"

db = Honker::Database.new("app.db", extension_path: "./libhonker_ext.dylib")
q = db.queue("greetings")

q.enqueue({name: "world"})

job = q.claim_one("worker-1")
puts "hello, #{job.payload[:name]}!"
job.ack
```

--------------------------------

### Initialize Honker Database Connection

Source: https://honker.dev/languages/ruby

Establish a connection to the Honker database using the `Honker::Database` class. Specify the database file and the path to the Honker extension.

```ruby
require "honker"

db = Honker::Database.new(
  "app.db",
  extension_path: "./libhonker_ext.dylib",
  watcher_backend: "shm",
)
```

--------------------------------

### Bun: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, creates a queue, enqueues a job, and claims it for processing in Bun. Uses the '@russellthehippo/honker-bun' package and the extension library.

```javascript
import { open } from "@russellthehippo/honker-bun";


const db = open("app.db", "./libhonker_ext.dylib");
const q = db.queue("greetings");

q.enqueue({ name: "world" });


const job = q.claimOne("worker-1")!;
console.log(`hello, ${(job.payload as { name: string }).name}!`);
job.ack();
```

--------------------------------

### Elixir: Your First Queue

Source: https://honker.dev/getting-started

Opens a database, enqueues a job, and claims it for processing in Elixir. Uses the Honker module and requires the extension library.

```elixir
{:ok, db} = Honker.open("app.db", extension_path: "./libhonker_ext.dylib")


{:ok, _id} = Honker.Queue.enqueue(db, "greetings", %{name: "world"})


{:ok, job} = Honker.Queue.claim_one(db, "greetings", "worker-1")
IO.puts("hello, #{job.payload["name"]}!")
Honker.Job.ack(db, job)
```

--------------------------------

### Open Honker with different watcher backends (JavaScript)

Source: https://honker.dev/reference/watcher-backends

Shows how to open a Honker database using the default, kernel, and shm watcher backends in JavaScript.

```javascript
const db = honker.open('app.db');
const dbK = honker.open('app.db', undefined, 'kernel');
const dbS = honker.open('app.db', undefined, 'shm');

```

--------------------------------

### Build Honker with Watcher Features

Source: https://honker.dev/reference/watcher-backends

Instructions for building Honker with kernel-watcher and shm-fast-path features using different package managers.

```bash
cd packages/honker
maturin develop --release --features kernel-watcher,shm-fast-path
```

```bash
cd packages/honker-node
CARGO_BUILD_FEATURES=kernel-watcher,shm-fast-path npm run build
```

--------------------------------

### Build Honker extension from source

Source: https://honker.dev/

Build the Honker extension Rust crate in release mode.

```bash
# Build from source — it's one crate
cargo build --release -p honker-extension
# → target/release/libhonker_ext.{dylib,so}
```

--------------------------------

### Run WAL Index Methods Benchmark

Source: https://honker.dev/reference/benchmarks

Compiles and runs the release build of the WAL index methods benchmark.

```bash
cd bench/wal_index_methods && cargo run --release
```

--------------------------------

### Open Database with Java Options

Source: https://honker.dev/languages/jvm

Opens a Honker database with custom watcher options, such as MMAP_SHM backend. Ensure to close the database connection using try-with-resources.

```java
import dev.honker.Honker;
import dev.honker.OpenOptions;
import dev.honker.WatcherBackend;
import dev.honker.WatcherOptions;


var options = OpenOptions.builder()
    .watcherOptions(WatcherOptions.builder()
        .backend(WatcherBackend.MMAP_SHM)
        .build())
    .build();


try (var db = Honker.open("app.db", options)) {
    // use db
}
```

--------------------------------

### Open Honker Database with Options

Source: https://honker.dev/languages/rust

Open a Honker database using `OpenOptions` to specify configurations like the watcher backend.

```rust
use honker::{Database, OpenOptions};


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

```

--------------------------------

### Build Honker for C++

Source: https://honker.dev/getting-started

Clone the C++ Honker repository and build using Zig. Requires Zig 0.16+, C++17 compiler, and SQLite 3.9+ with extension loading.

```bash
git clone https://github.com/russellromney/honker-cpp.git
cd honker-cpp
zig build
```

--------------------------------

### Initialize Honker watchers with different backends (Rust)

Source: https://honker.dev/reference/watcher-backends

Illustrates initializing Honker's SharedUpdateWatcher with polling, kernel, and shm backends using Rust. The kernel and shm backends require specific Cargo features.

```rust
use honker_core::{SharedUpdateWatcher, WatcherBackend, WatcherConfig};


let polling = SharedUpdateWatcher::new(db_path.clone());
let kernel = SharedUpdateWatcher::new_with_config(
    db_path.clone(),
    WatcherConfig { backend: WatcherBackend::KernelWatch },
);
let shm = SharedUpdateWatcher::new_with_config(
    db_path,
    WatcherConfig { backend: WatcherBackend::ShmFastPath },
);

```

--------------------------------

### Run Stream Benchmark

Source: https://honker.dev/reference/benchmarks

Executes the stream benchmark suite with 5000 iterations.

```bash
uv run python bench/stream_bench.py --n 5000
```

--------------------------------

### Loading Honker Extension

Source: https://honker.dev/reference/extension

Loads the Honker extension and initializes the database by calling `honker_bootstrap()`. This function is idempotent and should be called once per database.

```APIDOC
## Loading

```sql
.load ./libhonker_ext
SELECT honker_bootstrap();
```

`honker_bootstrap()` is idempotent and creates every `_honker_*` table if not already present. Call it once per database.
```

--------------------------------

### Enqueue and Claim Jobs (C++)

Source: https://honker.dev/languages/cpp

Demonstrates enqueuing a job to a Honker queue and claiming a job for processing. Jobs are acknowledged after successful completion.

```cpp
auto q = db.queue("emails");
q.enqueue(R"({\"to\":\"alice@example.com\"})");


auto job = q.claim_one("worker-1");
if (job) {
  job->ack();
}

```

--------------------------------

### Listen for Notifications in Go

Source: https://honker.dev/guides/pubsub

Subscribe to a channel and process notifications from the returned channel. Remember to close the subscription when done.

```go
sub, _ := db.Listen("orders")
defer sub.Close()


for notif := range sub.Channel() {
    fmt.Println(notif.Channel, string(notif.Payload))
}
```

--------------------------------

### Atomic Enqueue in Go

Source: https://honker.dev/getting-started

Shows how to perform atomic enqueues in Go, integrating business logic writes with message queuing within a single transaction.

```go
tx, _ := db.Begin()
tx.Exec(
    "INSERT INTO orders (id, total, customer_id) VALUES (?, ?, ?)",
    42, 9900, "alice",
)
q.EnqueueTx(tx, map[string]any{
    "order_id":   42,
    "email_type": "confirmation",
}, honker.EnqueueOptions{})
tx.Commit()
```

--------------------------------

### Open Database with Kotlin DSL

Source: https://honker.dev/languages/jvm

Opens a Honker database using Kotlin's builder DSL for concise configuration, including watcher options. The connection is managed with Kotlin's `use` function.

```kotlin
import dev.honker.WatcherBackend
import dev.honker.kotlin.honker
import dev.honker.kotlin.openOptions
import dev.honker.kotlin.watcherOptions


honker("app.db", openOptions {
    watcherOptions(watcherOptions {
        backend(WatcherBackend.MMAP_SHM)
    })
}).use { db ->
    // use db
}
```

--------------------------------

### Open a Honker Database

Source: https://honker.dev/languages/python

Open a Honker database file. Choose a watcher backend based on your needs: 'polling' for stability, 'kernel' for filesystem hints, or 'shm' for fast SQLite WAL-index.

```python
import honker

db = honker.open("app.db", watcher_backend="shm")
```

--------------------------------

### Transactional Honker Usage with database/sql

Source: https://honker.dev/guides/orm/go

Demonstrates using the Honker wrapper with a database transaction (*sql.Tx) for enqueuing jobs and sending notifications.

```go
import "yourapp/honker"


var emails = &honker.Queue{Name: "emails"}


tx, _ := db.Begin()
tx.Exec("INSERT INTO orders (user_id) VALUES (?)", 42)
emails.Enqueue(tx, map[string]any{"to": "alice@example.com"}, honker.EnqueueOpts{})
honker.Notify(tx, "orders", map[string]any{"id": 42})
tx.Commit()
```

--------------------------------

### Enqueue and Process Jobs in Kotlin

Source: https://honker.dev/

Demonstrates transactional enqueuing of an email job and subsequent processing using Honker in Kotlin. Ensure the Honker library is imported.

```kotlin
import dev.honker.kotlin.honker


honker("app.db").use { db ->
    val q = db.queue("emails")


    db.transactionVoid { tx ->
        tx.execute("INSERT INTO orders (id, total) VALUES (?, ?)", listOf(42, 99))
        q.enqueue(tx, "{\"to\":\"alice@example.com\",\"order_id\":42}")
    }


    val job = q.claimOne("worker-1").orElseThrow()
    sendEmail(job.payloadJson())
    job.ack()
}
```

--------------------------------

### Configure exqlite for Honker Extension

Source: https://honker.dev/guides/orm/elixir

Add Honker's extension path to your Ecto Repo configuration in `config/config.exs`. This allows `exqlite` to load the Honker native extension.

```elixir
config :my_app, MyApp.Repo,
  database: "app.db",
  load_extensions: ["/path/to/libhonker_ext"]

```

--------------------------------

### Run Honker Benchmark

Source: https://honker.dev/reference/benchmarks

Executes the Honker benchmark suite with 5000 iterations.

```bash
uv run python bench/honker_bench.py --n 5000
```

--------------------------------

### Claim and Process Jobs in a Loop (Go)

Source: https://honker.dev/guides/queues

Continuously claim one job at a time in a loop. Process the job, acknowledging success or retrying on failure. Includes a small sleep if no job is found.

```go
for {
    job, err := q.ClaimOne("worker-1")
    if err != nil { log.Fatal(err) }
    if job == nil {
        time.Sleep(100 * time.Millisecond)
        continue
    }
    var payload map[string]any
    json.Unmarshal(job.Payload, &payload)
    if err := sendEmail(payload); err != nil {
        job.Retry(60, err.Error())
    } else {
        job.Ack()
    }
}
```

--------------------------------

### Open Honker Database Connection in Bun

Source: https://honker.dev/languages/bun

Import and use the `open` function from `@russellthehippo/honker-bun` to establish a connection to your SQLite database. Ensure the Honker extension library (`libhonker_ext.{so,dylib,dll}`) is accessible by providing its path or placing it alongside your application. The `watcherBackend` option can be configured for specific performance characteristics.

```javascript
import { open } from "@russellthehippo/honker-bun";


const db = open("app.db", "./libhonker_ext.dylib", { watcherBackend: "shm" });
```

--------------------------------

### Enqueue and Process Jobs in C++

Source: https://honker.dev/

Shows how to use Honker in C++ for enqueuing jobs within a transaction and processing them. Requires linking against the Honker C++ library.

```cpp
#include "honker.hpp"


int main() {
    honker::Database db{"app.db", "./libhonker_ext.dylib"};
    auto q = db.queue("emails");


    {
        honker::Transaction tx{db.raw()};
        sqlite3_exec(
            tx.raw(),
            "INSERT INTO orders (id, total) VALUES (42, 99)",
            nullptr, nullptr, nullptr
        );
        q.enqueue_tx(tx, R"({"to":"alice","order_id":42})");
        tx.commit();
    }


    auto job = q.claim_one("worker-1");
    if (job) {
        send_email(job->payload());
        job->ack();
    }
}
```

--------------------------------

### Enable Experimental Watcher Backends

Source: https://honker.dev/languages/rust

Configure Honker with experimental features like kernel-watcher and shm-fast-path in your Cargo.toml.

```rust
honker = { version = "0.3", features = ["kernel-watcher", "shm-fast-path"] }

```

--------------------------------

### Enqueue and Claim Job in Java

Source: https://honker.dev/languages/jvm

Demonstrates enqueuing a JSON payload to a queue and claiming a single job for processing. The database connection and job claims are managed within a try-with-resources block.

```java
try (var db = Honker.open("app.db")) {
    var q = db.queue("emails");
    q.enqueue("{\"to\":\"alice@example.com\",\"order_id\":42}");


    var job = q.claimOne("worker-1").orElseThrow();
    sendEmail(job.payloadJson());
    job.ack();
}
```

--------------------------------

### Manual Offset Save (Go)

Source: https://honker.dev/guides/streams

A Go implementation for reading events in batches and manually saving the consumer's offset. It includes a delay if no events are immediately available.

```go
for {
    batch, _ := s.ReadFromConsumer("email-worker", 100)
    if len(batch) == 0 {
        time.Sleep(100 * time.Millisecond)
        continue
    }
    for _, event := range batch {
        sendOrderEmail(event.Payload)
    }
    s.SaveOffset("email-worker", batch[len(batch)-1].Offset)
}
```

--------------------------------

### Open a Honker Database

Source: https://honker.dev/languages/node

Open a Honker database file. The third argument selects the watcher backend: `undefined` or `"polling"` for default, `"kernel"` for filesystem wake hints, or `"shm"` for WAL-index fast path.

```javascript
const honker = require("@russellthehippo/honker-node");


const db = honker.open("app.db", undefined, "shm");
```

--------------------------------

### Use Honker Package Directly

Source: https://honker.dev/guides/orm/dotnet

Use the native Honker package to open a database connection, access a queue, and enqueue items.

```csharp
using Honker;


using var db = Database.Open("app.db");
var emails = db.Queue("emails");


emails.Enqueue(new { to = "alice@example.com" });

```

--------------------------------

### Register Tasks with SQL

Source: https://honker.dev/guides/scheduler

Register periodic tasks directly using SQL commands. Use `honker_scheduler_register` for tasks and `honker_scheduler_tick` to process them.

```sql
.load ./libhonker_ext
SELECT honker_bootstrap();

-- Register a recurring task. `cron_expr` can be 5-field cron,
-- 6-field cron, or `@every <n><unit>`.
SELECT honker_scheduler_register(
  'nightly-backup', 'backups', '0 3 * * *',
  '{"target":"s3"}', 0, 3600
);

SELECT honker_scheduler_register(
  'heartbeat', 'health', '@every 1s',
  '{"ok":true}', 0, NULL
);

SELECT honker_scheduler_tick(unixepoch());
```

--------------------------------

### Open Database Connection

Source: https://honker.dev/languages/dotnet

Open a database connection using Honker. Specify the database file path, extension path, and watcher backend. Ensure the extension library is accessible.

```csharp
using Honker;


using var db = Database.Open("app.db", new OpenOptions
{
    ExtensionPath = "./libhonker_ext.dylib",
    WatcherBackend = "shm",
});

```

--------------------------------

### Bootstrap Honker Extension in Rails

Source: https://honker.dev/guides/orm/ruby

Run the `honker_bootstrap()` SQL function once to initialize the Honker extension. This should be done from an initializer or migration after the database connection is established.

```ruby
Rails.application.config.after_initialize do
  ActiveRecord::Base.connection.execute("SELECT honker_bootstrap()")
end

```

--------------------------------

### Open Honker Database

Source: https://honker.dev/languages/elixir

Open a Honker database file with specified extension path and watcher backend.

```elixir
{:ok, db} =
  Honker.open("app.db",
    extension_path: "./libhonker_ext.so",
    watcher_backend: "shm"
  )

```

--------------------------------

### Enable SQLite Extension Loading

Source: https://honker.dev/guides/orm/jvm

Configure SQLite JDBC to enable extension loading before opening the connection. This is necessary for using Honker's SQL functions.

```java
import org.sqlite.SQLiteConfig;


var config = new SQLiteConfig();
config.enableLoadExtension(true);


var props = config.toProperties();
try (var conn = java.sql.DriverManager.getConnection("jdbc:sqlite:app.db", props);
     var stmt = conn.createStatement()) {
    stmt.execute("SELECT load_extension('/absolute/path/to/libhonker_ext.dylib')");
    stmt.execute("SELECT honker_bootstrap()");
}
```

--------------------------------

### Atomic Enqueue in Bun

Source: https://honker.dev/getting-started

Demonstrates atomic enqueue in Bun.js, ensuring that database writes and message enqueues are transactional.

```javascript
const tx = db.transaction();
tx.execute(
  "INSERT INTO orders (id, total, customer_id) VALUES (?, ?, ?)",
  [42, 9900, "alice"],
);
q.enqueue({ order_id: 42, email_type: "confirmation" }, { tx });
tx.commit();
```

--------------------------------

### Listen for Notifications in Node.js

Source: https://honker.dev/guides/pubsub

Utilize a for await...of loop to process incoming notifications asynchronously. Ensure the database connection is properly managed.

```javascript
for await (const notif of db.listen('orders')) {
  console.log(notif.channel, notif.payload);
}
```

--------------------------------

### Integrate Honker with Framework-Owned sqlite3*

Source: https://honker.dev/guides/orm/cpp

Use Honker as a helper with an existing `sqlite3*` connection. This involves manually managing transactions and using `sqlite3_prepare_v2` for enqueuing.

```c
sqlite3_exec(db.raw(), "BEGIN IMMEDIATE", nullptr, nullptr, nullptr);
sqlite3_exec(
    db.raw(),
    "INSERT INTO orders (id, total, customer_id) VALUES (42, 9900, 'alice')",
    nullptr, nullptr, nullptr
);


sqlite3_stmt* stmt = nullptr;
sqlite3_prepare_v2(
    db.raw(),
    "SELECT honker_enqueue('emails', ?, NULL, NULL, 0, 3, NULL)",
    -1,
    &stmt,
    nullptr
);
sqlite3_bind_text(stmt, 1, R"({\"order_id\":42})", -1, SQLITE_TRANSIENT);
sqlite3_step(stmt);
sqlite3_finalize(stmt);


sqlite3_exec(db.raw(), "COMMIT", nullptr, nullptr, nullptr);
```

--------------------------------

### Load Honker Extension with better-sqlite3

Source: https://honker.dev/guides/orm/javascript

Load the `libhonker_ext` extension on a SQLite handle using `db.loadExtension()`. This is the initial step for integrating Honker with better-sqlite3 or bun:sqlite.

```javascript
const Database = require('better-sqlite3');
// or: import { Database } from 'bun:sqlite';


const db = new Database('app.db');
db.loadExtension('/path/to/libhonker_ext');
db.prepare('SELECT honker_bootstrap()').run();

```

--------------------------------

### Wire honker extension with sqlx in Rust

Source: https://honker.dev/guides/orm/rust

When retrofitting into an existing sqlx-based codebase, load the SQLite extension using `SqliteConnectOptions::extension` and execute `honker_bootstrap()` to initialize it.

```rust
use sqlx::sqlite::SqliteConnectOptions;
use sqlx::{ConnectOptions, Executor};
use std::str::FromStr;


let opts = SqliteConnectOptions::from_str("sqlite:///app.db")?
    .extension("/path/to/libhonker_ext");


let mut conn = opts.connect().await?;
conn.execute("SELECT honker_bootstrap()").await?;
```

--------------------------------

### Load Honker Extension in Django

Source: https://honker.dev/guides/orm/python

Configure Django's DATABASES setting and use a receiver to load the Honker extension when a SQLite connection is created. Ensure the extension path is correct.

```python
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "app.db",
    },
}


# apps.py (or any module imported at startup)
from django.db.backends.signals import connection_created
from django.dispatch import receiver




@receiver(connection_created)
def _load_honker(sender, connection, **kwargs):
    if connection.vendor != "sqlite":
        return
    raw = connection.connection  # underlying sqlite3.Connection
    raw.enable_load_extension(True)
    raw.load_extension("/path/to/libhonker_ext")
    raw.execute("SELECT honker_bootstrap()")

```

--------------------------------

### Fire a Signal using SQL Extension

Source: https://honker.dev/guides/pubsub

Fire a notification directly using SQL commands after loading the Honker extension. This method mimics Postgres's pg_notify signature.

```sql
.load ./libhonker_ext
SELECT honker_bootstrap();


-- Matches pg_notify's signature for drop-in familiarity.
SELECT notify('orders', '{"id":42,"event":"placed"}');
```

--------------------------------

### Load Honker Extension for SQLAlchemy/SQLModel

Source: https://honker.dev/guides/orm/python

This snippet shows how to load the Honker extension when using SQLAlchemy or SQLModel. It attaches to the engine's connect event to enable and load the extension, then runs the bootstrap function.

```python
from sqlalchemy import create_engine, event
from sqlalchemy.orm import Session


engine = create_engine("sqlite:///app.db")


@event.listens_for(engine, "connect")
def _load_honker(conn, _):
    conn.enable_load_extension(True)
    conn.load_extension("/path/to/libhonker_ext")
    conn.execute("SELECT honker_bootstrap()")

```

--------------------------------

### Publish to a Stream (Bun)

Source: https://honker.dev/guides/streams

Publish an event to a stream using the Bun runtime. The event data is provided as a JavaScript object.

```javascript
import { open } from "@russellthehippo/honker-bun";


const db = open("app.db", "./libhonker_ext.dylib");
const s = db.stream("orders");


s.publish({ id: 42, amount: 9900 });
```

--------------------------------

### Listen for Notifications in Ruby

Source: https://honker.dev/guides/pubsub

Use a block to handle incoming notifications. Each notification object contains channel and payload information.

```ruby
db.listen("orders") do |notif|
  puts "#{notif.channel} #{notif.payload}"
end
```

--------------------------------

### Claim and Process Jobs in a Loop (Bun)

Source: https://honker.dev/guides/queues

Continuously claim jobs in a loop using Bun. Acknowledge successful jobs or retry failed ones with a specified delay and error. Includes a sleep if no job is found.

```javascript
while (running) {
  const job = q.claimOne("worker-1");
  if (!job) { await Bun.sleep(100); continue; }
  try {
    await sendEmail(job.payload as { to: string });
    job.ack();
  } catch (e) {
    job.retry(60, String(e));
  }
}
```

--------------------------------

### Atomic Enqueue using SQL

Source: https://honker.dev/getting-started

Demonstrates atomic enqueue operations directly in SQL, ensuring that database inserts and message enqueues are handled within a single transaction.

```sql
.load ./libhonker_ext
SELECT honker_bootstrap();


BEGIN;
INSERT INTO orders (id, total, customer_id) VALUES (42, 9900, 'alice');
SELECT honker_enqueue(
  'emails',
  '{"order_id":42,"email_type":"confirmation"}',
  NULL, NULL, 0, 3, NULL
);
COMMIT;
```

--------------------------------

### Atomic Enqueue in Kotlin

Source: https://honker.dev/getting-started

Shows how to perform atomic enqueues in Kotlin, integrating business logic writes with message queuing within a single transaction.

```kotlin
db.transactionVoid { tx ->
    tx.execute(
        "INSERT INTO orders (id, total, customer_id) VALUES (?, ?, ?)",
        listOf(42, 9900, "alice"),
    )
    q.enqueue(tx, """{"order_id":42,"email_type":"confirmation"}""")
}
```

--------------------------------

### Publish to a Stream (SQL)

Source: https://honker.dev/guides/streams

Publish an event to a stream using SQL commands. The `honker_stream_publish` function handles event publishing.

```sql
.load ./libhonker_ext
SELECT honker_bootstrap();


-- Returns the assigned offset (monotonic within a topic).
SELECT honker_stream_publish('orders', NULL, '{"id":42,"amount":9900}');
```

--------------------------------

### Enqueue Jobs in C++

Source: https://honker.dev/guides/queues

Enqueue jobs with optional delay and priority. The second argument to `enqueue` can be the delay in seconds, and the third can be the priority. Ensure the honker extension library is correctly linked.

```cpp
#include "honker.hpp"


int main() {
    honker::Database db{"app.db", "./libhonker_ext.dylib"};
    auto q = db.queue("emails");


    q.enqueue(R"({"to":"alice@example.com"})");
    q.enqueue(R"({"to":"bob@example.com"})", 60);
    q.enqueue(R"({"to":"urgent@example.com"})", 0, 10);
}
```

--------------------------------

### Listen for Notifications in Python

Source: https://honker.dev/guides/pubsub

Use an async for loop to iterate over notifications from a specified channel. Historical notifications are not replayed.

```python
async for notif in db.listen("orders"):
    print(notif.channel, notif.payload)
```

--------------------------------

### Open Honker Database Connection

Source: https://honker.dev/languages/go

Opens a connection to a Honker database file, specifying the path to the extension library and watcher backend options. Handles potential errors and ensures the connection is closed.

```go
db, err := honker.OpenWithOptions("app.db", "./libhonker_ext.so", honker.OpenOptions{
    WatcherBackend: "shm",
})
if err != nil { log.Fatal(err) }
defer db.Close()

```

--------------------------------

### Queue and Claim Jobs

Source: https://honker.dev/languages/node

Queue items for processing and claim them for execution. Jobs are acknowledged after successful processing.

```javascript
const q = db.queue("emails");
q.enqueue({ to: "alice@example.com", orderId: 42 });


const job = q.claimOne("worker-1");
if (job) {
  await sendEmail(job.payload);
  job.ack();
}
```

--------------------------------

### Batch Claim and Ack Jobs (SQL)

Source: https://honker.dev/guides/queues

SQL functions to claim multiple jobs at once with a specified visibility timeout and to acknowledge multiple jobs by their IDs.

```sql
-- Claim up to 32 jobs with a 300-second visibility timeout.
-- Returns a JSON array: [{"id": ..., "queue": ..., "payload": ...,
--                         "worker_id": ..., "attempts": ...}, ...]
SELECT honker_claim_batch('emails', 'worker-1', 32, 300);


-- Ack multiple jobs (DELETEs if the claim is still valid).
SELECT honker_ack_batch('[1,2,3]', 'worker-1');
```

--------------------------------

### Directly Use C++ Binding to Enqueue Data

Source: https://honker.dev/guides/orm/cpp

Use the `honker-cpp` binding to establish a database connection and enqueue data into a specified queue. This is suitable for simple enqueue operations.

```cpp
#include "honker.hpp"


int main() {
    honker::Database db{"app.db", "./libhonker_ext.dylib"};
    auto emails = db.queue("emails");


    emails.enqueue(R"({\"to\":\"alice@example.com\"})");
}
```

--------------------------------

### Batch Claim and Acknowledge Jobs in SQL

Source: https://honker.dev/guides/queues

Utilize SQL functions to claim and acknowledge jobs in batches. This is useful for direct database interaction.

```sql
SELECT honker_claim_batch('emails', 'worker-1', 100, 300);
-- process each row in the returned JSON
SELECT honker_ack_batch('[1,2,...,100]', 'worker-1');
```
Tokens:
Raw