RocksDB upgrade to 9.5.0 release notes (#710)

Simran-B · nerpaula · web-flow · commit 3a78aec5d26f · 2025-10-22T14:21:53.000+02:00
* WIP: RocksDB upgrade to 9.5.0 release notes

* Throttling wasn't changed

* Apply to 3.13

* Clarify units

* Some RocksDB startup option defaults have been reverted

* Fix merge error

* Fix merge mistake

---------

Co-authored-by: Paula Mihu &lt;97217318+nerpaula@users.noreply.github.com&gt;
diff --git a/site/content/3.12/release-notes/version-3.12/incompatible-changes-in-3-12.md b/site/content/3.12/release-notes/version-3.12/incompatible-changes-in-3-12.md
@@ -900,6 +900,20 @@ the following steps.
 4. Restore the dump to the new deployment. You can directly move from any
    3.11 or 3.12 version to 3.12.4 (or later) this way.
 
+## RocksDB upgrade
+
+<small>Introduced in: v3.12.6</small>
+
+The RocksDB library has been upgraded from version 7.2.0 to 9.5.0.
+
+As part of this storage engine upgrade, the default values of the following
+RocksDB-related startup options have been changed:
+
+- `--rocksdb.pending-compactions-slowdown-trigger` has been changed from 128 KiB to 1 GiB.
+- `--rocksdb.pending-compactions-stop-trigger` has been changed from 16 GiB to 32 GiB.
+- `--rocksdb.partition-files-for-documents` has been changed from false to true.
+- `--rocksdb.throttle-slow-down-writes-trigger` has been obsoleted.
+
 ## Optional elevation for GeoJSON Points
 
 <small>Introduced in: v3.11.14-2, v3.12.6</small>
diff --git a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md
@@ -2243,6 +2243,40 @@ DB-Servers in a cluster has been added:
 |:------|:------------|
 | `arangodb_vocbase_transactions_lost_subordinates_total` | Counts the number of lost subordinate transactions on database servers. |
 
+### RocksDB upgrade
+
+<small>Introduced in: v3.12.6</small>
+
+The RocksDB library has been upgraded from version 7.2.0 to 9.5.0.
+
+As a result, you may see performance improvements while using slightly less
+resources especially for mixed workloads.
+
+The following new RocksDB functionality is exposed in ArangoDB:
+
+- Different types of block caches, LRU and HyperClockCache (HCC), selectable via
+  the new `--rocksdb.block-cache-type` startup option
+- A `--rocksdb.block-cache-estimated-entry-charge` startup option to configure the HCC.
+- RocksDB table format version 6 (not downwards-compatible to older versions of RocksDB).
+- RocksDB blob caching (if blobs are enabled for the documents column family),
+  which you can enable via `--rocksdb.enable-blob-cache`.
+- Using blob files only from a certain level onwards (if blobs are enabled for
+  the documents column family), which you can enable via
+  `--rocksdb.blob-file-starting-level`.
+- Blob cache prepopulation, which you can enable via `--rocksdb.prepopulate-blob-cache`.
+- An option to generate Bloom/Ribbon filters that minimize memory internal
+  fragmentation, which you can enable with `--rocksdb.optimize-filters-for-memory`.
+
+The following RocksDB metrics have been added:
+
+| Label | Description |
+|:------|:------------|
+| `rocksdb_block_cache_charge_per_entry` | Average size of entries in RocksDB block cache.
+| `rocksdb_block_cache_entries` | Number of entries in the RocksDB block cache.
+| `rocksdb_live_blob_file_garbage_size` | Size of garbage in live RocksDB .blob files.
+| `rocksdb_live_blob_file_size` | Size of live RocksDB .blob files.
+| `rocksdb_num_blob_files` | Number of live RocksDB .blob files.
+
 ### API call recording
 
 <small>Introduced in: v3.12.5</small>
diff --git a/site/content/3.13/release-notes/version-3.12/api-changes-in-3-12.md b/site/content/3.13/release-notes/version-3.12/api-changes-in-3-12.md
@@ -309,7 +309,6 @@ is for debugging purposes.
 See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-api-calls)
 for details.
 
-
 #### AQL query recording
 
 <small>Introduced in: v3.12.6</small>
diff --git a/site/content/3.13/release-notes/version-3.12/incompatible-changes-in-3-12.md b/site/content/3.13/release-notes/version-3.12/incompatible-changes-in-3-12.md
@@ -900,6 +900,20 @@ the following steps.
 4. Restore the dump to the new deployment. You can directly move from any
    3.11 or 3.12 version to 3.12.4 (or later) this way.
 
+## RocksDB upgrade
+
+<small>Introduced in: v3.12.6</small>
+
+The RocksDB library has been upgraded from version 7.2.0 to 9.5.0.
+
+As part of this storage engine upgrade, the default values of the following
+RocksDB-related startup options have been changed:
+
+- `--rocksdb.pending-compactions-slowdown-trigger` has been changed from 128 KiB to 1 GiB.
+- `--rocksdb.pending-compactions-stop-trigger` has been changed from 16 GiB to 32 GiB.
+- `--rocksdb.partition-files-for-documents` has been changed from false to true.
+- `--rocksdb.throttle-slow-down-writes-trigger` has been obsoleted.
+
 ## Optional elevation for GeoJSON Points
 
 <small>Introduced in: v3.11.14-2, v3.12.6</small>
diff --git a/site/content/3.13/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/3.13/release-notes/version-3.12/whats-new-in-3-12.md
@@ -2243,6 +2243,40 @@ DB-Servers in a cluster has been added:
 |:------|:------------|
 | `arangodb_vocbase_transactions_lost_subordinates_total` | Counts the number of lost subordinate transactions on database servers. |
 
+### RocksDB upgrade
+
+<small>Introduced in: v3.12.6</small>
+
+The RocksDB library has been upgraded from version 7.2.0 to 9.5.0.
+
+As a result, you may see performance improvements while using slightly less
+resources especially for mixed workloads.
+
+The following new RocksDB functionality is exposed in ArangoDB:
+
+- Different types of block caches, LRU and HyperClockCache (HCC), selectable via
+  the new `--rocksdb.block-cache-type` startup option
+- A `--rocksdb.block-cache-estimated-entry-charge` startup option to configure the HCC.
+- RocksDB table format version 6 (not downwards-compatible to older versions of RocksDB).
+- RocksDB blob caching (if blobs are enabled for the documents column family),
+  which you can enable via `--rocksdb.enable-blob-cache`.
+- Using blob files only from a certain level onwards (if blobs are enabled for
+  the documents column family), which you can enable via
+  `--rocksdb.blob-file-starting-level`.
+- Blob cache prepopulation, which you can enable via `--rocksdb.prepopulate-blob-cache`.
+- An option to generate Bloom/Ribbon filters that minimize memory internal
+  fragmentation, which you can enable with `--rocksdb.optimize-filters-for-memory`.
+
+The following RocksDB metrics have been added:
+
+| Label | Description |
+|:------|:------------|
+| `rocksdb_block_cache_charge_per_entry` | Average size of entries in RocksDB block cache.
+| `rocksdb_block_cache_entries` | Number of entries in the RocksDB block cache.
+| `rocksdb_live_blob_file_garbage_size` | Size of garbage in live RocksDB .blob files.
+| `rocksdb_live_blob_file_size` | Size of live RocksDB .blob files.
+| `rocksdb_num_blob_files` | Number of live RocksDB .blob files.
+
 ### API call recording
 
 <small>Introduced in: v3.12.5</small>
@@ -2275,7 +2309,6 @@ impact of this feature:
 See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-api-calls)
 for details.
 
-
 ### AQL query recording
 
 <small>Introduced in: v3.12.6</small>
