Which Temporal database fits your team: PostgreSQL, MySQL or Cassandra
If your team is self-hosting a Temporal Service and needs to pick where it persists workflow state, PostgreSQL is the store most teams should evaluate first, with MySQL a sound choice when your operations staff already run it well, and Cassandra justified mainly when you already operate it at scale and accept a second store for visibility. SQLite is for development and testing only, and the Temporal persistence docs state it is not meant for production. Confirm the exact tested versions against the Temporal persistence documentation before you standardize, since Temporal tests Cassandra 3.11, 4.0 and 5.0.4 or later, PostgreSQL 13 through 16, and MySQL 5.7 and 8.0.19 or later.
PostgreSQL fits teams that already run it, want one relational operations model for Temporal and their other systems, and need a clear major-version upgrade path. The PostgreSQL versioning policy supports each major release for five years, and PostgreSQL 14 is listed as supported only until November 12, 2026, so pick a major version that will still be supported through your planned Temporal lifecycle. MySQL fits teams standardized on MySQL with DBA skills in replication and backup, and you should check which LTS line your Temporal release supports. Cassandra fits when your organization already runs Cassandra at the scale Temporal's workloads require, because it adds operational expertise you would otherwise not need.
Cassandra always needs a separate Visibility store. Temporal does not support Cassandra for visibility, so a Cassandra deployment must add Elasticsearch, OpenSearch, MySQL, PostgreSQL or SQLite for visibility, and the docs recommend Elasticsearch or OpenSearch once you run more than a few Workflow Executions. Budget for that second system in both build effort and run effort, and ask your team to confirm which visibility store the target Temporal release supports before you commit. Because Dual Visibility allows moving the Visibility store between databases since Temporal Server v1.21, a visibility choice made now is not permanent, but plan the migration rather than assuming it will be simple.
Cassandra, PostgreSQL and MySQL side by side for Temporal
This table compares the three tested persistence stores for a self-hosted Temporal Service on tested versions, licensing, visibility pairing, high availability, upgrades and operator skills. Read each row as a checklist: the documented fact comes first, and the items to confirm with your own environment or vendor follow it.
| Area | Cassandra | PostgreSQL | MySQL |
|---|---|---|---|
| Tested versions for persistence | Cassandra 3.11, 4.0 and 5.0.4 or later, per the Temporal persistence docs | PostgreSQL 13.18, 14.15, 15.10 and 16.6 in the tested list, per the Temporal persistence docs. Confirm the current list before you pick a version | MySQL 5.7 and 8.0 (8.0.19 or later required), per the Temporal persistence docs |
| License | Confirm the license terms of the Cassandra distribution you select with your legal team | PostgreSQL License, a liberal license similar to BSD or MIT | MySQL Community Edition is GPL. Oracle paid editions add Enterprise Backup, TDE and 24x7 support |
| Visibility store pairing | Cassandra cannot be a Visibility store. Standard visibility on Cassandra was removed in Temporal Server v1.24, so you must add a separate supported store | Can serve as both persistence and Visibility store, with PostgreSQL 12 or later for Visibility | Can serve as both persistence and Visibility store, with MySQL 8.0.17 or later for Visibility |
| Visibility at scale | Pair with Elasticsearch 7 or 8, or OpenSearch 2 or later, which the docs recommend beyond a few Workflow Executions | Docs recommend Elasticsearch or OpenSearch for setups that spawn more than a few Workflow Executions. Test your own volume before relying on SQL visibility | Same guidance as PostgreSQL. Test SQL visibility against your expected execution volume |
| High availability approach | Cluster-based design. Confirm replication and node settings with your Cassandra operator guidance | Hot standbys with synchronous or asynchronous replication. Automatic failover needs external tools, since PostgreSQL does not detect primary failure itself | Group Replication with automated failover and InnoDB Cluster are in Community Edition, with MySQL Router and MySQL Shell |
| Upgrade path | Confirm schema and node upgrade steps for your Cassandra version against Temporal upgrade notes | Minor releases do not change storage format. Major upgrades use pg_dumpall, pg_upgrade or logical replication, which works across major versions | LTS track for long support, Innovation track supported only until the next Innovation release. Choose the LTS line for production |
| Operator skills required | Distributed database operations, including cluster repair and capacity planning. Confirm internal skills or a support contract | Standard SQL database administration, backups, replication and failover tooling. PgBouncer is a documented option for connection pooling | Standard SQL database administration, plus Group Replication and Router if you use InnoDB Cluster |
| Development use only | Not applicable. Temporal does not list Cassandra as development-only | SQLite 3.x is meant only for development and testing, for any of the three stores | SQLite 3.x is meant only for development and testing, for any of the three stores |
Why persistence and Visibility are two decisions
A self-hosted Temporal Service keeps workflow state in its persistence store and keeps the searchable workflow metadata (what is running, what has completed, and which search attributes match) in a separate Visibility store. Choosing Cassandra, PostgreSQL or MySQL answers only the first question. The second question has to be answered on its own, and for a Cassandra deployment the answer is never Cassandra. Temporal does not support Cassandra as a Visibility store, so any team that picks Cassandra for persistence must add a second database for Visibility before the cluster can run.
The supported Visibility stores are Elasticsearch (v7 and v8), OpenSearch 2 and later, MySQL 8.0.17 or later, PostgreSQL 12 or later and SQLite 3.31.0 or later. SQLite is suitable only for development. The Temporal visibility docs recommend Elasticsearch or OpenSearch once a setup runs more than a few Workflow Executions, so a team planning real volume should treat that search cluster as a required component, with its own sizing, backups and upgrade plan. A team that persists to PostgreSQL or MySQL can often use the same engine for Visibility, which reduces the number of systems to operate. Confirm the exact version pairing for your Temporal Server release in the Temporal self-hosted visibility docs before you commit.
Plan for the second store as a reversible decision, not a permanent one. Since Temporal Server v1.21, Dual Visibility lets operators move the Visibility store from one database to another, so a team can start with a simple store and move to Elasticsearch or OpenSearch later. Ask your Temporal and search-platform specialists to confirm the migration path for your target versions, and write the Visibility choice into your capacity plan from day one.
How the Frontend, History, Matching and Worker services use the stores
A self-hosted Temporal Service is a set of four cooperating services sitting on top of a persistence store and a separate Visibility store. The database you pick for persistence affects every one of these components, so it helps to know which service touches which store before you size or secure the cluster.
Frontend service
The Frontend is the entry point for SDK clients and the Web UI, so it handles API requests, authorization checks and rate limits before work reaches the rest of the cluster. Because it is the only component clients reach directly, it is where the Authorizer and mTLS settings matter most. If no Authorizer is configured, the default noopAuthorizer allows every API request, so confirm this is replaced before any shared network can reach the Frontend.
History service
History owns workflow state and writes the ordered event history that Temporal replays to resume workflows after failures. It is the heaviest writer to the persistence store, so the choice between Cassandra, PostgreSQL and MySQL shows up here first in write throughput and sharding behavior. Ask your team to load test History against the store you choose, not only the Frontend.
Matching service
Matching manages task queues and hands workflow and activity tasks to Workers. It depends on persistence for queue state, so store latency affects how quickly tasks reach Workers. Confirm task queue behavior under load in a staging cluster before you commit to a database engine.
Worker service
The Worker service runs Temporal's own background system workflows that handle tasks such as archival and replication. It reads and writes persistence on its own schedule, so it competes with History for database capacity. Size the store with background work in mind, not only with application traffic.
Persistence store
Persistence holds workflow execution state and history. The tested options are Cassandra 3.11, 4.0 and 5.0.4 or later, PostgreSQL 13 to 16, and MySQL 5.7 and 8.0.19 or later. SQLite is meant only for development and testing. Confirm the exact versions you will run against the persistence documentation before you pick a database.
Visibility store and network placement
The Visibility store answers list and search queries over workflow executions, and Cassandra deployments must add a supported Visibility store alongside it. Elasticsearch or OpenSearch is recommended once you run more than a few Workflow Executions. The Temporal deployment docs also require that services run on hosts not reachable from the public internet, with access limited to trusted internal networks, so plan network placement for every store as well.
Which database to choose by existing team skills and platform
If your organization already operates PostgreSQL for other platforms, Temporal's persistence and Visibility needs can often be met on the same skill set. PostgreSQL is tested by Temporal on versions 13 through 16, and PostgreSQL 14 is the release that remains supported until November 2026, so check which major version your team runs against that window. Your database team already knows backups, replication and major upgrades, which lowers the operating surprise.
- Upgrade planning: Major upgrades use pg_dumpall and restore, pg_upgrade, or logical replication, so confirm which method your team has rehearsed.
- Failover design: PostgreSQL does not detect a primary failure on its own, so automatic failover depends on external tooling your team must choose and run.
- Connection management: Ask whether your team already uses a connection pooler such as PgBouncer and how it interacts with Temporal's services.
- Visibility fit: PostgreSQL 12 or later can serve as a Visibility store, but the Temporal documentation recommends Elasticsearch or OpenSearch once a deployment spawns more than a few Workflow Executions.
- Authentication: Confirm how your identity team wants database access handled, since PostgreSQL supports certificate, LDAP, GSSAPI and OAuth methods.
Before committing, confirm with the database team which supported major version they will run, who owns the failover tooling, and how backups and point-in-time recovery are tested.
Teams that already run MySQL for other applications can persist Temporal to MySQL on the tested lines, MySQL 5.7 and 8.0, with 8.0.19 or later required. MySQL also supports Visibility from 8.0.17 or later. The MySQL release model matters here: the LTS track gets extended support, while Innovation releases are supported only until the next Innovation release, so the version you pick determines how long you can stay on it without an upgrade.
- Version choice: Check whether your database team runs an LTS line and confirm that line is on Temporal's tested list before you deploy.
- Edition needs: MySQL Community Edition includes InnoDB Cluster, Group Replication and MySQL Router, while Enterprise Edition adds Enterprise Backup, Transparent Data Encryption and 24x7 Oracle support. Decide which of these your controls require.
- Backup approach: Enterprise Backup provides hot backups in the paid edition, so confirm how the Community Edition backup process will be run and tested.
- Licensing review: MySQL Community Edition is available under the GPL, so have legal confirm that this fits your distribution and hosting model.
- Visibility store: MySQL works as a Visibility store, but confirm that the same team will own the scaling plan once Workflow Execution volume grows.
Before committing, confirm the exact MySQL line and patch level, the edition your controls require, and who runs upgrades inside the LTS support window.
If your organization already runs Apache Cassandra, Temporal can persist to it on the tested versions 3.11, 4.0 and 5.0.4 or later. Cassandra is a persistence choice only. It cannot serve as the Visibility store, because standard visibility on Cassandra was deprecated in Temporal Server v1.21 and removed in v1.24. That means a Cassandra deployment always adds a second database to operate, usually Elasticsearch, OpenSearch, or one of the other supported Visibility stores.
- Two stores to run: Plan for the persistence cluster and a separate Visibility store, each with its own backups, upgrades and monitoring.
- Team skills: Confirm that your Cassandra operators are comfortable with the schema upgrade order that Temporal requires, where schema changes run before server upgrades when release notes call for them.
- Visibility choice: Elasticsearch or OpenSearch is the recommended path at scale, so confirm whether your search team already runs either engine.
- Consistency expectations: Ask your Cassandra team how they tune replication and consistency for workloads that write execution history.
- Migration path: Dual Visibility lets you change the Visibility store later, which can reduce the risk of choosing a store that does not fit your growth.
Before committing, confirm which Cassandra version your operators support, whether they will own the separate Visibility store, and whether a PostgreSQL or MySQL platform would be simpler to run for your team.
Upgrades, backups, monitoring and skills for each store
This table compares how each persistence store is upgraded, backed up, made highly available and staffed when it sits under a self-hosted Temporal Service. Read it as an operating checklist: the store you pick decides which upgrade path, failover tooling and team skills you need before go-live.
| Area | Cassandra | PostgreSQL | MySQL |
|---|---|---|---|
| Upgrade path | Cassandra upgrades are a separate operating task from Temporal schema upgrades, so confirm the Cassandra version against Temporal's tested list (3.11, 4.0, 5.0.4 or later) before you plan a change. | Minor releases replace executables and restart without changing storage format. Major upgrades use pg_dumpall with restore, pg_upgrade or logical replication, and PostgreSQL 14 support ends November 12, 2026. | LTS and Innovation tracks differ in support length. Temporal requires MySQL 8.0.19 or later, so confirm your target line against that floor and Oracle's support policy. |
| Backup and recovery | Backup tooling and snapshot procedures are Cassandra-specific. Ask your team to document restore tests for both the persistence keyspace and the separate Visibility store. | Continuous archiving and point-in-time recovery are documented in PostgreSQL. Test restores for the Temporal database and the Visibility database, since both hold state you need. | Enterprise Backup provides hot backups under MySQL Enterprise Edition. Community Edition users need to confirm which backup tools their team will run and test. |
| Built-in high availability | Cassandra is a distributed store, but replication settings and repair schedules are operator decisions. Confirm them with your Cassandra specialist. | Hot standby servers serve read-only queries, with synchronous or asynchronous replication. Automatic failover needs external tools, because PostgreSQL does not detect primary failure or notify standbys. | InnoDB Cluster and Group Replication with automated failover are included in Community Edition, with MySQL Router and MySQL Shell for connection and management. |
| Failover ownership | Owned by the Cassandra cluster design. Confirm how Temporal reconnects during node loss in your tested configuration. | Plan and test a failover tool, fencing and connection routing, such as PgBouncer, before production. Assign an owner for each step. | Failover is part of the cluster design, so test it against your Temporal deployment rather than assuming automatic recovery for every failure. |
| Monitoring focus | Watch node health, compaction and latency, plus the Visibility store's query latency and indexing lag. | Watch replication lag, connection counts, long transactions and disk growth on both the persistence and Visibility databases. | Watch replication or cluster member state, connection use and InnoDB health, plus Visibility store query behavior. |
| Team skills needed | Distributed database operations, including repair, compaction and capacity planning, plus Elasticsearch or OpenSearch if you add search-based Visibility. | Standard relational operations: backups, replication, upgrades and query tuning. Many platform teams already hold this skill. | Standard relational operations, with InnoDB Cluster and Router experience for high availability. Confirm Oracle licensing for any Enterprise features you need. |
How to migrate Visibility later without rebuilding the cluster
This sequence moves a self-hosted Temporal Visibility store from one supported database to another while the Temporal Service keeps running, so the persistence choice made at launch does not lock you in.
Confirm the current server and visibility versions
The platform or SRE owner records the Temporal Server minor version, the Helm chart or binary version, and the Visibility store currently in use. Temporal's Dual Visibility capability is available since Temporal Server v1.21, so confirm the running minor line is at or after that release before planning anything else. Check the Temporal visibility documentation for the store versions your target supports, such as Elasticsearch or OpenSearch 2 and later from Server 1.30.1. The output is a written inventory of current and target versions that the rest of the sequence references.
Rehearse the migration in a non-production namespace
The platform team sets up a staging cluster with a copy of the current configuration and creates a test namespace. They run a representative mix of Workflow Executions, including long-running, timer-driven and failed workflows, and then enable Dual Visibility so both stores receive writes. Before any production change, they check that list and search queries return the same results from both stores, that workflows with custom search attributes are indexed correctly, and that the Visibility backlog clears. The output is a signed-off test record that names every query type checked.
Upgrade to the latest patch of the current minor
Before changing any store, the operator moves the running server to the latest patch release of its current minor version. Temporal guarantees backward compatibility only between two successive minor versions, so this step removes known patch-level issues before the larger change. The operator reads the release notes for each patch and confirms the Helm chart version is compatible with the server image, since chart versions below 0.73.1 do not work with server images 1.30 and later. The output is a cluster reporting the new patch version with healthy Frontend, History, Matching and Worker services.
Run schema upgrades before server upgrades
Where the release notes for the next minor version call for a schema change, the database administrator runs the schema upgrade against the persistence and Visibility stores first, using the tooling that matches each database. Only after the schema change completes does the operator update the server binaries or images. Running the server before the schema is ready can cause failures that look like application errors, so the order matters. The output is a schema version recorded in each store that matches what the release notes require.
Step up one minor version at a time
The operator repeats the upgrade cycle for each intermediate minor line, moving from one minor version to the next and stopping at the latest patch of each before continuing. Because backward compatibility is guaranteed only between two successive minor versions, skipping a line is not a supported path. Each stop gets a health check of the frontend, workers and a sample workflow. The output is a cluster on the target minor version with its patch level recorded at every stop.
Enable Dual Visibility and backfill the new store
The operator configures the cluster to write Visibility records to both the existing store and the target store, then lets the new store catch up with historical records as the service supports. The platform team watches the Visibility write path and workflow list queries for errors while the backfill runs. The output is a target store that returns the same counts and search results as the source for the test namespace and the production namespaces.
Switch reads and retire the old store
Once the new store matches the old one, the team points Visibility reads at the target store, watches application error rates and query latency for the period their runbook defines, and only then stops writes to the old store. Retiring the old store is a separate change with its own backup and rollback plan. The output is a documented cut-over record and a Visibility store that serves all list and search queries, with the previous store kept until the rollback window closes.
Document the cut-over and test rollback
The operator records the versions, schema states, Dual Visibility settings and cut-over time in the runbook, and confirms the team can revert reads to the previous store. Rollback should be rehearsed in the non-production namespace before it is needed in production. Confirm with your Temporal support channel or the vendor documentation any step specific to your Temporal Server minor version. The output is a runbook that another engineer can follow without the original author.
Questions buyers ask before choosing a Temporal database
Is SQLite acceptable for a production Temporal Service?
No. The Temporal persistence documentation says SQLite 3.x persistence is meant only for development and testing, not production. For a production self-hosted Temporal Service, choose one of the tested persistence stores: Cassandra, PostgreSQL or MySQL. SQLite can still be useful on a laptop to try workflows locally, but a team that moves a prototype into production on SQLite will need to rebuild its persistence layer before go-live. Confirm the exact supported versions for your chosen store against the persistence documentation before you write the deployment plan.
Why does a Cassandra-backed Temporal deployment need a separate Visibility store?
Cassandra cannot serve as a Temporal Visibility store. Standard visibility on Cassandra was deprecated in Temporal Server v1.21 and removed in v1.24, so a deployment that persists to Cassandra must pair it with a supported Visibility store. The supported options are Elasticsearch v7 and v8, OpenSearch 2 and later, MySQL 8.0.17 or later, PostgreSQL 12 or later and SQLite 3.31.0 or later. That means a Cassandra deployment runs two stores, with their own sizing, backups and upgrades. Ask your team to count this second store in the operating model before choosing Cassandra.
When is Elasticsearch or OpenSearch needed for Temporal visibility?
The Temporal visibility documentation recommends Elasticsearch or OpenSearch for any setup that spawns more than a few Workflow Executions. Below that scale, a relational Visibility store on MySQL or PostgreSQL may be enough, which keeps the stack smaller. Above it, search and filtering across many executions usually justify the extra cluster. Supported versions include Elasticsearch 7 and 8 and OpenSearch 2 or later from Temporal Server 1.30.1. Estimate your execution volume and query patterns, then confirm the threshold with Temporal's documentation and a load test in your own environment.
What drives the cost and effort of each database option?
The main cost components are the licenses, the infrastructure, and the people who run the stores. PostgreSQL is released under the PostgreSQL License, and MySQL Community Edition is available under the GPL, so software cost is usually not the driver for either. Cassandra adds a Visibility store, which doubles the number of stores to operate. For MySQL, Enterprise Edition adds features such as Enterprise Backup and Transparent Data Encryption under a commercial subscription. For PostgreSQL, high availability needs external failover tooling, because PostgreSQL does not detect a primary failure on its own. Ask any quote to separate infrastructure, licensing, one-time setup and recurring operations.
How long does a Temporal visibility migration take, and what does it need from our team?
The duration depends on your data volume, your downtime tolerance and the store pair involved, and no supplied fact gives a figure, so ask for an estimate based on your own environment. Since Temporal Server v1.21, Dual Visibility lets operators migrate the Visibility store from one database to another. The work needs someone who can run the Temporal Server upgrade path, which requires moving one minor version at a time and running schema upgrades before server upgrades when release notes call for them. Your team also needs to test queries against the new store and plan a rollback path before cutover.
Can our internal team run a self-hosted Temporal database alone?
It depends on your existing database skills and the store you choose. A team that already operates PostgreSQL or MySQL in production can usually extend that work to Temporal, while a team with no Cassandra or Elasticsearch experience will need to learn those systems before taking on production duty. Temporal's self-hosted deployment docs say services should run on hosts not reachable from the public internet, and that matters for every store in the design. DeployOpen plans, implements, hardens, backs up, upgrades and documents self-hosted platforms in your infrastructure, and can support ongoing operations through a retainer. Ask for a written scope that names the stores, the skills you already have and the handover you need.
Which Temporal security controls depend on the database choice?
Authentication and authorization sit mostly in the Temporal Service, not in the database. If no Authorizer is configured, self-hosted Temporal uses the default noopAuthorizer, which allows every API request with no authentication or access control. Temporal supports mTLS with separate settings for internode and frontend traffic, a ClaimMapper for JWT or certificate claims, an Authorizer plugin, and OIDC single sign-on for the Web UI. The database choice still matters for protecting stored data. PostgreSQL supports certificate, LDAP and OAuth client authentication, and MySQL Enterprise Edition adds Transparent Data Encryption. Confirm which of these controls your chosen store needs before you approve the design.
Which database should a team pick for a new self-hosted Temporal Service?
Choose PostgreSQL if your team already runs it well and you want one relational store for both persistence and a modest Visibility store. Choose MySQL if your organization standardizes on it and you need its Community or Enterprise tooling. Choose Cassandra only if you have a proven Cassandra operating practice and accept the second Visibility store that comes with it. Whichever you pick, plan for Elasticsearch or OpenSearch once your execution volume grows. The tested versions for PostgreSQL include 14 through 18 in support windows documented by PostgreSQL, so align your choice with a supported major version.
How DeployOpen scopes and delivers a Temporal persistence deployment
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks, so the persistence choice is made against your environment. Engagements are usually fixed-scope, with the scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Confirm which persistence store your team is allowed to operate, since Cassandra adds a separate Visibility store that PostgreSQL or MySQL deployments can avoid.
- Record the Temporal Server version line, the Helm chart version and the database versions you intend to run, checked against Temporal's tested lists.
- Agree in writing whether visibility starts on a SQL store or moves to Elasticsearch or OpenSearch, and what volume triggers that decision.
- Define the written scope for network placement, internal-only access, and how authentication, mTLS and payload encryption will be configured.
How we build
- Deploy the Frontend, History, Matching and Worker services with the chosen persistence and visibility stores in a non-production environment first.
- Configure the Authorizer and ClaimMapper so no API request is allowed without a deliberate access decision.
- Set up database replication, backups and point-in-time recovery for the chosen store, and test a restore before go-live.
- Run upgrade rehearsals that follow Temporal's one-minor-version-at-a-time path, with schema upgrades run before server upgrades when release notes require them.
How we hand over
- Deliver architecture and runbook documentation covering each store, its versions, its backup and failover procedure, and its owner.
- Document the visibility migration path, including how Dual Visibility would be used if the store changes later.
- Provide evidence of configuration, access controls and tested restores that your internal or external auditors can review.
- Walk your platform and database teams through day-two operations, upgrade steps and the escalation path for incidents.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after handover, scoped separately from the initial build.
- Track Temporal and database release windows so upgrades are planned before a version leaves support.
- Ask any quote to separate one-time build effort from recurring retainer effort, so you can compare options on total ownership cost.
- Confirm with your database vendor and Temporal's documentation any version or failover behavior that your environment depends on before go-live.
