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
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 query 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
- Connect them to events from various AWS services
Your ion fns will be passed (and need to return) the JSON payloads as described for the corresponding service.
- 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.