Store artifacts on a filesystem

By default, DearDiary stores every Resource artifact inline in the database. That works for kilobyte-sized configs and small serialised models, but a 500 MB checkpoint will substantially increase the database file size and slow every metadata query. The DearDiary.FilesystemStore backend writes artifact bytes to a directory on local disk, keeping the database file smaller and allowing the bytes to be backed up along with the rest of the storage volume.

Configuration

Set two environment variables in the .env file:

DEARDIARY_ARTIFACT_BACKEND=filesystem
DEARDIARY_ARTIFACT_FS_ROOT=/var/lib/deardiary/artifacts

The root directory is created on the first write. No separate provisioning step is needed.

Layout on disk

Each artifact is written to <root>/<aa>/<uuid>, where <aa> is a two-character shard of the UUID so no single directory grows unbounded. Two uploads of identical bytes produce distinct files: there is no content-addressed deduplication, so deleting one Resource cannot break a sibling that uploaded the same payload.

End-to-end example

Create a project, experiment, and iteration, then upload an artifact through the configured store:

julia> project_id, _ = create_project("Filesystem tutorial");
julia> experiment_id, _ = create_experiment(project_id, DearDiary.IN_PROGRESS, "FS experiment");
julia> iteration_id, _ = create_iteration(experiment_id);
julia> payload = rand(UInt8, 4096);
julia> resource_id, _ = create_resource(experiment_id, "checkpoint.bin", payload);

The resource row records the new backend and the URI that points at the bytes on disk:

julia> resource = get_resource(resource_id)DearDiary.Resource
 ├ id = "60d19a68-4fb4-40b4-bb3c-76f7671ca7ec"
 ├ experiment_id = "6df49db5-1f67-425f-823f-3b5b73ce166c"
 ├ name = "checkpoint.bin"
 ├ description = ""
 ├ data = UInt8[]
 ├ created_date = 2026-08-25T20:37:37.829
 ├ updated_date = nothing
 ├ backend = "filesystem"
 ├ uri = "file:///tmp/jl_QBAHWX/28/28130349-e047-4785-85fe-dc9a096fc1d1"
 ├ size_bytes = 4096
 └ content_hash = "000260059f4ee744496ec287826a04acfcf29279a5a69685eaf31c71c4cb23f1"

julia> resource.backend"filesystem"

julia> resource.uri |> startswith("file://")true

The on-disk path is reachable directly for inspection or streaming from another process. DearDiary itself reads through read_resource_data:

julia> read_resource_data(resource_id) == payloadtrue