Local Dev and CI with dev-local

With Datomic dev-local you can develop and test applications with minimal connectivity and setup. Get the dev-local library, add it to your classpath, and you have full access to the Client API (both synchronous and asynchronous flavors). This allows you to:

• Develop and test Datomic Cloud applications without connecting to a server and without changing your application code.
• Create small, single-process Datomic applications and libraries.

Dev-local is available at no cost. Note that dev-local is not redistributable. If you make Datomic apps/libs for others to use they must get a copy of dev-local themselves.

Get the latest version (0.9.184) of dev-local and unzip it. From the unzip directory, install dev-local in your local repository with:

mvn org.apache.maven.plugins:maven-install-plugin:3.0.0-M1:install-file -Dfile=dev-local-0.9.184.jar

By default, dev-local stores all databases under a common storage directory. To specify this directory, create a .datomic/dev-local.edn file in your home directory, containing a map with :storage-dir and an absolute path:

{:storage-dir "/full/path/to/where/you/want/data"}

There are two steps to use dev-local: add the dev-local library to your classpath and create a local client.

To add dev-local to your classpath, add a com.datomic/dev-local entry to your deps.edn file.

{com.datomic/dev-local
 {:mvn/version "<dev-local-version>"}}

The dev-local dependency is all you need for using dev-local.

If you intend to use dev-local in a system that also uses Datomic Cloud (i.e. using import-cloud or divert-system), you must also include the Datomic client-cloud dependency in your project.

There are two ways to get a local client:

• you can explicitly request a local client
• you can divert requests for Datomic Cloud clients to use local storage for development and testing

To explicitly request a local client, pass a map to d/client with

• :server-type :dev-local
• a :system name,

(require '[datomic.client.api :as d])
(def client (d/client {:server-type :dev-local
                       :system "dev"}))

To divert an existing Datomic Cloud system to dev-local, call divert-system:

(require '[datomic.dev-local :as dl])
(dl/divert-system {:system "production"})

;; existing requests for Cloud system will be served locally!
(def client (d/client {:system "production"
                       :server-type :ion
                       :region "us-east-1"
                       :endpoint "http://entry.production.us-east-1.datomic.net:8182/"}))

You can also use import-cloud to import data from Datomic Cloud to local storage.

If you are new to Datomic, you can now work through the tutorial.

dev-local stores data to your local filesystem, in directories under the :system you specify when creating a dev-local client.

Each database will store transactions in a directory named <storage-dir>/<system-name>/<database-name>. You can "backup" or "restore" a dev-local database simply by copying the database directory.

Most usage of dev-local should be via portable Client API calls. Capabilities that are specific to dev-local are available through the datomic.dev-local namespace:

• divert-system to develop and test Datomic Cloud applications against dev-local
• release-db to release memory used by a database
• import-cloud to import a Cloud database for dev-local use

All dev-local API calls take a single arg-map argument.

(import-cloud arg-map)
(divert-system arg-map)
(release-db arg-map)

• dev-local is in-process with your application code, and has all the tradeoffs (vs. a server or cluster) that this implies.
• dev-local requires 32 bytes of JVM heap per datom. You should plan your application with this in mind, while also leaving memory for your application's use.
• dev-local relies on OS page caching for performance, so leave some RAM available (i.e. not allocated to JVM heap) for this.

dev-local is best suited for small, single process applications. For larger projects, create a Datomic Cloud system.