Getting Started

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

  • install and configure Datomic's prerequisites
  • connect to the memory database
  • submit a transaction
  • issue a query
  • connect to the free database

Install and configure Datomic's prerequisites

Datomic requires the Java JDK to be installed. The environment variable JAVA_HOME must be set to point to the location where the JDK is installed. To set JAVA_HOME in Unix-like environments with a bash-like shell:

export JAVA_HOME=/path/to/jdk

To set JAVA_HOME in Windows:

  1. On your Windows desktop, right-click My Computer and select Properties.
  2. Click the Advanced tab (Windows 7 users then click Advanced System Settings) and then click Environment Variables.
  3. In the System variables area click "New…".
  4. Enter JAVA_HOME in the Variable name field. Enter the pathname of the JDK installation directory in the Variable value field. Click OK.
  5. Click OK.

Finally, update your environment's PATH to include the JDK-provided executables. To set the PATH in Unix-like environments with a bash-like shell:

export PATH=$JAVA_HOME/bin:$PATH

To set the PATH in Windows:

  1. On your Windows desktop, right-click My Computer and select Properties.
  2. Click the Advanced tab (Windows 7 users then click Advanced System Settings) and then click Environment Variables.
  3. In the System variables area, select Path and click "Edit…".
  4. Enter %JAVA_HOME%\bin; as the first semicolon-delimited entry in the Variable name field, being careful to preserve all the existing entries! Click OK.
  5. Click OK.

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, which you can download here.

After you download Datomic, unzip it and navigate to the root directory. From there, run the Datomic Shell:

bin/shell

You should see the Datomic Shell prompt:

Datomic Shell
Type Shell.help(); for help.

datomic %

Create a memory database by calling Peer.createDatabase:

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 = Util.list("db/add",
                  Peer.tempid("db.part/user"),
                  "db/doc",
                  "hello world");
resp = conn.transact(Util.list(datom));

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 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 free storage protocol (following the instructions below), or (2) jump straight into the tutorial, and come back to the transactor later.

Running the transactor with the free storage protocol

The free storage protocol uses local disk files for storage.

You can start a local transactor with free storage as follows:

bin/transactor config/samples/free-transactor-template.properties

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

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

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

datomic:free://localhost:4334/hello

Using this URI, you should now be able to repeat the steps from the previous section, this time making your connection to the transactor.

Next Steps

Now that you have verified that you can connect to the memory database and to the transactor, you are ready to work through the tutorial.