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.

Throughout this tutorial, shell commands are run from the root directory of the Datomic distribution.

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 to the same directory, the root of the unzipped Datomic distribution.

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

bin/repl

Once the REPL is running, you have to import the Client library and core.async, in particular, the <!! core.async function (more on that later).

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

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 conn
 (<!! (client/connect
       {:db-name "hello"
        :account-id client/PRO_ACCOUNT
        :secret "mysecret"
        :region "none"
        :endpoint "localhost:8998"
        :service "peer-server"
        :access-key "myaccesskey"})))
#'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
object[datomic.client.impl.types.Connection 0x2b148329 "#datomic.client.impl.types.Connection[{
    :t 63, 
    :next-t 1000, 
    :account-id \"00000000-0000-0000-0000-000000000000\", 
    :db-name \"hello\", 
    :db-id \"58a4663b-fad3-41a7-b581-dcc7c48dd9a3\", 
    :timeout 60000}]"]
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.

NOTE: About Asynchrony

The Datomic Client is fully asynchronous. As you go through this tutorial, you will use the core.async blocking take function (<!!), which waits for the channel to provide the desired value and returns that.

Do not forget to use the <!! operator to retrieve return values from channels returned by Datomic Client library functions.

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