Peer Server

The Peer Server is a JVM process that provides an interface for the Datomic Client library:

• It accepts queries and transactions from Datomic Clients
• Submits transactions to, and accepts changes from, the transactor
• Provides data access, caching, and query capability to connected Clients, reading from the storage service as needed

The Datomic Peer Server is a JVM process that provides an interface for the Datomic Client Library. The Peer Server provides a gateway to the database, submitting transactions and accepting changes from the transactor. Like the Peer Library, the Peer Server provides caching and query capability for connected Datomic Clients.

The Client library requires that one or more Peer Servers be running. Peer servers are special intermediate nodes that handle queries and caching. Peer servers can be scaled horizontally just like Peers. Clients have a network hop for read operations as the queries are sent to Peer Servers. The Client library is much lighter weight than the Peer library at the cost of increasing latency on reads.

A 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. As such, the system running the Peer Server must have appropriate permissions to access storage, as specified in the storage documentation.

The Peer Server must also be able to connect to the live Transactor at the location specified by the host property in the transactor properties file. For more information on the connection between the peer server and the transactor, see the deployment documentation.

Note that Peer Servers do not own databases. As such, the Peer Server cannot create or destroy a database.

You can launch a Peer Server for one or more databases with the peer-server command:

bin/run -m datomic.peer-server\
        -h host\
        -p port\ 
        -a access-key,secret\
        -d dbname,URI\

• The access-key and secret are opaque strings. Clients must provide

a matching access-key and secret to connect.

• A dbname can consist of alphanumeric characters plus the hyphen '-'.
• The -d option may be passed multiple times to serve multiple

databases from a single peer server.

• The -a option may be passed multiple times to allow multiple access

keys and secrets, e.g. to support a key rotation scheme.

The database-uri is described in the documentation for connect, e.g.

datomic:ddb://us-east-1/my-datomic-table/my-db

As a development convenience, a peer server can also serve transient, memory-only databases by passing a mem URI to the peer server command.

To connect to a Peer Server, call connect, passing a client created with the arguments used to create the peer server:

• Peer server host:port for :endpoint
• Peer server secret for :secret
• Peer server access-key for :access-key

Along with the other connect hard-coded arguments shown in the example below:

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

(def client
  (d/client
   {:server-type :peer-server
    :endpoint "localhost:8998"
    :secret "my-secret"
    :access-key "my-access-key"
    :validate-hostnames false}))

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

The connection between clients and the peer server does not support SSL hostname validation. Both should be run within trusted network boundaries.

The use of iteration in the Client API (i.e. taking from a query or datoms result channel repeatedly) requires that the client communicate with the same Peer Server instance that served the original request. In a system with multiple Peer Servers behind a load balancer we recommend you enable sticky sessions to ensure iterative requests are routed to the same Peer Server instance. If sticky sessions are unavailable, it is also possible to handle chunking and iteration manually using the :limit and :offset arguments.