mqlite

# what it solves

Three problems that keep re-appearing in every backend.

# why mqlite

Design priorities, in order — when they conflict, the earlier one wins.

# the killer feature: a transactional outbox with no outbox

package main

import (
    "context"
    "log"

    "github.com/mqlitehq/mqlite"
    "github.com/mqlitehq/mqlite/engine"
)

func main() {
    ctx := context.Background()
    mq, _ := mqlite.OpenEmbedded(ctx, "file:./app.db")
    defer mq.Close()
    _ = mq.CreateQueue(ctx, "order-events", mqlite.QueueConfig{})

    err := mq.Tx(ctx, func(tx *engine.EngineTx) error {
        // 1) the business write, on the SAME transaction. Use tx.Context(), not the
        //    ctx you passed to Tx — a statement interrupted mid-transaction wedges
        //    a local SQLite database.
        if _, err := tx.SQL().ExecContext(tx.Context(),
            `INSERT INTO orders(id, total) VALUES(?, ?)`,
            42, 1999); err != nil {
            return err // rollback: nothing enqueued
        }
        // 2) enqueue — commits atomically with it:
        _, err := tx.SendOne("order-events",
            engine.OutMessage{Body: []byte(`{"order":42}`)})
        return err
    })
    if err != nil {
        log.Fatal(err)
    }
    // Either both happened, or neither did.
}

# how it works

Two delivery targets, one storage story: a topic stores nothing — the thing that stores, is consumed, and can dead-letter is always a queue.

the source version described here is covered by the conformance TCK — details in Concepts; the full construction story (schema, locks, fencing, recovery) is in Internals

# the honest part

Published historical measurements from specific workloads; remeasure v0.3.3 with your payloads, concurrency and monitoring enabled before sizing production. Full method: docs/benchmark.md.

when NOT to use mqlite — it is a single-writer, single-node queue by design

# quickstart

Three ways in — they all drive the same engine. These examples pin v0.3.3; see Deployment for installation and runtime settings.

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/mqlitehq/mqlite"
)

func main() {
    ctx := context.Background()
    mq, err := mqlite.OpenEmbedded(ctx, "file:./mq.db")
    if err != nil {
        log.Fatal(err)
    }
    defer mq.Close()

    if err := mq.CreateQueue(ctx, "orders", mqlite.QueueConfig{
        LockDuration:     30 * time.Second,
        MaxDeliveryCount: 5,
    }); err != nil {
        log.Fatal(err)
    }

    // produce
    if _, err := mq.SendOne(ctx, "orders", mqlite.OutMessage{Body: []byte(`{"id":42}`)}); err != nil {
        log.Fatal(err)
    }

    // consume (Peek-Lock): receive, do work, then settle
    msgs, err := mq.Receive(ctx, "orders", mqlite.RecvOpts{Max: 10, Wait: 5 * time.Second})
    if err != nil {
        log.Fatal(err)
    }
    for _, m := range msgs {
        fmt.Printf("got: %s\n", m.Body)
        if err := m.Complete(ctx); err != nil { // or m.Abandon(ctx) to retry, m.Reject(ctx) -> DLQ
            log.Fatal(err)
        }
    }
}

go install github.com/mqlitehq/mqlite/cmd/mqlite@v0.3.3   # default port 6754

# start the broker on :6754 with a known token, in the background
MQLITE_TOKENS=mqk_dev MQLITE_DB=file:./mq.db mqlite serve &
export TOKEN=mqk_dev        # (omit MQLITE_TOKENS to have the broker generate + print one)

# create a queue, send, receive — curl-able by construction
curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     --data '{"name":"orders","config":{}}' \
     localhost:6754/mqlite.v1.AdminService/CreateQueue

curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     --data "{\"queue\":\"orders\",\"messages\":[{\"body\":\"$(printf hi | base64)\"}]}" \
     localhost:6754/mqlite.v1.QueueService/Send

curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     --data '{"queue":"orders","max_messages":1,"wait_time_ms":5000}' \
     localhost:6754/mqlite.v1.QueueService/Receive

docker run -d --name mqlite -p 127.0.0.1:6754:6754 \
  -e MQLITE_TOKENS=mqk_dev \
  -e MQLITE_DB=file:/data/mq.db \
  -v mqdata:/data \
  ghcr.io/mqlitehq/mqlite:0.3.3

curl http://localhost:6754/          # discovery card (no auth)
# then open the admin console in a browser: http://localhost:6754/ui

# one key for each application

Available since v0.3.1. Keep a configured administrator token and issue separate application keys at runtime, with no broker restart.

Permissions apply across one broker. Tokens are shown once; the database stores only their digests. Manage keys through the Go SDK, HTTP API, CLI, console or MCP.

Read the access key guide →

# run it in production

Start with one broker over a persistent local SQLite file. Choose a durability setting and rehearse recovery before putting messages into production.

Prometheus collection is off by default. Enable --metrics or MQLITE_METRICS=on to serve authenticated /metrics on the API port, and give the collector a separate MQLITE_MONITOR_TOKENS credential. Keep collection on a private network; if the API has public ingress, deny /metrics there. The starter includes Prometheus, Grafana, a dashboard and verification scenarios.

# built for AI agents too