Query Groups

Datomic provides an AWS CloudFormation template for creating a query group that extends a production topology Datomic system.

After you plan your system, you can use the instructions on this page to:

1 Creating a Query Group

1.1 Prerequisites

Note: Query groups extend an existing system. Before launching a query group, you must launch a production topology system running release 441 or later.

1.2 "Select Template" Screen

Follow these steps to create a query group using the Datomic template.

  1. Go to the CloudFormation console
  2. Click the Create Stack button
  3. Under Choose a Template, select the Specify an Amazon S3 template URL option
  4. Paste the Query Group template URL from the current releases page in the input box

1.3 "Specify Details" Screen

Fill in the template's parameter value as specified below.

Stack Name
Choose a name for this query group. Use only lowercase letters, numbers, and hyphens. Your system name gets concatenated in various contexts and so should be kept short, e.g. fewer than 24 characters.
Existing System Name
Enter the name of your existing production system.
Instance Type
Choose the EC2 Instance Type of the query group nodes.
AWS EC2 Key Pair
The key pair to assign to cluster nodes. Select a key pair for ssh access to nodes.
Environment Map
Ion #environment map.
Application Name
Select the name of the application that will deploy to this group. This cannot be changed later! See planning your system for guidance.
Desired capacity
The desired capacity for the query group Auto Scaling group.
Minimum query group instances
The minimum size of the Auto Scaling group.
Maximum query group instances
The maximum size of the query group Auto Scaling group
Minimum number of query group instances during update
Specifies the minimum number of instances that must be in service within the query group Auto Scaling group while AWS CloudFormation updates instances.
Existing IAM managed policy for node
(Optional) Specifies the name of a to assign to instance nodes
Environment Map
Ion environment map.
Preload Database
All query group instances will load this database when they start.

1.4 "Options" Screen

  1. Leave the default settings
  2. Click the Next button.

1.5 "Review" Screen

  1. Under Capabilities, click the checkbox stating "I acknowledge that AWS CloudFormation might create IAM resources with custom names."
  2. Click Create

1.6 Verify that the Stack Launched Correctly

Find your stack in the CloudFormation window and click the checkbox at the start of its row. Watch the Events tab until it shows CREATE_COMPLETE for the resource Type "AWS::CloudFormation::Stack." This can take several minutes.

2 Connecting to a Query Group

The arg-map of a client for a query group requires the endpoint of the query group.

(require '[datomic.client.api :as d])

(def cfg {:server-type :ion
          :region "<your AWS Region>" ;; e.g. us-east-1
          :system "<system-name>"
          :endpoint "http://entry.<query-group-name>.<region>.datomic.net:8182/"
          :proxy-port <local-port for SSH tunnel to access gateway>})

(def client (d/client cfg))

3 Updating a Query Group

You can upgrade a query group stack for one (or both) of the following purposes:

  • You can upgrade a query group stack to change a query group's configuration, while leaving the template itself unchanged. This allows you to update the characteristics of a query group, for instance the instance type or the number of instances the query group is running, and Cloudformation will manage the update for you.
  • You can upgrade to a different version of Datomic Cloud.

Note: The "Existing System Name" and "Application Name" parameters cannot be changed this way. If you want to change these parameters, you must delete the query group and recreate the query group.

To update a query group stack:

  • Click the name of your query group stack in the CloudFormation console.
  • On the Stack page, Click "Update Stack".
  • On the "Select Template" screen, choose "Use current template", click Next.
  • On the "Specify Details" screen, change your parameter(s), click Next.
  • On the "Options" screen, leave all options unchanged, click Next.
  • On the "Review" screen, click the checkbox stating "I acknowledge that AWS CloudFormation might create IAM resources with custom names."

You can then preview the changes that this update stack operation is going to make. Click Update when you are ready to apply them. Cloudformation will then apply the changes to the stack, and you can monitor the Events tab in the Cloudformation console to see the status of the stack. The update is complete when the Events tab shows UPDATE_COMPLETE for the resource Type "AWS::CloudFormation::Stack."

4 Deleting a Query Group

NOTE Deleting a query group does not delete your Datomic system or any data!

To delete a Datomic query group:

  1. Go to the CloudFormation console.
  2. Find your stack on the list of stacks.
  3. Right-click on your query group stack and select "Delete Stack".