Client Getting Started
Getting started with the Client Library is similar to Getting Started with Peer except for a few differences:
Once you have your development environment setup and have connected to a database.
Local Development Setup
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 usingmem
, 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:
Flag | Name | Value | Description |
---|---|---|---|
-h |
Host | localhost |
the hostname |
-p |
Port | 8998 |
the port to listen on |
-a |
Access key | myaccesskey |
an access key (you will this pass back to the Peer Server later to authenticate yourself) |
-a |
Secret | mysecret |
an secret (you will this pass back to the Peer Server later to authenticate yourself) |
-d |
storage | hello |
a URL describing what storage to use and a database name |
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.
Integrate Client Library
The Client library must be integrated in your project. Follow the instructions for your preferred project type
Follow the instructions until you have a running REPL.
Connect to a Database
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.
Connecting
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.
Transacting
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.