An edge deployment often needs durable messaging without operating a broker, a stream platform, a cache, and a job queue as separate services. Sagüin is designed for the smaller boundary: one binary under 20 MB, one node, and one SQLite database holding all stored state.
It is not a clustered replacement for a distributed event platform. It is a practical option when one machine owns the workload and its limits are understood.
Why SQLite fits the edge
SQLite provides transactions and crash recovery in one local database file without a separate database server. That makes it attractive for gateways, industrial PCs, small ARM machines, and remote installations where operational simplicity matters as much as throughput.
With Sagüin, the one SQLite database holds:
- every channel's records,
$broadcastincluded, and the positions of durable consumers; latestvalues and their tombstones;- queue jobs, with their attempt counts and retry times, and dead letters;
- durable sessions, with their subscriptions, in-flight messages, held QoS 2 exchanges and Wills;
- retained values, as flags on
$broadcastrecords.
Every table, with its columns, keys and indexes, is documented. Queue holds and non-durable sessions stay in memory. The exact durability boundary depends on the storage mode. “Uses SQLite” is not itself a complete durability claim.
Where one node is the right trade-off
A single-node broker can be a good fit when:
- the broker runs beside the equipment producing the data;
- upstream connectivity is intermittent;
- thousands of connections are enough and millions are not required;
- local recovery matters more than automatic failover;
- an operator can monitor one process and one storage device;
- data can later be forwarded to a central system.
The same design is a poor fit when the service requires transparent node failure, consensus, multi-region availability, or horizontal write scaling. Sagüin deliberately provides no clustering or automatic failover.
Three storage modes fail differently
The store runs in one of three modes, and a reply confirming a change always waits for that change's commit:
full, the default, syncs every commit. Everything acknowledged survives a crash or a power cut.normalsyncs everysync_interval, 1 second by default. A crash of the broker loses nothing acknowledged; a power cut or an operating-system crash loses at most the commits since the last completed sync.memoryruns from a RAM copy of the database inmemory_dir, which must be a tmpfs, and snapshots it tofile_patheverysnapshot_interval, 30 minutes by default, and at a graceful stop. A crash of the broker or a power cut returns to the last snapshot. It is refused on macOS.
Use full unless the disk is slow, such as an SD card. There, normal or memory write to it far less often, if losing recent data is acceptable. Operators should choose based on the failure they need to survive.
Keep the deployment bounded
Small systems become reliable by making limits explicit. Every resource the broker holds has a limit, set by configuration or by the disk. Plan and monitor:
- each channel's retention, by age and size, and an
appendchannel'smax_bytes; - the retained values' own limit,
retained.max_bytes; - session expiry, capped by
limits.max_session_expiry; - packet size and connection limits, such as
limits.max_packet_sizeandlimits.max_connections; - queue attempts and dead-letter growth;
- free disk space.
The store has no size limit of its own: state without a limit, such as a latest channel or sessions, is bounded by the disk, and the operator sizes the disk. On a full disk, a write is refused only when SQLite reports lack of space and the transaction did not commit; a publish is then refused with 0x97 instead of acknowledging a promise that storage did not keep. When the broker's own work falls behind delivery, it holds publishers back until it catches up.
A useful edge topology
A common shape is:
devices → local Sagüin broker → local consumers
│
└─ append history → upstream bridge when connected
Local subscribers continue to use MQTT. An append channel keeps bounded history while the uplink is unavailable. A bridge connects Sagüin to a peer broker as an ordinary MQTT 5 client of the peer; each of its outbound rules is a durable consumer with its own cursor, so when connectivity returns it resumes from its stored position. Latest channels hold current device state, while queue channels can coordinate local work.
Operate the storage as a database
Keep the database on reliable local storage. One store writer does every commit's work, so a fast single core matters most, and in full mode the drive comes before the CPU: prefer a drive with power-loss protection and steady latency after bursts. On Btrfs, turn copy-on-write off for the database's directory (chattr +C) before the database is created. Space that retention frees stays inside the database file and is reused, so the file grows to its busiest size: size the disk for the peak. A damaged database stops the broker rather than serving from it.
Read Store for the storage modes, the lock and a full disk, and the storage reference for every table and for tuning: machines, drives, settings and capacity. Operations covers health, metrics and the operations routes. The measurements, from an AMD Ryzen 7 260 with consumer NVMe to a Raspberry Pi 4 Model B with an SSD over USB, are single runs of one recipe on those machines, a concrete reference point rather than a capacity promise.