Storage Tiering

By the end of this page you will know which storage-tier levers in ScramDB actually move data or bytes today, and which parts of a hot/warm/cold picture are not available in the current build so you do not build around a feature that does not exist yet.

Hot: the buffer pool

The buffer pool is the real, working "how much of the database stays in fast memory" lever. It is covered in full on the Memory page, this section is a pointer, not a duplicate.

[storage]
buffer_pool_size_bytes = "8GB"
buffer_pool_percent = 60
buffer_pool_cap = "64GB"

Data inside the buffer pool is served from RAM. Data outside it falls back to a disk read. This is the tier that actually determines whether your working set feels fast, and it is the first thing to size correctly, see Memory for the full field reference and a verification recipe.

Warm: the OS page cache

There is a [storage.memory] effective_cache_bytes / effective_cache_percent field in the config, intended as a planner cost hint about how much data the OS page cache is likely to have warm, similar in spirit to PostgreSQL's effective_cache_size. Be aware: this field parses and stores a value, but it is not yet consumed by the query planner's cost model. Setting it does not change which plan ScramDB picks today.

The real "warm" tier is whatever your operating system's page cache keeps resident from recent disk reads, on its own, using its own eviction policy. ScramDB does not manage or control this layer directly, it is a side effect of the OS caching pages it has recently read from disk, and it disappears whenever the OS decides to evict a page for something else.

Off-box durability at object-storage cost: WAL archival

This is a genuine, working cost lever, but it is a durability and point-in-time-recovery feature, not a way to move table data to cheaper storage. Do not confuse it with "cold" table tiering below, they solve different problems.

[storage.wal]
[storage.wal.archive]
enabled = true
destination = "s3://my-bucket/scramdb-wal"
poll_interval = "5s"

Key	Default	What it controls
enabled	false in the library default config; true in the shipped Docker image's default config. These differ, check which one applies to your deployment.	Turns WAL segment archival on.
destination	unset	An object_store URL: file:///abs/path, s3://bucket/prefix, gs://bucket/prefix, or az://account/container/prefix. If enabled = true with no destination set, ScramDB derives a local file archive under {data_dir}/wal-archive so point-in-time recovery and branching work out of the box with no object store configured.
poll_interval	"5s"	How often the archiver checks for newly closed WAL segments once it is caught up. This does not throttle a backlog, consecutive already-closed segments ship back to back with no delay between them.

Once enabled, ScramDB ships each closed WAL segment to the configured destination. This is what backs point-in-time recovery and database branching without requiring you to keep every WAL segment on local disk indefinitely, off-box object storage is cheaper than growing local disk to hold the same history. See Backup for how archived WAL is used for recovery and branching.

Verifying it worked: check the WAL-archive counters on /metrics.

curl -s http://127.0.0.1:9090/metrics | grep scramdb_wal_archive

Expected: scramdb_wal_archive_enabled 1, and scramdb_wal_archive_segments_archived_total climbing as writes generate and close WAL segments. scramdb_wal_archive_segments_behind and scramdb_wal_archive_bytes_behind only appear once a real measurement exists, their absence on a fresh scrape means "not measured yet," not zero.

Cold: table-data tiering to object storage

This is not available in the current build. There is a [storage.cold_config] section and a cold_enable key in the config surface, but setting cold_enable = true in your TOML has no effect: ScramDB forces this value off unconditionally at startup, regardless of what your config file says. Even setting it aside, there is no writeback or read path wired up behind it today, no scheduled job moves table or segment data to object storage and back. Do not write a config expecting cold data tiering to work, and do not build a cost model around moving table data to cheaper storage automatically, that capability does not exist in ScramDB today.

If reducing storage cost for cold data is your goal today, the working levers are: keep your buffer pool sized to your genuinely active working set (see Memory) so cold data simply is not paged in, and use WAL archival above to avoid growing local disk for durability history.

Next

See Memory for the full buffer-pool field reference, or Backup for how WAL archival backs recovery and branching.