Ions

Ions let you develop applications for the cloud by deploying your code to a running Datomic cluster. You can focus on your application logic, writing ordinary Clojure functions, and the ion tooling and infrastructure handles the deployment and execution details. You can leverage your code both inside Datomic transactions and queries, and from the world at large via built-in support for AWS Lambda.

There are four activities involved in using Datomic Ions:

  • dev - Write your application as a set of Clojure functions in a tools.deps based project. Keep it in a git repo.
  • push - Capture your current local view of the world as a revision you can later deploy.
  • deploy - Get a revision running on a Datomic cluster, including all associated Lambdas.
  • bond - Use the functions you have deployed in transactions and queries. If your application includes Lambdas, connect those Lambdas to various AWS events or to AWS API Gateway for web app support.

Benefits

  • Focus on your application
  • Leverage your Datomic Cloud cluster compute resources and data locality
  • Extend Datomic transactions and queries with your own logic
  • Connect to the broader AWS cloud via Lambda events
  • Service web consumers with API Gateway
  • Scale Datomic and your app together
  • Deliver on AWS with high agility

../images/ions-who-do.png

Activities

dev

A Datomic Ions application is an ordinary tools.deps based Clojure project kept in git. You can have dependencies, including local deps of libs in progress. The project must include datomic.ions.dev as a dev-time dependency. In addition, you must include a datomic/ion-config.edn file in the classpath, which specifies the application name and an :allow list of namespace-qualified functions to which bindings are allowed. You also configure functions you wish to expose as Lambdas.

Datomic Cloud manages a Code Deploy application for every compute group you launch. The :app-name in your ion-config.edn connects your code to the named Code Deploy application.

push

You capture the current state of your application code by invoking datomic.ion.dev push. push creates a named CodeDeploy revision in Amazon S3, which you can later deploy to one or more Datomic query groups. If you are working on committed code with no local deps you will get a stable revision named after your commit. Otherwise, you will have to supply a name for your (unreproducible) revision.

push reads through your deps.edn and ensures all library dependencies and local code are moved to S3. In addition, it creates a first-class revision in Code Deploy. push is smart about minimizing the transfer of code to S3.

deploy

You get a revision you have previously pushed running on a particular Datomic query group by invoking datomic.ion.dev deploy. You will need to supply the name of the revision and the name of the target group. Datomic Cloud manages a Code Deploy deployment group for each query group you launch, with a name matching the CF template for that group.

deploy uses AWS Step Functions to:

  • deploy your code and dependencies to the query group using Code Deploy
    Code Deploy works by moving code from S3 to the query group's EC2 instances and cycling the Datomic process with a newly-extended classpath, in a rolling fashion. This is much faster than cycling EC2 instances. deploy is smart about minimizing the transfer of code from S3.
  • [optionally] ensure Lambdas
    If you've configured Lambdas, deploy ensures a Lambda corresponding to each lambda-enabled function. These lambdas are in fact just lightweight proxies that forward invocations to your functions running on the Datomic cluster (i.e. your code is not running in AWS Lambda). In this way your code runs near the data and cache, and without the limitations and complexities of running in the Lambda execution context.

    You can monitor the progress of deploy with datomic.ion.dev deploy-status

bond

You can use any fn listed in the :allow list of ion-config.edn as a transaction function or query expression. Datomic will automatically require the corresponding namespace if needed.

If you've configured some fns to be exposed as lambdas they will be named $(group-name)_$(lambda-name). You can:

  • Invoke the lambdas directly
  • Put a lambda behind the AWS API Gateway
    An ion fn can be an entire webapp, with API Gateway handling the exposure to the internet. The datomic.ion library includes helpers for getting to/from the API Gateway's JSON format and ring-like edn handlers.

    For more information, see the tutorial and reference.