Data models

A non-exhaustive map of the major persistence tables. The Cassandra schema is canonical (see schema/cassandra/temporal/schema.cql); SQL and SQLite mirror the same logical shape.

Cluster-level tables

Table	Owner / writer	Purpose
cluster_metadata	OperatorService, replication	Registry of clusters that exchange replication.
cluster_metadata_info	OperatorService	Per-cluster details (address, version).
namespaces	NamespaceHandler	One row per namespace + its config.
namespace_metadata	NamespaceHandler	Notification version for namespace cache.
namespace_replication_queue	OperatorService, replication	Cross-cluster namespace updates.
nexus_endpoints	OperatorService	Nexus endpoint registry.

Per-shard tables

These tables are partitioned by shard (shard_id):

Table	Owner	Purpose
shards	History ShardController	Shard ownership + RangeID + queue ack levels.
executions	History engine	One row per workflow execution. Holds Mutable State.
current_executions	History engine	Current run pointer per (namespace, workflow_id).
history_node	History engine	History event chunks.
history_tree	History engine	History branch metadata (forks for resets / N-DC).
transfer_tasks	History queue processor	Transfer queue items (drive Matching).
timer_tasks	History queue processor	Timer queue items (deferred work).
visibility_tasks	History queue processor	Visibility queue items.
replication_tasks	History replication	Outbound replication tasks.
replication_tasks_dlq	History replication	Replication DLQ.
outbound_tasks	History outbound queue	Nexus / callback delivery.
archival_tasks	History archival queue	Archive completed workflows.

The exact column names vary between Cassandra and SQL backends but the role of each table is the same.

Matching

Table	Owner	Purpose
task	Matching backlog	Persisted Workflow / Activity tasks.
task_queues	Matching	Per-(namespace, queue, partition) metadata.
task_queue_user_data	Matching userDataManager	Versioning rules, build-ID sets, etc.

Visibility

The visibility store is logically separate (often Elasticsearch). Its core record is one row per workflow execution with status, namespace, search attributes, and a small set of timestamps. See schema/elasticsearch/ for the ES index template and common/persistence/visibility/ for the SQL implementation.

Schema versions

Each backend has its own schema_version table populated by temporal-cassandra-tool / temporal-sql-tool. New tables and columns land as a new version directory under schema/<backend>/<dbname>/versioned/.

Where to read more

• Persistence
• schema/
• How to contribute → tooling