Upgrading
Datomic Cloud is designed to minimize the upgrade effort, allowing rolling upgrades with zero downtime. To plan and implement an upgrade, you need to:
- Be running split CloudFormation stacks
- Know what version you are running
- Choose a release
- Perform the upgrade
In most situations, never downgrade Datomic.
Know What Version You Are Running
- Datomic Cloud releases have a version number of the form
[CloudFormation-revision]-[code-revision]
. - A Datomic system comprises one storage stack, plus a separate compute stack for each compute group, each with its own version
- A storage stack does not manage any code, and so its version information includes only a CloudFormation revision
- A compute stack has both a CloudFormation revision and a code revision
- All the stacks for a system should normally be running the same version of Datomic, but this is not mandatory and will not be the case during an upgrade
You can query the revisions for all stacks for a system from the CLI or inspect them in the AWS console:
From the CLI
- The
datomic cloud list-systems
command lists all systems, with the storage CloudFormation revision under thestorage-cft-version
key. - The
datomic system list-instances <system>
command lists all compute instances for a particular system. Each instance will have agroup-cft-version
key with the CloudFormation revision that launched the instance, and agroup-cloud-version
key with the code revision that the instance is currently running.
From the AWS Console
- Storage stacks have a CloudFormation revision number in the
DatomicCFTVersion
output - Compute stacks have a CloudFormation revision number in the
DatomicCFTVersion
output, and a code revision number in theDatomicCloudVersion
output
To view the outputs for a CloudFormation stack:
- Select the name of your system stack in the CloudFormation console
- Click on the outputs tab
Choose a Release
The releases page provides three resources that can help you decide when and how to upgrade:
- The critical notices section contains critical notices for all users. Always read this section.
- The release history table includes a summary column with a brief description of each release.
- The release notes provides a comprehensive list of changes in each release.
Do not downgrade to older versions of Datomic Cloud.
Perform an Upgrade
Before any upgrade, read the critical notices for all releases between your current release(s) and the release(s) you are upgrading to. These notices may override the generic instructions below.
The documentation for each release lists an upgrade type, Make sure you perform the correct type of upgrade, which can be one of:
Storage and Compute Upgrade
If both storage and compute are being upgraded:
- Upgrade storage first
- Then upgrade compute
Storage Upgrade
To update a Storage stack:
- Open the CloudFormation console
- Select your stack via the checkbox or radio button.
- Click the "Update" button.
- Select "Specify an Amazon S3 template URL" and enter the CloudFormation template URL for the version you wish to upgrade to (check the release page for all versions) then click "Next".
On the "Specify Details" screen, set the "Reuse Existing Storage" option to true:
- On the "Options" screen, leave all options unchanged.
- On the "Review" screen, click the checkbox stating "I acknowledge that AWS CloudFormation might create IAM resources with custom names" and click "Update".
Compute Upgrade
If you have more than one compute group, upgrade all of them. Upgrade the primary compute group first and then upgrade your query groups. It is ok to upgrade the query groups in parallel.
To update a Compute Stack:
- Open the CloudFormation console.
- Select your stack via the checkbox or radio button.
- Click the "Update" button.
- Select "Specify an Amazon S3 template URL:" and enter the CloudFormation template URL for the version that you wish to upgrade to (see Release page for all versions) then click "Next".
- On the "Specify Details" screen, leave all options unchanged.
- On the "Options" screen, leave all options unchanged.
- On the "Review" screen, click the mandatory checkboxes that you agree with.
Do Not Downgrade
Generally speaking, you should never downgrade Datomic CloudFormation templates.
- Newer versions are better: They may contain important fixes.
- Newer versions are compatible: They continue to support the entirety of the API.
- Older versions may be incapable of correctly handling newer features.
- Our support team is better able to help if you are running a recent version.
If you have a need to downgrade Datomic, please contact support first, and let the Datomic team advise you.