Append Only File (AOF)
Append Only File (AOF) captures every write operation received by the server. Upon server restart, these operations are replayed to reconstruct the original dataset.
Dragonfly v2.1.0 includes an experimental AOF. It is disabled by default and enabled with the --aof flag.
Snapshots remain the default persistence method: see Saving Backups and the snapshotting design.
Differences from Valkey AOF
Dragonfly's AOF works differently from Valkey AOF:
- Each shard writes its own log, in Dragonfly's binary format rather than the Redis protocol. Dragonfly cannot load Valkey or Redis AOF files, and their tools cannot read Dragonfly's logs. To move data from Valkey or Redis, use an RDB snapshot instead.
- AOF can only be enabled at startup, with
--aof. There is noappendonlyorappendfsyncsetting. - There is no fsync policy: written data is flushed to disk once per second.
- There is no rewrite or compaction.
BGREWRITEAOFandWAITAOFare unknown commands.
Enabling AOF
Start Dragonfly with --aof:
./dragonfly --aof --dir=/var/lib/dragonfly --proactor_threads=4
Without --dir, the files are written to the working directory.
A log is replayed with the shard count it was written with: --num_shards if set,
otherwise the number of threads. Set --proactor_threads explicitly instead of relying on the CPU count.
With Docker, Dragonfly also needs a seccomp profile that allows io_uring:
docker run -p 6379:6379 --ulimit memlock=-1 --security-opt seccomp=unconfined \
-v dragonfly-data:/data \
docker.dragonflydb.io/dragonflydb/dragonfly --aof --proactor_threads=4
The working directory of the image is /data, so the AOF files go to the dragonfly-data volume.
Docker's default seccomp profile blocks io_uring.
Without --security-opt seccomp=unconfined, Dragonfly switches to epoll and exits
(in this and the following log excerpts, timestamps, thread ids, offsets, sizes and LSNs vary):
W20261105 12:10:43.740739 6 dfly_main.cc:573] Check if io_uring is disabled via /proc/sys/kernel/io_uring_disabled. Switching to epoll.
E20261105 12:10:43.747426 6 server_family.cc:1076] --aof needs io_uring
Instead of unconfined, you can pass a custom seccomp profile:
Docker's default profile with the io_uring_setup, io_uring_enter and io_uring_register system calls added to the allowed ones.
Requirements
AOF runs only on Linux. Dragonfly checks the following at startup and exits with the error shown if a requirement is not met:
| Requirement | Startup error |
|---|---|
io_uring: Linux kernel 5.10 or newer, io_uring not disabled or blocked by seccomp, enough locked memory, no --force_epoll | --aof needs io_uring |
A local --dir: s3://, gs:// and Azure Blob paths are not supported | --aof needs a local --dir |
--hz greater than 0, because the heartbeat writes the log | --aof needs --hz > 0, the heartbeat seals AOF blocks |
Not a replica: no --replicaof | --aof is not supported on replicas |
At runtime, the AOF flags cannot be changed, and an instance started with --aof refuses to become a replica:
dragonfly> CONFIG SET aof true
(error) ERR Unknown option or number of arguments for CONFIG SET - 'aof'
dragonfly> CONFIG GET aof*
(empty array)
dragonfly> REPLICAOF 10.0.0.2 6379
(error) ERR REPLICAOF is not supported with --aof
Flags
--aof: If true, each shard logs its writes to an append-only file in--dir. Default:false.--aof_max_buffered_bytes: Per shard, the amount of logged data not yet written to disk above which the shard blocks until writes complete. Default:64MiB. Do not set it below8kb, the size of a log block.
Files in --dir
With two shards, --dir contains these files while Dragonfly runs:
appendonly-0-0.aof
appendonly-0-1.aof
appendonly-1-0.aof
appendonly-1-1.aof
appendonly.manifest
appendonly.manifestrecords the base snapshot, the shard count and where each shard's log starts. It is protected by a checksum. A damaged manifest stops startup withfailed to read the AOF manifest: invalid AOF manifest.appendonly-<shard>-<seq>.aofare the log segments of each shard. Every start continues the log in a new segment, and while Dragonfly runs, each shard keeps its next, still empty segment ready. A clean shutdown deletes the empty segment. After a crash, it stays.*.discardedfiles are segments that crash recovery set aside. Dragonfly never reads them.- The base snapshot, if one was adopted at the first start, stays where it is. Dragonfly never deletes it.
Startup
First Start
When --dir has no AOF manifest, Dragonfly starts a new log:
- If
--dirhas a snapshot that matches--dbfilename(for the defaultdump-{timestamp}, the newest one), Dragonfly loads it and uses the file in place as the base of the log. Without a snapshot, the log starts from an empty dataset. - The base must be in Dragonfly format. An RDB file stops startup with
--aof adopts only DFS dumps for now, found /data/dump.rdb. To start from an RDB file, start Dragonfly once without--aofso that it loads the file, runSAVE DF, and stop it withSHUTDOWN NOSAVE, so that the newest snapshot is the one in Dragonfly format. Then start it with--aof. If an earlier start with--aofstopped at the RDB file, this start logsRedoing an interrupted AOF bootstrap, which is expected. - If
--dircontains AOF segments but no manifest, Dragonfly does not start:AOF files in /data but no manifest, e.g. /data/appendonly-0-0.aof.
Later Starts
On later starts, Dragonfly does not look for snapshots by --dbfilename. Instead, it:
- Loads the base named in the manifest. If the file is gone, startup stops with
the AOF base /data/dump-summary.dfs is missing. - Replays each shard's log on top of the base, all shards in parallel.
- Continues each shard's log in a new segment.
Startup blocks until the base is loaded and the log is replayed. Configure startup and liveness probes to allow for the replay time. Because v2.1.0 has no compaction, every start replays the entire log since the base, and the replay takes longer as the log grows.
Durability
Replies do not wait for the disk:
- Each shard collects its log records in blocks of up to 8 KB and writes a block when it is full or at the next heartbeat:
every 10 ms with the default
--hzof100(every1000 / hzmilliseconds). - Once per second, each shard flushes what it has written with
fdatasync.
A crash of the Dragonfly process loses the records that have not reached the file yet:
up to one heartbeat interval of writes, plus any blocks still queued for the disk, which --aof_max_buffered_bytes limits per shard.
A crash of the machine or a power loss can also lose about the last second of written data.
A clean shutdown, with SIGTERM or SHUTDOWN, writes and syncs every logged record before Dragonfly exits.
Crash Recovery
After a crash, the end of a shard's log can be missing or damaged. At startup, Dragonfly replays each shard's log up to its last valid block, cuts off the rest, and logs:
W20261105 12:13:05.864750 11 aof_chain_reader.cc:247] AOF shard 0: damaged tail of 300 bytes after lsn 2
W20261105 12:13:05.864760 11 execution_state.cc:93] ReportError: AOF log ends with a damaged tail
Damage is never skipped: everything after the first damaged block of a shard is dropped, and the later segments of that shard are renamed to *.discarded.
Snapshots and AOF
In v2.1.0, snapshots do not shorten the log.
SAVE, BGSAVE
and --snapshot_cron write regular snapshots, and the manifest keeps the base from the first start.
- With
--aof, Dragonfly writes no snapshot on shutdown, not even withSHUTDOWN SAVE. - Keep a
{timestamp}in--dbfilename, as in the defaultdump-{timestamp}, so that every save writes new files and the base snapshot of the log stays unchanged. - Do not delete or move the base snapshot. Its file name is in
appendonly.manifest.
Starting a New AOF from a Snapshot
There is no log compaction in v2.1.0: segments are never deleted, and every start adds one per shard. To shrink the log or change the shard count, start a new AOF from a snapshot:
- Stop the clients that write to Dragonfly. Writes made after the next step are lost.
- Run
SAVE DF. With a{timestamp}in--dbfilename, it writes a new snapshot in Dragonfly format. - Stop Dragonfly. With
--aof, it writes no other snapshot on shutdown. - Move
appendonly.manifestand everyappendonly-*file out of--dir. - Start Dragonfly with
--aof, and with a new--proactor_threadsvalue if you change the shard count. The newest snapshot that matches--dbfilenamebecomes the base of a new, empty log.
Monitoring
INFO has no AOF fields, and Dragonfly exports no AOF metrics. AOF messages appear in the server log.
If you have any thoughts or suggestions about AOF, we encourage you to join the conversation on our Slack community.