Client Getting Started

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.

The tutorial uses the mem storage option with Peer Server. A transactor does not need to be running when using mem, but a transactor must be running and connected to the storage when using other storages.

Navigate to the root of your Datomic distribution directory then run:

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

This starts a Peer Server with:

The tutorial will use the mem storage. mem stores the data in memory and does not persist beyond the life of the process.

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

The Peer Server process will lock the terminal will to this Peer Server process until the process is killed. CTRL-C will kill the process, or you can close the terminal window.

Continuing with the tutorial with client will require a running Peer Server.

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

The first step to interacting with Datomic via the Client API is creating a client with datomic.client.api/client.

Then create a connection with datomic.client.api/connect by passing in the client and a database name.

Creating a client requires 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. They are set to "mysecret" and "myaccesskey" in this tutorial.

datomic.client.api/client takes a map with your client configuration.

(def cfg {:server-type :peer-server
          :access-key "myaccesskey"
          :secret "mysecret"
          :endpoint "localhost:8998"
          :validate-hostnames false})

=> #'user/cfg

Create a client:

(def client (d/client cfg))

=> #'user/client

Create a connection with that client:

(def conn (d/connect client {:db-name "hello"}))

=> #'user/conn

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

conn

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

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 Client API connect takes a client object and a map with a key of :db-name the value of the database that you want to connect to.

(def cfg {:server-type :peer-server
	:access-key "myaccesskey"
	:secret "mysecret"
	:endpoint "localhost:8998"
	:validate-hostnames false})

=>
#+user/cfg

(def client (d/client cfg))

=>
#'user/client

(def conn (d/connect client {:db-name "hello"}))

=>
#'user/conn

Now your connection can be used similar to how it is in the Peer Getting Started.

The Client library's transact function takes the transaction data in a map under the key :tx-data.

movie-schema is defined in the Peer Getting Started section. Follow that guide, starting from "Transacting Schema" with these modifications to learn about using Client.

(d/transact conn {:tx-data movie-schema})

=>
{:db-before {:database-id "58a47389-f1ab-4d81-85b6-715cecde9bac", 
             :t 63, 
             :next-t 1000, 
             :history false}, 
 :db-after {:database-id "58a47389-f1ab-4d81-85b6-715cecde9bac", 
            :t 1000, 
            :next-t 1001, 
            :history false}, 
 :tx-data [ #datom[13194139534312 50 #inst "2017-02-15T15:28:31.174-00:00" 13194139534312 true] 
            #datom[63 10 :movie/title 13194139534312 true] 
            #datom[63 40 23 13194139534312 true] 
            #datom[63 41 35 13194139534312 true] 
            #datom[63 62 "The title of the movie" 13194139534312 true] 
            #datom[64 10 :movie/genre 13194139534312 true] 
            #datom[64 40 23 13194139534312 true] 
            #datom[64 41 35 13194139534312 true] 
            #datom[64 62 "The genre of the movie" 13194139534312 true] 
            #datom[65 10 :movie/release-year 13194139534312 true] 
            #datom[65 40 22 13194139534312 true] 
            #datom[65 41 35 13194139534312 true] 
            #datom[65 62 "The year the movie was released in theaters" 13194139534312 true] 
            #datom[0 13 65 13194139534312 true] 
            #datom[0 13 64 13194139534312 true] 
            #datom[0 13 63 13194139534312 true]], 
 :tempids {-9223301668109598144 63, -9223301668109598143 64, -9223301668109598142 65}}

This is in contrast to the Peer library. Peer's transact takes the tx-data directly and returns a future which must be clojure.core/derefed.

The rest of the Getting Started guide applies to the Client library with this difference in mind.