Getting Started

This guide will get you up and running with Datomic in minutes. You will see how to:

Install Datomic

You can find steps for downloading Datomic at Get Datomic. For getting started, Datomic Pro Starter is recommended. Datomic Pro Starter is free to download and use, but does require that you register by creating an account at My Datomic first. Datomic requires either the Java 7 JDK or Java 8 JDK.

Once you've downloaded Datomic, unzip it somewhere locally and look at its contents. Note the contents of the bin and config directories.

  • The bin directory contains executables for launching Datomic repls, installing the peer library locally, running a transactor, etc. It also contains scripts to configure storage.
  • config/samples contains sample transactor.properties files. You will need a transactor.properties file configured for your system and storage in order to launch a transactor.

For the following steps, we'll give directions for launching commands that must be called from the Datomic root directory. This will be the version and edition qualified directory name. You will need to cd to this directory now, e.g.:

cd /home/user/datomic/datomic-pro-0.9.5067

Project Setup

Below are steps for configuring Maven and Leiningen to use the Datomic Pro Peer library. Datomic Pro dependencies are not available through Maven central. You will need to configure your project or global Maven/Leiningen settings to point to the private Datomic Pro repository or install the Datomic Pro dependency locally.

If you want Maven and Leiningen to download the Datomic Pro Peer library you will need username and password credentials. Your username and password credentials are available at My Datomic.

For local dev testing, you can install the peer library to your local maven repository by running:

bin/maven-install

After doing so, you will be able to add the peer library dependency for that version to your Maven or Leiningen project. If you opt to do this for your initial Datomic setup, you can skip the repository configuration steps below for the time being.

Maven Setup

You can add the maven dependency for the Datomic peer library as follows inside the <dependencies> block of your pom.xml file as:

<dependency>
  <groupId>com.datomic</groupId>
  <artifactId>datomic-pro</artifactId>
  <version>0.9.5067</version>
</dependency>

In order to download this dependency, you will need to configure your global Maven server settings as well as your project's pom.xml to point to my.datomic.com as follows:

<!-- ~/.m2/settings.xml-->
  <servers>
    …
    <server>
      <id>my.datomic.com</id>
      <username>USERNAME</username>
      <password>PASSWORD</password>
    </server>
    …
  </servers>

and:

<!-- pom.xml -->
  <repositories>
    …
    <repository>
      <id>my.datomic.com</id>
      <url>https://my.datomic.com/repo</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <releases>
        <enabled>true</enabled>
      </releases>
    </repository>
    …
  </repositories>

Leiningen Setup

To access the peer library from Leiningen you will need to add a dependency to your project.clj file:

:dependencies [...
               [com.datomic/datomic-pro "0.9.5067"]
              ...]

To download the Datomic Pro peer library dependency, you will need to configure your global Leiningen settings to include your my.datomic.com credentials. This will also require that you configure Leiningen for private repository authentication. Instructions for doing so can be found here.

;; ~/.lein/credentials.clj.gpg
{#"my\.datomic\.com" {:username "USERNAME"
                      :password "PASSWORD"}}

You will also need to configure your project to use this repository:

;; project.clj
:repositories {"my.datomic.com" {:url "https://my.datomic.com/repo"
                                 :creds :gpg}}

Connecting to the memory database

The memory database is an in-memory implementation of the entire Datomic stack (minus durability). It is suitable for experimentation and testing. The memory system is included in the Datomic peer library.

The following workflow uses the memory database from the Groovy shell. You can start the Groovy shell from the Datomic root directory with:

bin/groovysh

You should see the Datomic Groovy Shell prompt:

Groovy shell (1.8.9, JVM: 1.7.0_60)
Type 'help' or '\h' for help.
-----------------------------------
groovy:000>

You can exit the Datomic Groovy Shell with exit or Ctrl+D.

You can also run a Java shell or Clojure REPL using:

bin/shell # Java (BeanShell), exit with "exit();"
bin/repl  # Clojure, exit with "(System/exit 0)"

Import the Datomic Peer library:

import datomic.Peer

Create a memory database by calling Peer.createDatabase. You will need to define a database URI to connect to that will include the storage protocol.

uri = "datomic:mem://hello"
Peer.createDatabase(uri)

Now, connect to the database by calling Peer.connect:

conn = Peer.connect(uri)

Next, add a fact to the system. The following transaction will create a new entity with the doc string "hello world":

datom = ["db/add", Peer.tempid("db.part/user"),
         "db/doc", "hello world"]
resp = conn.transact([datom])

The form of the above datom definition in natural language is:

datom = ["add fact" "about a new entity with this temporary id"
         "assert that the attribute db/doc" "has the value hello world"]

Now you can query for the fact you just created. Queries are not against a connection, but against an immutable value of the database. Call the db method to get the current value of the database:

db = conn.db()

The following query will find all entities in the system with the doc string "hello world":

Peer.q("[:find ?entity :where [?entity :db/doc \"hello world\"]]",
       db)

The above query in natural language is:

["find" "entities" "where we specify entities as" 
["an entity" "has the attribute db/doc" "with value hello world"]]

The memory database and the transactor implement the same API, so you can use them interchangeably during development and testing. Now that you have a memory database up and running, you can either:

  1. set up a transactor using the dev storage protocol (following the instructions below)
  2. jump straight into the tutorial, and come back to the transactor later.

Running the transactor with the dev storage protocol

The dev storage protocol uses local disk files for storage. You will need to configure a transctor.properties file. Copy config/samples/dev-transactor-templates.properties somewhere locally and edit it with the text editor of your choice. You will need to paste in the license key sent to you from My Datomic:

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

You can repeat the connection/creation steps from the examples above with:

import datomic.Peer
uri = "datomic:dev://localhost:4334/hello"
Peer.createDatabase(uri)

Doing this will connect you to the transactor which will write to your local file system using the "dev" storage protocol.

Note: You can complete the steps above using Datomic Free, but will need to substitute "dev" with "free" for the above examples to work. You can also skip the steps for adding your license key.

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 tutorial.