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.

Datomic dev-local is part of Cognitect dev-tools. Get the latest version of dev-tools and unzip it.

dev-local can be acquired via maven or tools.deps by following the instructions e-mailed to you when you requested the latest version.

To install the downloaded jar locally: install dev-local with the install script from the zip directory:

./install

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 "0.9.232"}}

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

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"}))

If you are using dev-local to develop and test a Datomic Cloud application, add the client-cloud dependency to your project. Then, 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.

Sometimes durable storage is unnecessary and/or inconvenient. For example, a CI system may have no need of data after the tests run and no access to a file system.

You can force dev-local to use a memory-only database by passing :storage-dir :mem to the map you pass when creating a client, as shown in the example below:

(def client (d/client {:server-type :dev-local
                       :storage-dir :mem
                       :system "ci"}))

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 limits the total number of datoms in a transaction to 10⁵.
• dev-local limits strings to 4096 characters.

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