Ions Reference

Ions support the synchronous client API only. Ions do not support the use of asynchronous client or the peer api.

When you create a client with :ion server-type, Datomic will create a client based on where your code is running:

• If on a Cloud node, Datomic will ignore the rest of the argument map to client and create an in-memory ion client.
• Otherwise,Datomic will use the rest of the argument map to create a client as for the :cloud server-type.

This allows you to write code that connects from your development environment to a Cloud system for dev and testing, and that can then be deployed to a running system with no code change.

The following example shows how to create a client that connects through a local proxy port to the inventory-dev system in us-east-1 during development. When deployed as an ion, the same code will create an in-memory client on the system it is deployed to.

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

(def cfg {:server-type :ion
          :region "us-east-1"
          :system "inventory-dev"
          :endpoint "http://entry.inventory-dev.us-east-1.datomic.net:8182/"
          :proxy-port 8182})

(def client (d/client cfg))

Ion applications can include arbitrary Clojure code, but to be useful they must expose one or more entry points for callers. Ions support six kinds of entry points for different callers, each with a different function signature.

The datomic/ion-config.edn resource configures the application's entry points. ion-config is an edn map with the following keys:

• :app-name is string name of a Datomic application
• :allow is a vector of fully qualified symbols naming query or transaction functions. When you deploy an application, Datomic will automatically require all the namespaces mentioned under :allow.
• :xforms is a vector of fully qualified symbols naming functions for use in xform.
• :lambdas is a map configuring AWS Lambda entry points
• :http-direct is a map configuring an HTTP Direct entry point.

When developing and testing locally, it can be helpful to match the JVM settings that your code will run under in Datomic Cloud.

Datomic Cloud runs Java version 1.8.0.

Additionally all instances use the following flags:

-XX:+UseG1GC -XX:MaxGCPauseMillis=50 -Dclojure.spec.skip-macros=true

Because ions run on the same classpath as Datomic Cloud, it is possible for ion dependencies to conflict with Datomic's own dependencies. If this happens:

• Datomic's dependencies will be used.
• The return from push will warn you with a :dependency-conflicts map.
• You can add the :deps from the conflicts map to your local project so that you can test against the libraries used by Datomic Cloud.

The Datomic team works to keep Datomic's dependencies up-to-date. If you are unable to resolve a dependency conflict, please contact support.

By default, an ion push is reproducible, i.e. built entirely from artifacts in git or maven repositories. For a push to be reproducible, your git working tree must be clean, and your deps.edn project cannot include any local/root dependencies. A reproducible push is uniquely named by the SHA of its git commit.

In some situations, you may want to push code that Datomic does not know to be reproducible. For example:

• you are testing work-in-progress that does not have a git commit
• you are implementing your own approach to reproducibility

For these situations, ions permit an unreproducible push. Since an unreproducible push has no git SHA, you must specify an unrepro name (:uname).

You are responsible for making the uname unique within your org+region+app. If unames are not unique, ions will be unable to automatically roll back failed deploys.

To check the status of a deploy, call datomic.ion.dev with an :op of :deploy-status:

clojure -A:ion-dev '{:op :deploy-status (options)}'

Deploy Status returns the the Step Functions reference of the overall ion deploy and of the code deploy as a map:

{:deploy-status "SUCCEEDED"
 :code-deploy-status "SUCCEEDED"}

On success, both the overall ion deploy and Code Deploy status will eventually return with "SUCCEEDED"

You can monitor a deploy in near real-time from the Step Functions Console. Look for a state machine named datomic-$(group).

When you deploy an application with lambda ions, Datomic will create AWS Lambdas named:

$(group)-$(name)

where group is the :group key you used to invoke deploy, and name is the name under the :lambdas key in ion-config.edn.

The tutorial includes an example of invoking an ion Lambda via the AWS CLI.

If you deploy the same ion to different compute groups, your code may want to be conditional based on which group it is running in. You can discover your compute group at runtime with get-app-info, which takes no arguments, and returns a map that will include at least these keys:

• :app-name is your app-name
• :deployment-group is the name of your ion deployment group

For example, the following excerpt from deploy-monitor gets the app-name:

(get (ion/get-app-info) :app-name)

When running outside Datomic Cloud, get-app-info returns the value of the DATOMIC_APP_INFO_MAP environment variable, read as edn.

If you want to add your own per-compute-group configuration, you can create an environment map.

You create an environment map when you first create a compute group. For example, the environment map below specifies that a compute group is for a :staging deployment environment:

You can then retrieve the environment map at runtime with get-env, which takes no arguments, and returns the environment map.

For example, the following excerpt from deploy-monitor retrieves the deployment environment specified above:

(get (ion/get-env) :env)

You can set the environment map for local development via the DATOMIC_ENV_MAP environment variable. When running outside Datomic Cloud, get-env returns the value of DATOMIC_ENV_MAP, read as edn.

If you need to change the environment map for a running compute group, you can perform a CloudFormation parameter upgrade.

If you need more flexible lifecycle, or granular security, you can use parameters as described below.

• A parameter is a named slot known to application code that can be filled in with a specific parameter value at runtime.
• The AWS Systems Manager Parameter Store provides an implementation of parameters that supports an independent lifecycle, encryption for sensitive data, and IAM security over a hierarchical naming scheme.
• All Datomic cluster nodes have read permission on parameter store keys that begin with datomic-shared.
• The ion library provides get-params as a convenience for reading parameter store parameters.

The deploy-monitor sample application demonstrates using app-info, the environment map, and parameters together. First, the environment and app-info map are used to create a key prefix following the the naming convention:

/datomic-shared/(env)/(app-name)/

• datomic-shared is a prefix readable by all Datomic nodes
• env is taken from the environment map, and differentiates different environments for the same application, e.g. "ci" vs. "prod".
• app-name is the ion app-name.

Then, this prefix is used to name configuration keys in the parameter store. deploy-monitor needs four parameters:

• a Datomic database name
• a Slack channel
• two encrypted tokens for Slack

Given this convention, the following AWS CLI commands will create the parameters for the "prod" environment:

# actual parameter values not shown
aws ssm put-parameter --name /datomic-shared/prod/deploy-monitor/db-name --value $DB_NAME --type String
aws ssm put-parameter --name /datomic-shared/prod/deploy-monitor/channel --value $CHANNEL --type String
aws ssm put-parameter --name /datomic-shared/prod/deploy-monitor/bot-token --value $BOT_TOKEN --type SecureString
aws ssm put-parameter --name /datomic-shared/prod/deploy-monitor/verification-token --value $VERIFICATION_TOKEN --type SecureString

You could use similar commands to create parameters for additional environments.

At runtime, deploy-monitor uses get-app-info and get-env to load the information needed to create a Parameter Store path, and then reads all of its parameter values with get-params:

(def get-params
  "Returns the params under /datomic-shared/(env)/(app-name)/, where

env       value of get-env :env
app-name  value of get-app-info :app-name"
  (memoize
   #(let [app (or (get (ion/get-app-info) :app-name) (fail :app-name))
          env (or (get (ion/get-env) :env) (fail :env))]
      (ion/get-params {:path (str "/datomic-shared/" (name env) "/" app "/")}))))