Skip to main content
Temporal Server uses a database to persist workflow execution state, history, and metadata. This reference describes the schema structure for supported databases.

​
Supported Databases

  • PostgreSQL (v12+)
  • MySQL (v8+)
  • SQLite (v3) - Development only
  • Cassandra (v3+)
Temporal requires two logical databases:
  1. Temporal Store: Core workflow and shard data
  2. Visibility Store: Search and list operations

​
Schema Organization

Schemas are located in the source tree: 
schema/
├── postgresql/
│   └── v12/
│       ├── temporal/
│       │   ├── schema.sql
│       │   └── versioned/
│       └── visibility/
│           ├── schema.sql
│           └── versioned/
├── mysql/
│   └── v8/
│       ├── temporal/
│       └── visibility/
├── sqlite/
│   └── v3/
│       ├── temporal/
│       └── visibility/
└── cassandra/
    └── temporal/

​
Temporal Store Schema

​
Namespaces

​
namespaces

Stores namespace configuration and metadata.
ColumnTypeDescription
partition_idINTEGERPartition identifier (always 54321)
idBYTEA/VARBINARYNamespace UUID
nameVARCHAR(255)Unique namespace name
notification_versionBIGINTVersion for namespace updates
dataBYTEA/BLOBSerialized namespace proto
data_encodingVARCHAR(16)Encoding type (proto3)
is_globalBOOLEANWhether namespace is global
Primary Key: (partition_id, id) Unique Index: name

​
namespace_metadata

Global namespace metadata.
ColumnTypeDescription
partition_idINTEGERPartition identifier
notification_versionBIGINTCurrent notification version
Primary Key: (partition_id)

​
Shards

​
shards

Stores history shard metadata and ownership.
ColumnTypeDescription
shard_idINTEGERShard identifier
range_idBIGINTCurrent range ID for ownership
dataBYTEA/BLOBSerialized shard info
data_encodingVARCHAR(16)Encoding type
Primary Key: (shard_id)

​
Workflow Executions

​
executions

Stores mutable state for workflow executions.
ColumnTypeDescription
shard_idINTEGERShard owning this execution
namespace_idBYTEA/VARBINARYNamespace UUID
workflow_idVARCHAR(255)Workflow identifier
run_idBYTEA/VARBINARYRun UUID
next_event_idBIGINTNext event ID to be assigned
last_write_versionBIGINTVersion for conflict resolution
dataBYTEA/BLOBMutable state proto
data_encodingVARCHAR(16)Encoding type
stateBYTEA/BLOBExecution state proto
state_encodingVARCHAR(16)State encoding
db_record_versionBIGINTDatabase record version
Primary Key: (shard_id, namespace_id, workflow_id, run_id)

​
current_executions

Tracks the current (latest) run for each workflow ID.
ColumnTypeDescription
shard_idINTEGERShard ID
namespace_idBYTEA/VARBINARYNamespace UUID
workflow_idVARCHAR(255)Workflow identifier
run_idBYTEA/VARBINARYCurrent run UUID
create_request_idVARCHAR(255)Request ID that created execution
stateINTEGERExecution state
statusINTEGERWorkflow status
start_versionBIGINTStart version for conflict resolution
start_timeTIMESTAMPWhen execution started
last_write_versionBIGINTLast write version
dataBYTEA/BLOBWorkflowExecutionState proto
data_encodingVARCHAR(16)Encoding type
Primary Key: (shard_id, namespace_id, workflow_id)

​
current_chasm_executions

Tracks current Chasm (state machine) executions.
ColumnTypeDescription
shard_idINTEGERShard ID
namespace_idBYTEA/VARBINARYNamespace UUID
business_idVARCHAR(255)Business identifier
archetype_idBIGINTArchetype identifier
run_idBYTEA/VARBINARYCurrent run UUID
create_request_idVARCHAR(255)Creation request ID
stateINTEGERExecution state
statusINTEGERStatus
start_versionBIGINTStart version
start_timeTIMESTAMPStart time
last_write_versionBIGINTLast write version
dataBYTEA/BLOBExecutionState proto
data_encodingVARCHAR(16)Encoding
Primary Key: (shard_id, namespace_id, business_id, archetype_id)

​
History Events

​
history_node

Stores history events in a tree structure.
ColumnTypeDescription
shard_idINTEGERShard ID
tree_idBYTEA/VARBINARYHistory tree identifier
branch_idBYTEA/VARBINARYBranch identifier
node_idBIGINTNode ID
txn_idBIGINTTransaction ID
prev_txn_idBIGINTPrevious transaction ID
dataBYTEA/BLOBHistory events batch
data_encodingVARCHAR(16)Encoding type
Primary Key: (shard_id, tree_id, branch_id, node_id, txn_id)

​
history_tree

Stores metadata about history branches.
ColumnTypeDescription
shard_idINTEGERShard ID
tree_idBYTEA/VARBINARYTree identifier
branch_idBYTEA/VARBINARYBranch identifier
dataBYTEA/BLOBBranch info proto
data_encodingVARCHAR(16)Encoding type
Primary Key: (shard_id, tree_id, branch_id)

​
Tasks

​
history_immediate_tasks

Immediate tasks (transfer, visibility) for workflow execution.
ColumnTypeDescription
shard_idINTEGERShard ID
category_idINTEGERTask category
task_idBIGINTTask identifier
dataBYTEA/BLOBTask data proto
data_encodingVARCHAR(16)Encoding type
Primary Key: (shard_id, category_id, task_id)

​
history_scheduled_tasks

Scheduled tasks (timers, delayed tasks).
ColumnTypeDescription
shard_idINTEGERShard ID
category_idINTEGERTask category
visibility_timestampTIMESTAMPWhen task becomes visible
task_idBIGINTTask identifier
dataBYTEA/BLOBTask data proto
data_encodingVARCHAR(16)Encoding type
Primary Key: (shard_id, category_id, visibility_timestamp, task_id)

​
Task Queues

​
tasks_v2

Stores workflow and activity tasks with fairness scheduling.
ColumnTypeDescription
range_hashBIGINTHash for partitioning
task_queue_idBYTEA/VARBINARYTask queue identifier
passBIGINTScheduling pass for fairness
task_idBIGINTTask identifier
dataBYTEA/BLOBTask data
data_encodingVARCHAR(16)Encoding type
Primary Key: (range_hash, task_queue_id, pass, task_id)

​
task_queues_v2

Task queue metadata and state.
ColumnTypeDescription
range_hashBIGINTHash for partitioning
task_queue_idBYTEA/VARBINARYTask queue identifier
range_idBIGINTRange ID for ownership
dataBYTEA/BLOBTask queue state
data_encodingVARCHAR(16)Encoding type
Primary Key: (range_hash, task_queue_id)

​
task_queue_user_data

User-defined task queue data including versioning.
ColumnTypeDescription
namespace_idBYTEA/VARBINARYNamespace UUID
task_queue_nameVARCHAR(255)Task queue name
dataBYTEA/BLOBTaskQueueUserData proto
data_encodingVARCHAR(16)Encoding type
versionBIGINTVersion for optimistic locking
Primary Key: (namespace_id, task_queue_name)

​
build_id_to_task_queue

Maps worker build IDs to task queues.
ColumnTypeDescription
namespace_idBYTEA/VARBINARYNamespace UUID
build_idVARCHAR(255)Build identifier
task_queue_nameVARCHAR(255)Task queue name
Primary Key: (namespace_id, build_id, task_queue_name)

​
Cluster Management

​
cluster_metadata_info

Stores cluster configuration for multi-cluster setups.
ColumnTypeDescription
metadata_partitionINTEGERPartition ID
cluster_nameVARCHAR(255)Cluster name
dataBYTEA/BLOBCluster metadata proto
data_encodingVARCHAR(16)Encoding type
versionBIGINTVersion number
Primary Key: (metadata_partition, cluster_name)

​
cluster_membership

Tracks cluster members and their roles.
ColumnTypeDescription
membership_partitionINTEGERPartition ID
host_idBYTEA/VARBINARYHost UUID
rpc_addressVARCHAR(128)RPC address
rpc_portSMALLINTRPC port
roleSMALLINTService role
session_startTIMESTAMPWhen session started
last_heartbeatTIMESTAMPLast heartbeat time
record_expiryTIMESTAMPWhen record expires
Primary Key: (membership_partition, host_id) Indexes:
  • (role, host_id)
  • (role, last_heartbeat)
  • (rpc_address, role)
  • (last_heartbeat)
  • (record_expiry)

​
Queues

​
queues

Named queue metadata.
ColumnTypeDescription
queue_typeINTQueue type identifier
queue_nameVARCHAR(255)Queue name
metadata_payloadBYTEA/BLOBQueue metadata
metadata_encodingVARCHAR(16)Encoding type
Primary Key: (queue_type, queue_name)

​
queue_messages

Messages in named queues.
ColumnTypeDescription
queue_typeINTQueue type
queue_nameVARCHAR(255)Queue name
queue_partitionBIGINTPartition ID
message_idBIGINTMessage identifier
message_payloadBYTEA/BLOBMessage data
message_encodingVARCHAR(16)Encoding type
Primary Key: (queue_type, queue_name, queue_partition, message_id)

​
Nexus Endpoints

​
nexus_endpoints

Stores Nexus endpoint configurations.
ColumnTypeDescription
idBYTEA/VARBINARYEndpoint UUID
dataBYTEA/BLOBNexusEndpoint proto
data_encodingVARCHAR(16)Encoding type
versionBIGINTVersion for optimistic locking
Primary Key: (id)

​
nexus_endpoints_partition_status

Tracks version of nexus_endpoints table.
ColumnTypeDescription
idINTAlways 0 (single row)
versionBIGINTTable version
Primary Key: (id) Constraint: id = 0 (single row table)

​
Visibility Store Schema

​
executions_visibility

Main visibility table for workflow search.
ColumnTypeDescription
namespace_idVARCHAR(64)Namespace UUID
workflow_idVARCHAR(255)Workflow identifier
run_idVARCHAR(64)Run UUID
start_timeTIMESTAMPWorkflow start time
close_timeTIMESTAMPWorkflow close time
workflow_type_nameVARCHAR(255)Workflow type
statusINTWorkflow status
history_lengthBIGINTNumber of history events
execution_timeTIMESTAMPExecution timestamp
memoBYTEA/BLOBMemo data
encodingVARCHAR(64)Encoding type
task_queueVARCHAR(255)Task queue name
search_attributesJSONB/JSONCustom search attributes
Primary Key: (namespace_id, run_id) Indexes:
  • (namespace_id, close_time, status)
  • (namespace_id, start_time, status)
  • (namespace_id, workflow_type_name, close_time)
  • Additional indexes on search attributes

​
Schema Versioning

Temporal uses versioned schema migrations:
  • Base schema: schema.sql
  • Migrations: versioned/vX.Y/*.sql
Example: 
schema/postgresql/v12/temporal/
├── schema.sql (base schema)
└── versioned/
    ├── v1.0/schema.sql
    ├── v1.1/cluster_metadata.sql
    ├── v1.2/queue.sql
    └── v1.19/current_chasm_executions.sql

​
Setup and Migration

​
Initial Setup

# Create database
temporal-sql-tool --plugin postgres create-database

# Setup schema
temporal-sql-tool --plugin postgres setup-schema -v 0.0
temporal-sql-tool --plugin postgres update-schema -d schema/postgresql/v12/temporal/versioned

​
Upgrade Schema

# Check current version
temporal-sql-tool --plugin postgres version

# Upgrade to latest
temporal-sql-tool --plugin postgres update-schema -d schema/postgresql/v12/temporal/versioned

​
Best Practices

  1. Separate Databases: Use separate physical databases for temporal and visibility stores
  2. Connection Pooling: Configure appropriate connection pool sizes
  3. Indexes: Monitor slow queries and add indexes as needed
  4. Partitioning: Consider table partitioning for very large deployments
  5. Backups: Regular backups are essential - test restore procedures
  6. Retention: Configure appropriate retention policies
  7. Monitoring: Monitor database metrics (CPU, IOPS, connections)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us