# mqlite > A message queue in a single SQLite file. Peek-Lock delivery, retries, dead-letter > queues, scheduling, duplicate detection, FIFO groups and topic fan-out — embedded > in a Go process or served as a tiny HTTP broker. Pure Go, no CGO. MIT licensed. Public documentation: https://mqlitehq.github.io/. Relative links below resolve against this website. NOTE ON VERSIONS: the latest release is v0.3.3 (default port 6754, schema token 5). This website tracks main, currently source v0.3.3. Runtime access keys and key-management tools require v0.3.1 or later. Unified Observe, configured monitor credentials and the monitoring starter require v0.3.2 or later. Installation commands below pin v0.3.3. Use the [v0.3.3 documentation](https://github.com/mqlitehq/mqlite/tree/v0.3.3/docs) for the versioned reference. Upgrading from v0.2.0 (port 8080, schema token 2) requires a new database; follow [upgrade and rollback](operations.html#upgrade-and-rollback). - One engine, two front-ends: `mqlite.OpenEmbedded` (in-process, one SQLite file) and `mqlite serve` (HTTP broker, default :6754, Bearer-token auth, secure by default — a token is auto-generated if none is set). - Storage: local SQLite (pure-Go driver) or remote Turso/libSQL. Remote buys durability + geo-replication (~45 ms per durable commit), not throughput. - Wire protocol: JSON over HTTP, one POST per operation, 27 routes in source v0.3.3 under /mqlite.v1.QueueService/*, /mqlite.v1.AdminService/* and /mqlite.v1.AuthService/*. Message bodies are base64 in JSON. GET / is an open discovery card listing every endpoint. - Delivery: Peek-Lock (receive → work → settle with a lock_token) or receive-and-delete. Exactly one settlement verb per outcome: Complete / Abandon / Reject / Defer. Locks renewable (Renew); a 1 s reaper returns expired locks to active or to DLQ at the delivery limit. Peek-Lock is at-least-once; handlers must be idempotent. - Lease boundary: new settlements and Renew require the current lock_token and locked_until_ms > now; equality is expired, even before the reaper runs. Renew before expiry. An unexpired exact-request receipt can replay an already committed settlement after its original deadline (same queue, sequence, token, verb and effect-changing arguments); it cannot authorize a new effect or revive a lease. - Receive-and-Delete removes the row before returning it and grants no lease: empty lock_token and zero locked_until_ms (omitted in JSON), including receive attempt replays. The SDK exposes a zero LockedUntil time. - Retries: delivery_count per message; at max_delivery_count on retry → dead-letter queue (state, not a separate queue). Redrive moves dead letters back; DLQ retention bounds age/count/bytes. - Ordering: standard (per-group_id FIFO, cross-group parallel), group_fifo (group_id required), strict_fifo (whole-queue serial). Order holds across crashes and lock expiry. Abandon with delay_ms > 0 parks the message in scheduled and keeps blocking its ordered group until due (strict_fifo: the whole queue). - Pub/sub: topics are implicit; Subscribe(topic, name, filter) creates a backing queue per subscription; filters are one expr boolean predicate, fail-closed. Queue, subscription and topic names are one disjoint namespace (conflicts 409). - Queue deletion (v0.3.3 and later): AdminService/DeleteQueue requires manage permission, an empty plain queue and its generation from ListQueues. Any retained message blocks deletion. Subscription queues and topics are not deleted by this operation. Preserve the original generation when retrying; see [DeleteQueue](api.html#deletequeue). - Maintenance diagnostics (v0.3.3 and later): Observe exposes bounded failure details and recovery status. Optional private diagnostic logs retain redacted details across restarts; cumulative error counts are not current health. - Scheduling: deliver at a time (Schedule). Cancel only removes never-delivered scheduled messages (delivery_count = 0), not delayed retries. Per-message TTL is capped by the queue default. Duplicate detection by message_id within a window. - Transactional outbox (embedded-only): business write + enqueue commit in ONE SQLite transaction via mq.Tx. - Ops: /ui embedded admin console, opt-in authenticated /metrics Prometheus (incl. per-RPC latency histograms), /healthz, CLI (24 commands, including the key subcommand group), MCP server (mqlite-mcp, 18 tools in source v0.3.3). The local production boundary is one broker per persistent SQLite file; backups and recovery must be rehearsed. Use TLS and Bearer authentication for network access. - Unified observation (v0.3.2 and later): AdminService/Observe, SDK, CLI observe, MCP observe, console and Prometheus share one metric contract. Track collection success and freshness independently of scrape availability; unavailable values are not zero. Process counters reset on restart. Use MQLITE_MONITOR_TOKENS for a separate read-only collector credential; it permits only Observe and /metrics, not payload access, consumption, administration or key issuance. Grafana queries Prometheus and does not need the MQLite token. Reuse the supplied dashboard and alert rules with an existing collector or the local monitoring starter. - Prometheus access (v0.3.2 and later): disabled by default (/metrics returns 404 and discovery omits metrics). Enable --metrics or MQLITE_METRICS=on to serve on the API port; discovery then includes "metrics":"/metrics". Administrator auth must stay enabled. Only configured monitor or administrator credentials and managed manage keys may scrape. Observe works independently of this switch. Keep the collector on a private network; block /metrics at any public API ingress. Authentication does not make a public route private. On Fly.io, reuse an external collector over the private network instead of adding a monitoring VM. - Access keys (v0.3.1 and later): configured MQLITE_TOKENS remain full administrators. Managed keys are persisted in the same DB and can be created, listed, expired and revoked at runtime using SDK/HTTP/CLI/console/MCP. send = send/schedule/cancel; listen = receive/settle/renew/peek/queue stats; manage includes both and administration/key issuance, including other managers. Rights cover the entire broker. Listen is consumption, not read-only auditing. Newly generated secrets are mqk_ + 64 lowercase hex; stored as SHA-256 digests, never plaintext. Preserve the public 32-lowercase-hex ID before creation. Secrets are returned once; a lost response must be reconciled by ID and revoked before replacing. Duplicate ID returns key_conflict, never an old secret. CLI: key create/list/revoke. MCP: create_key/list_keys/revoke_key. List pagination: next_after_id -> after_id; 100 default, 1000 maximum. 401 unauthenticated or 403 permission_denied is permanent: do not retry forever. Revocation affects later requests; already-authorized long polls may finish. Environment tokens cannot be listed/revoked through the managed-key API. - Limits: message body ≤ 1 MiB (configurable), request body ≤ 32 MiB, Receive ≤ 256 messages / 20 s long-poll. - NOT for: log streaming/replay (use Kafka/Redpanda/NATS JetStream), multi-node HA clusters (NATS/RabbitMQ), Postgres-native queueing (pgmq/River), or sustained six-figure msg/s on one node. Single-writer, single-node by design. ## Docs - [Concepts](concepts.html): the whole model — queues, topics, subscriptions, filters, and the full message lifecycle state machine. - [Internals](internals.html): schema, concurrency, fencing and recovery. - [HTTP API reference](api.html): every route, request, response, error code and limit. - [CLI reference](cli.html): the mqlite command-line client — broker, produce/consume/administer, embedded or against a broker. - [Access keys](access-keys.html): permissions, issuance, rotation, expiry and revocation. - [Operations](operations.html): production scope, backup, restore, upgrade and rollback. - [Deployment](deployment.html): installation, persistent storage, tokens and TLS. - [Observability](observability.html): canonical measurements, availability, credentials, dashboard and alerts. - [Cloud monitoring](observability-cloud.html): private authenticated collection on Fly.io, Alibaba Cloud, Azure and Kubernetes. - [For AI agents](agents.html): MCP server setup and a copy-paste system prompt for driving the raw HTTP API. - [Full docs bundle](llms-full.txt): concepts + internals + API + CLI + access keys + MCP + examples + operations + deployment + observability + cloud monitoring as one plain-markdown file. ## Source - [GitHub](https://github.com/mqlitehq/mqlite): code, issues, full docs/ tree (deployment, Turso, retention, observability, conformance TCK, benchmarks). - [Concepts source](https://github.com/mqlitehq/mqlite/blob/main/docs/concepts.md). - [Internals source](https://github.com/mqlitehq/mqlite/blob/main/docs/internals.md). - [HTTP API source](https://github.com/mqlitehq/mqlite/blob/main/docs/api-reference.md). - [CLI source](https://github.com/mqlitehq/mqlite/blob/main/docs/cli.md). - [Operations source](https://github.com/mqlitehq/mqlite/blob/main/docs/operations.md). - [Deployment source](https://github.com/mqlitehq/mqlite/blob/main/docs/deployment.md). - [Observability source](https://github.com/mqlitehq/mqlite/blob/main/docs/observability.md). - [Cloud monitoring source](https://github.com/mqlitehq/mqlite/blob/main/docs/observability-cloud.md). - [Access key source](https://github.com/mqlitehq/mqlite/blob/main/docs/access-keys.md). - [MCP source](https://github.com/mqlitehq/mqlite/blob/main/docs/mcp.md). - [Releases](https://github.com/mqlitehq/mqlite/releases): binaries for linux/macos/windows (amd64+arm64), each archive contains mqlite + mqlite-mcp. - Container image: `ghcr.io/mqlitehq/mqlite:0.3.3` (default port 6754). See [Deployment](deployment.html) for persistent storage, authentication and TLS. - Broker: `go install github.com/mqlitehq/mqlite/cmd/mqlite@v0.3.3`. - MCP server: `go install github.com/mqlitehq/mqlite/cmd/mqlite-mcp@v0.3.3`. - SDK: `go get github.com/mqlitehq/mqlite@v0.3.3` (Go ≥ 1.21).