Skip to main content
Version: 2.0.0

Table Storage and Cache Policies

SpacetimeDB uses tiered storage to keep frequently accessed data in memory while allowing colder data to move to local disk or object storage. A table's cache policy determines which storage tiers its data can use. You declare the policy in your module's table definition.

Choose a Cache Policy​

Allowed storage tiersTypeScript / Rust valueC# valueBehavior
Memory only (default)required_in_memoryRequiredInMemoryLoad all the table's pages and blobs into memory at start up.
Memory and local diskrequired_on_diskRequiredOnDiskAllow colder data to page out of memory to local disk. Hot data can remain in memory.
Any available tierno_requirementNoRequirementAllow memory, local disk, and object storage where the deployment enables it.

Omitting the setting selects the in-memory policy. SpacetimeDB moves eligible data out of memory as it needs room and loads it again when accessed. See Resident memory limits for how this works on Maincloud.

Declare the Policy in Your Module​

These examples define a table that can page to local disk and a table that can page to any available tier.

Use the cachePolicy option of table():

import { schema, table, t } from 'spacetimedb/server';

const localHistory = table(
  { name: 'local_history', cachePolicy: 'required_on_disk' },
  {
    id: t.u64().primaryKey(),
    details: t.string(),
  }
);

const archivedHistory = table(
  { name: 'archived_history', cachePolicy: 'no_requirement' },
  {
    id: t.u64().primaryKey(),
    details: t.string(),
  }
);

const spacetimedb = schema({ localHistory, archivedHistory });
export default spacetimedb;

Residency, Durability, and Performance​

Cache policies control where data can reside while the database is running. They do not affect durability. For example, when a database restarts, SpacetimeDB recovers data even for tables configured to reside fully in memory.

The policy applies to table pages and large values stored as blobs. A blob shared by multiple tables stays in memory if at least one of their policies requires it.

Accessing cold data may require storage reads, increasing latency. Use indexed lookups to limit the pages an operation touches, and reserve the in-memory policy for data that needs consistently fast access. Large scans can bring substantial amounts of cold data into the cache. See Performance Best Practices.

Change an Existing Table's Policy​

Update the policy in your module and republish. To return to the default, select the in-memory policy or remove the setting. See Changing a table's cache policy for the publish command and memory requirements.