guide · iot & edge
Queue at the edge, drain to the center.
This page shows how to run bunqueue on an edge gateway: turn MQTT sensor messages into persisted jobs, keep them safe while the uplink is down, and forward them to a central server when it comes back.
bunqueue fits where a Redis + BullMQ stack does not: a single Bun process with one SQLite file, running on the gateway next to your sensors. No containers, no broker for the queue itself.
:::note[Runtime]
Everything on this page uses the Bun `bunqueue` package: embedded mode and `queue.forward()` are Bun-only. The polyglot [SDKs](/guide/sdks/) are not affected, they can still produce and consume on the central server the gateway forwards to.
:::
## Is it the right fit?
| Scenario | Fit |
| ---------------------------------------------------------- | ------------------------------------------------------------------ |
| Edge gateway (Raspberry Pi 4/5, Jetson, ARM64/x64 mini-PC) | Yes, embedded queue plus store-and-forward |
| Backend telemetry ingestion (absorb bursts, retry, DLQ) | Yes |
| Offline-first buffering over a flaky uplink | Yes, jobs persist to SQLite on the gateway |
| Replacing an MQTT broker | No, keep Mosquitto/EMQX and bridge into bunqueue |
| Running directly on microcontrollers (ESP32, 32-bit ARM) | No, Bun needs ARM64/x64; those devices publish MQTT to the gateway |
The pattern that works:
```
sensors ──MQTT──► broker (Mosquitto/EMQX) ──► bridge ──► bunqueue ──► Worker
(SQLite) │
▼
backend / TSDB / alerts
```
Devices keep speaking MQTT, their native protocol. A small bridge script subscribes to topics and turns each message into a job. From there you get what a broker alone does not give you: retries with backoff, a dead letter queue (DLQ, a parking lot for messages that failed all retries), priorities, delayed jobs, and a durable buffer when the uplink is down.
## The MQTT bridge
A full runnable version lives in [`examples/mqtt-bridge/`](https://github.com/egeominotti/bunqueue/tree/main/examples/mqtt-bridge). The core is this:
```typescript
import mqtt from 'mqtt';
import { Queue, Worker } from 'bunqueue/client';
// Embedded mode: the queue runs inside this process, no server needed,
// persisted to a SQLite file on the gateway.
const queue = new Queue('telemetry', {
embedded: true,
dataPath: './edge-queue.db',
});
const client = mqtt.connect('mqtt://localhost:1883');
client.on('connect', () => client.subscribe('sensors/#'));
client.on('message', (topic, payload) => {
void queue.add(
'reading',
{ topic, payload: JSON.parse(payload.toString()), receivedAt: Date.now() },
{ attempts: 5 }
);
});
// Process locally, or POST to your backend
const worker = new Worker(
'telemetry',
async (job) => {
// write to TSDB, trigger alerts, forward...
return { processed: true };
},
{ embedded: true, dataPath: './edge-queue.db', concurrency: 10 }
);
```
Run it:
```bash
bun add mqtt
MQTT_URL=mqtt://localhost:1883 bun examples/mqtt-bridge/index.ts
# publish a test reading
mosquitto_pub -t sensors/temp/room1 -m '{"temp":21.5}'
```
## Forwarding to a central server
The recommended hybrid: the embedded queue on the gateway is the offline buffer, and `queue.forward()` drains it to a central bunqueue server whenever the uplink is healthy.
```typescript
const local = new Queue('telemetry', { embedded: true, dataPath: './edge.db' });
const forwarder = local.forward({
to: { host: 'queue.example.com', port: 6789, tls: true, token: Bun.env.BQ_TOKEN },
queue: 'telemetry-ingest', // optional remote queue name (default: same as local)
concurrency: 4, // parallel forwards (default: 4)
});
forwarder.on('forwarded', ({ id, remoteId }) => console.log(`${id} -> ${remoteId}`));
forwarder.on('error', (err) => console.error('uplink:', err.message));
// later: await forwarder.close();
```
Central server, with native TLS (encrypted connections without a reverse proxy):
```bash
bunqueue start \
--tls-cert /etc/bunqueue/cert.pem \
--tls-key /etc/bunqueue/key.pem \
--auth-tokens "$TOKEN" \
--data-path /var/lib/bunqueue/queue.db
```
What `forward()` guarantees:
- **An uplink outage does not discard locally persisted work.** If the remote
push fails, the job fails locally, retries with backoff, and after its attempts
lands in the local DLQ. When the uplink returns, `local.retryDlq()` re-enqueues
it. This assumes the gateway process or persistent volume survives; use
`durable: true` for local jobs that cannot tolerate SQLite's 10ms hard-crash
window.
- **Re-forwards deduplicate while ownership is retained.** Each forwarded job
carries a deterministic remote job id, `fwd: