Durability: what LeonsDB guarantees

Losing or corrupting data is the worst thing a database can do. This page states exactly what LeonsDB promises, and where the limits are.

Acknowledged writes are never lost

When the LeonsDB server answers “OK” to a write, the write has been written to disk and flushed with fsync. A crash, a kill -9 or a power cut after that point cannot lose it. Every write request is applied atomically: after a crash you see either all of its operations or none of them, never part of them.

The test suite proves this on every change in two ways:

• Simulated power loss. Many writers run at full speed while the power is “cut”: the disk is reduced to what was really synced, plus a random part of what was not (torn writes). After recovery, every acknowledged write must be present and every record must exactly match a state it really had.
• Killed process. A separate writer process is killed at a random moment, the data is checked, and the writer is restarted on the same data and killed again, several times in a row.

As a check on the tests themselves, turning off the fsync makes them fail immediately with lost writes.

The connector’s write buffer

To keep the Minecraft main thread fast, the connector collects changes to normal fields and sends them to LeonsDB about once per second (adjustable), as well as when a player leaves and when the server shuts down.

The trade-off: if the Minecraft server process crashes, changes made in the last moment before the crash that were not yet sent are lost. In practice that is at most about one second of stat changes. Minecraft’s own world saving has the same kind of window, which is usually much longer.

Changes that must never be lost, such as money, should be made with update(...) (and the field marked @Transactional). They skip the buffer and are confirmed by the server before they count.

A single server is not a backup

A LeonsDB server stores its data on one disk. If that disk fails, the data on it is gone. Until replication is available, use automatic backups (on the roadmap) or snapshot the data directory regularly, and keep copies on another machine.

Requirements for the guarantee

• The data directory must be on a local disk. Network filesystems (NFS, SMB) and some container volume drivers do not honour fsync reliably.
• Disks or RAID controllers with write caches must not lie about flushes (enterprise SSDs with power-loss protection, or the write cache disabled).