Connect to a Database

This tutorial requires Datomic Starter or Datomic Pro. If you do not yet have Datomic, please follow the steps in Get Datomic to register and download Datomic Starter.

To get started with Datomic, you need to first launch a Peer Server that you can connect to. When you launch the process, you need to tell it:

  • what port to listen on
  • an access key and a secret (both opaque strings that you will pass back to the Peer Server later to authenticate yourself)
  • a URL describing what storage to use and a database name

For now, you will use the "mem" storage, which stores the data in memory and does not persist beyond the life of the process. To launch the Peer Server, from the root of the Datomic directory, run:

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

When this step completes appropriately, your terminal will be locked to this Peer Server process. If you want to kill the Peer Server, you can either CTRL-C from this shell or kill the terminal window.  

NOTE: To follow further steps, you must open a second terminal window.

Once the Peer Server is running, you need to launch a REPL and set up to use the Client library.

Download Client Library

The Datomic Client library is provided via Maven Central. Create a new Clojure project and add the client library to your dependencies:

NOTE: The Datomic Client requires Clojure version 1.9 or later

Maven

To retrieve the Client library for a Maven project, add the following snippet inside the <dependencies> block of your pom.xml file:

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

Clojure CLI

To use the Client library from a Clojure CLI REPL, add the following to your deps.edn dependencies map:

com.datomic/client-pro {:mvn/version "0.8.14"}

Leiningen

To include the Client library in a Leiningen project, add the following snippet to your project.clj file:

;; in collection under :dependencies key
[com.datomic/client-pro "0.8.14"]

Start a Clojure REPL

Clojure CLI

Using the Clojure CLI, start a REPL by entering:

clj

in a terminal.

Leiningen

With Leiningen, enter:

lein repl

at the terminal.

Once the REPL is running, you have to import the Client library.

(require '[datomic.client.api :as d])

At this point, you have a running environment you can use to execute commands against Datomic.

To interact with Datomic, you must first create a connection.

When you connect, you must specify several important parameters:

  • :db-name is the database your Client code will be interacting with.
  • :endpoint is the host and port where Datomic is running and listening.
  • :secret and :access-key are two opaque strings that match similar tokens provided when launching Datomic (for this tutorial, they are set to "mysecret" and "myaccesskey", respectively).

You package up the parameters into a map and pass that into the call to connect and store the results in a var that you can pass into other Client library operations, like transact or query. Go ahead and connect by running the following code now:

user=> (def cfg {:server-type :peer-server
                 :access-key "myaccesskey"
                 :secret "mysecret"
                 :endpoint "localhost:8998"})
#'user/cfg
user=> (def client (d/client cfg))
#'user/client
(def conn (d/connect client {:db-name "hello"}))
#'user/conn
user=> 

You should see that a var was created called "conn" which is holding your database connection. You can inspect it:

user=> conn
{:db-name "hello", 
 :database-id "5a381758-6e47-4504-aa08-07067b5c241a", 
 :t 1008, 
 :next-t 1009, 
 :type :datomic.client/conn}
user=> 

This tells you that you have an available connection to the database called "hello" as well as a few other details which you will learn more about later. You can now use "conn" as an input to future commands.

The next step will be to define some schema for your new database.