temporal-dsql

Temporal server with an Amazon Aurora DSQL persistence plugin.

This is a community distribution of Temporal. It isn't affiliated with or endorsed by Temporal Technologies, Inc. "Temporal" is a trademark of Temporal Technologies, Inc.

Warning

Experimental: don't use this in production yet. A review in October 2026 found correctness defects in shard ownership, transaction retries and namespace updates. They're tracked as open issues, and the critical and high ones should be fixed first.

What this adds to Temporal

• A dsql SQL persistence plugin for Temporal's default store, in common/persistence/sql/sqlplugin/dsql
• A DSQL schema, in schema/dsql, and a schema tool, temporal-dsql-tool
• IAM authentication with generated tokens, so no database password is stored
• A connection reservoir, and optional DynamoDB coordination, for DSQL's connection-rate limits

DSQL holds the persistence store only. Visibility needs a separate store, such as OpenSearch, Elasticsearch, PostgreSQL, MySQL or SQLite.

Everything outside the plugin, its schema and its tooling is upstream Temporal code.

Compatibility

Temporal base	Upstream main as of 2026-04-06, just before v1.31.0
DSQL schema version	1.1
Go	1.26

Quick start

You need an Aurora DSQL cluster, AWS credentials that can call dsql:DbConnectAdmin on it, and Go 1.26.

1. Build the server and the schema tool:

   make temporal-server temporal-dsql-tool

2. Create the schema on a new cluster:

   export AWS_REGION=us-east-1
   ./temporal-dsql-tool --endpoint <cluster-id>.dsql.us-east-1.on.aws --region us-east-1 \
     setup-schema --schema-name dsql/temporal --version 1.1

   Start from a new cluster at version 1.1. Upgrading an existing v1.0 schema currently fails (#28).

3. Copy config/development-dsql.yaml and replace its persistence block with this one:

   persistence:
     defaultStore: dsql
     visibilityStore: visibility
     numHistoryShards: 4              # can't be changed after the cluster is created
     datastores:
       dsql:
         sql:
           pluginName: "dsql"
           databaseName: "postgres"   # a DSQL cluster has one database, named postgres
           connectAddr: "<cluster-id>.dsql.us-east-1.on.aws:5432"
           connectProtocol: "tcp"
           tls:
             enabled: true
           maxConns: 20
           maxIdleConns: 20
       visibility:                    # in memory, for trying it out only
         sql:
           pluginName: "sqlite"
           databaseName: "default"
           connectAddr: "localhost"
           connectProtocol: "tcp"
           connectAttributes:
             mode: "memory"
             cache: "private"
           maxConns: 1
           maxIdleConns: 1

   The plugin connects as the DSQL admin role with IAM tokens and ignores user and password. With tls.enabled alone the connection is encrypted but the server certificate isn't verified; enableHostVerification: true verifies it (#39). The plugin reads the region from REGION or AWS_REGION, and AWS credentials from the default credential chain.

4. Start the server:

   ./temporal-server --config-file <your-config>.yaml --allow-no-auth start

For production settings, see the deployment guide.

Documentation

• DSQL documentation index
• Deployment guide
• Implementation details
• Connection reservoir design
• Metrics reference

Releases

There are no releases yet. Build from source as shown above.

Contributing

Open issues and pull requests in this repository, not in temporalio/temporal. main is protected, so every change goes through a pull request, including merges from upstream.

Built with Claude Code

This project is developed with Claude Code, Anthropic's agentic coding tool, and its contributions are a big part of how the project moves forward.

Work done with Claude Code is credited in the history. Its commits carry a Co-Authored-By: Claude … <noreply@anthropic.com> trailer, and its pull requests end with a "Generated with Claude Code" line. To learn more, see the Claude Code documentation.

License

MIT, the same as upstream Temporal. See LICENSE.