Local Dev Setup

Datomic is a distributed system. Storage services, transactors, peers, peer servers, and clients are designed so that load on one process has minimal impact on other processes (while delivering on Datomic's semantic promises).

As a convenience for development, you can 'undistribute' Datomic by running more than one process on the same virtual or physical hardware, e.g. running storage, transactor, and peer on a developer laptop.

Please note that 'development mode' cannot deliver the reliability or performance of a production deployment, as processes are competing for a single resource (the machine), and a single machine failure brings all processes down.

The steps for running a local 'development mode' of Datomic include:

NOTE: All steps in this process assume you're running commands from the root of the unzipped Datomic distribution.

Running a local Transactor

The dev storage protocol uses local disk files for storage and requires a Datomic Starter or Datomic Pro license. Datomic Starter is free to download and use, but does require that you register by creating an account at My Datomic.

Once you have a Datomic Starter or Pro license key, you need to configure a transactor.properties file:

Copy config/samples/dev-transactor-templates.properties somewhere locally and edit it with the text editor of your choice. Paste in the license key from the email sent to you via My Datomic: NOTE: The license key is only provided via email and is not the same as the download key shown on the my.datomic.com Dashboard.

license-key=<INSERT HERE>

You can start a local transactor with dev storage from your system shell as follows:

bin/transactor path/to/dev-transactor-template.properties

This script will print a few lines of output, including the base URI you will use to connect, e.g.

datomic:dev://localhost:4334/<DB-NAME>

To create a connection string, simply replace <DB-NAME> with a database name of your choice, e.g. "hello":

datomic:dev://localhost:4334/hello

The Transactor process will be used for the subsequent steps in this guide.

Creating a database

In a separate terminal instance, use the Clojure REPL included with the Datomic distribution to create a database in the local dev storage.

First, start a Clojure REPL that includes the Datomic Peer library in the classpath:

bin/repl

Using the Datomic Peer API, create a database. This example uses the connection string from the previous section:

(require '[datomic.api :as d])
(def db-uri "datomic:dev://localhost:4334/hello")
(d/create-database db-uri)

Once you've created the database, you can interact with it via the Datomic Peer or Client Libraries.

Using the Datomic Peer Library

Once you have created a database, you can use the Datomic Peer Library to interact with it.

In the same REPL you used to create your database run:

(def conn (d/connect db-uri))

Doing this will connect you to the transactor. Any transactions submitted to the connection will be persisted to your local file system.

For example:

@(d/transact conn [{:db/doc "Hello world"}])

Adds a new entity with the :db/doc value "Hello world".

You can close the Clojure REPL with Ctrl+D

In addition to using the included REPL, you can include the Datomic Peer Library in your Java or Clojure project.

Starting a Peer Server

The Datomic Peer Server does not create durable-storage databases itself. To use a Peer Server along with a dev storage database you will need to have previously created a database and have a running dev Transactor. If you haven't yet created a database, follow the Create a database instructions prior to starting the Peer Server. If you haven't yet started a Transactor, follow the Run a Transactor instructions prior to starting the Peer Server.

The Datomic Peer Server provides an interface for Datomic clients to access databases. The Peer Server communicates with storage and the Transactor to service both reads from and writes to Datomic databases.

In a separate terminal instance run:

bin/run -m datomic.peer-server -h localhost -p 8998 -a myaccesskey,mysecret -d hello,datomic:dev://localhost:4334/hello

To start a Peer Server at localhost, port 8998 serving the hello database from dev storage as "hello" with the access key "myaccesskey" and the secret "mysecret".

More details on configuration and options can be found on the Peer Server documentation page.

Using the Datomic Client Library

The Datomic Client Library communicates with a Peer Server. If you have not yet started a Peer Server, follow the Starting a Peer Server section prior to attempting to connect a Datomic Client.

In a separate terminal instance start a Clojure REPL that includes the Datomic Client library in the classpath (or if you're following this document from top to bottom, you can use the REPL from the Peer section):

bin/repl

Import the Datomic Client library and Clojure core.async:

(require '[clojure.core.async :refer (<!!)]
         '[datomic.client :as client])

Now, connect to the database by calling connect, the access-key/secret pair must match with one used to launch the Peer Server:

(def conn
 (<!! (client/connect
       {:db-name "hello"
       :account-id client/PRO_ACCOUNT
       :secret "mysecret"
       :region "none"
       :endpoint "localhost:8998"
       :service "peer-server"
       :access-key "myaccesskey"})))

Doing this will connect you to the transactor. Any transactions submitted to the connection will be persisted to your local file system.

For example:

(<!! (client/transact conn {:tx-data [{:db/doc "hello world"}]}))

Will create a new entity with the doc string "hello world".

You can close the Clojure REPL with Ctrl+D

The Tutorial provides further examples of using the Datomic Client library.

In addition to using the included REPL, you can include the Datomic Client Library in your Clojure project.

Starting Datomic Console

The Datomic Console is a graphical UI that can be used to explore databases and generate queries.

Running Console against a dev storage-backed database requires a running Transactor. If you haven't yet started a transactor, follow the instructions at Running a local Transactor prior to starting Console.

In a separate terminal instance run:

bin/console -p 8080 dev datomic:dev://localhost:4334/

To start the Console web service on port 8080 against the local dev storage.

When the Console starts, it prints a URL to browse to, typically http://localhost:8080/browse/. Open this URL in a web browser to start using the Console.

The Console process can be terminated with Ctrl+C

More details on running and using Console can be found in the Datomic Console documentation page.

Next Steps

Now that you have configured a project to use Datomic and experimented with some basic database operations, you are ready to work through the training course for a thorough introduction to Datomic's fundamentals.