Skip to content

CONCEPT Cited by 1 source

Temporal persistence layer

Definition

A Temporal cluster is a Temporal Server paired with a persistence layer — the durable data store that holds every piece of state the server needs to survive restarts, resume workflows, and dispatch work to workers. The persistence layer is pluggable: Temporal ships with two supported storage classes, one SQL (MySQL or PostgreSQL) and one NoSQL (Cassandra), and the choice determines the operational envelope of the cluster.

What the persistence layer stores

Six categories of data live in the persistence layer (Source: sources/2026-04-21-planetscale-temporal-workflows-at-scale-with-planetscale-part-1):

  • Tasks to be dispatched — pending activity / workflow tasks waiting for a worker to claim them.
  • Workflow Execution state — the authoritative record of which workflows are running, completed, failed, etc.
  • Mutable state of Workflow Executions — per-execution state that changes over the workflow's life (timers, pending child workflows, pending activities).
  • Event History — the append-only log of Workflow Execution History Events. This is the substrate Temporal replays from when a workflow is rehydrated after a crash; it is the concrete realisation of durable execution via write-ahead logging applied to user-space workflow code.
  • Namespace metadata — per-namespace configuration inside the cluster.
  • Visibility data — the indexed surface that answers queries like "show all running Workflow Executions".

The SQL vs NoSQL trade-off

PlanetScale's framing of the choice (Source: Longoria 2022-07-22):

If you choose SQL, you trade operational simplicity for scalability. If you decide on No-SQL, you trade scalability for operational complexity.

  • SQL (MySQL / PostgreSQL) — mature tooling, familiar ops, single-node read-your-writes semantics, rich query surface for visibility. But a single SQL instance caps Temporal's throughput at that one box's write ceiling; scaling requires manually standing up read replicas + sharding or adopting a horizontally-sharded SQL substrate.
  • NoSQL (Cassandra) — linear horizontal scalability for Temporal's workload shape, but the operator inherits Cassandra's tuning surface (compaction, tombstones, repair, gossip cluster health) which is substantially richer than running a single MySQL instance.

PlanetScale's structural argument for picking their substrate: PlanetScale's Vitess layer gives you MySQL's operational simplicity with horizontal-sharding scalability — collapsing the trade-off into a single choice rather than forcing one or the other.

Horizontal-partitioning alignment

Temporal also uses horizontal partitioning internally — workflows are partitioned across the History subsystem's shards (see Mikhail Shilkov's Choosing the number of shards in Temporal History service for the sizing framework). This means Temporal's shard count composes cleanly with the persistence layer's shard count: if the backing store is already horizontally sharded (Vitess / Cassandra), you can scale both independently without re-architecting.

The 2022-07-22 Longoria post makes this point explicitly:

Since Temporal also uses horizontal partitioning, Temporal maps effortlessly onto PlanetScale and can take full advantage of PlanetScale's scalability improvements over a single MySQL instance.

Dev-vs-production deployment distinction

PlanetScale calls out that the four quick-start deployment paths Temporal publishes — Docker Compose, Render Blueprint, Helm charts, Gitpod — are not production configurations. The blog series (Part 2, not yet published at the time of ingest) walks through the production shape: docker-compose talking to PlanetScale with the temporal and temporal_visibility tables created manually inside the managed database.

Seen in

  • sources/2026-04-21-planetscale-temporal-workflows-at-scale-with-planetscale-part-1 — canonical wiki disclosure of Temporal's persistence layer as a pluggable SQL-vs-NoSQL choice with the explicit "operational simplicity vs scalability" trade-off framing, and of the horizontal-partitioning alignment between Temporal's internal shards and the backing store's shards. Savannah Longoria (PlanetScale, 2022-07-22) frames PlanetScale/Vitess as the substrate that collapses the trade-off.
Last updated · 470 distilled / 1,213 read