docs: clarify LevelDB compaction limitations and StorageMax scope (#11188)
set expectations for behaviors like https://github.com/ipfs/kubo/issues/11096 Co-authored-by: Guillaume Michel <guillaumemichel@users.noreply.github.com>
Marcin Rataj committed
Feb 10, 2026 at 23:23 UTC
9ca1dbb8945fa0a6c91c07a6f10db265e8b836c2
2 files changed
+31
-1
docs/config.md
+8
@@ -910,6 +910,14 @@ storage system.
910
A soft upper limit for the size of the ipfs repository's datastore. With `StorageGCWatermark`,
911
is used to calculate whether to trigger a gc run (only if `--enable-gc` flag is set).
912
913
+> [!NOTE]
914
+> This only controls when automatic GC of raw blocks is triggered. It is not a
915
+> hard limit on total disk usage. The metadata stored alongside blocks (pins,
916
+> MFS, provider system state, pubsub message ID tracking, and other internal
917
+> data) is not counted against this limit. Always include extra headroom to
918
+> account for metadata overhead. See [datastores.md](datastores.md) for details
919
+> on how different datastore backends handle disk space reclamation.
920
+
921
Default: `"10GB"`
922
923
Type: `string` (size)
docs/datastores.md
+23
-1
@@ -34,7 +34,9 @@ The shardFunc is prefixed with `/repo/flatfs/shard/v1` then followed by a descri
34
NOTE: flatfs must only be used as a block store (mounted at `/blocks`) as it only partially implements the datastore interface. You can mount flatfs for /blocks only using the mount datastore (described below).
35
36
## levelds
37
-Uses a leveldb database to store key-value pairs.
37
+
38
+Uses a [leveldb](https://github.com/syndtr/goleveldb) database to store key-value
39
+pairs via [go-ds-leveldb](https://github.com/ipfs/go-ds-leveldb).
40
41
```json
42
{
@@ -44,6 +46,26 @@ Uses a leveldb database to store key-value pairs.
46
}
47
```
48
49
+> [!NOTE]
50
+> LevelDB uses a log-structured merge-tree (LSM) storage engine. When keys are
51
+> deleted, the data is not removed immediately. Instead, a tombstone marker is
52
+> written, and the actual data is removed later by background compaction.
53
+>
54
+> LevelDB's compaction decides what to compact based on file counts (L0) and
55
+> total level size (L1+), without considering how many tombstones a file
56
+> contains. This means that after bulk deletions (such as pin removals or the
57
+> periodic provider keystore sync), disk space may not be reclaimed promptly.
58
+> The `datastore/` directory can grow significantly larger than the live data it
59
+> holds, especially on long-running nodes with many CIDs.
60
+>
61
+> Unlike flatfs (which deletes files immediately) or pebble (which has
62
+> tombstone-aware compaction), LevelDB has no way to prioritize reclaiming
63
+> space from deleted keys. Restarting the daemon may trigger some compaction,
64
+> but this is not guaranteed.
65
+>
66
+> If slow compaction is a problem, consider using the `pebbleds` datastore
67
+> instead (see below), which handles this workload more efficiently.
68
+
69
## pebbleds
70
71
Uses [pebble](https://github.com/cockroachdb/pebble) as a key-value store.