Skip to content
XTDB

Getting started (Clojure)

In Clojure, you can access XTDB via a remote HTTP client, or in-process (e.g. for testing purposes).

Maven artifacts

The XTDB artifacts for each release are deployed to Maven Central:

deps.edn
;; currently only on the Maven Central 'open-source software repo hosting' (OSSRH) snapshots repo
{:mvn/repos {"ossrh-snapshots" {:url "https://s01.oss.sonatype.org/content/repositories/snapshots"}}

 :deps {org.clojure/clojure {:mvn/version "1.11.1"}

        ;; xtdb-api for the main public API, for both remote-client and in-process nodes
        com.xtdb/xtdb-api {:mvn/version "2.0.0-SNAPSHOT"}

        ;; xtdb-http-client-jvm for connecting to a remote server
        com.xtdb/xtdb-http-client-jvm {:mvn/version "2.0.0-SNAPSHOT"}

        ;; xtdb-core for running an in-process (test) node (JDK 17+)
        com.xtdb/xtdb-core {:mvn/version "2.0.0-SNAPSHOT"}}

 ;; JVM options required for in-process node
 :aliases {:xtdb {:jvm-opts ["--add-opens=java.base/java.nio=ALL-UNNAMED"
                             "-Dio.netty.tryReflectionSetAccessible=true"]}}}

For Maven (pom.xml) or Gradle (build.gradle.kts), see the Java getting-started guide.

Connecting through HTTP

  1. Firstly, to run the XTDB server, check out the general getting started guide.

  2. Then, add the thin client Maven coordinates to your dependency manager of choice.

  3. Once you have a REPL (e.g. by running clj), you can connect to the XTDB node with:

    (require '[xtdb.client :as xtc]
         '[xtdb.api :as xt])

(with-open [node (xtc/start-client "http://localhost:3000")]
  (xt/status node)

  ;; ...
  )

From here, check out the xtdb.api API docs to submit data and run queries.

In process

If you’re running a JVM, you can also use XTDB directly, in-process. In-process XTDB is particularly useful for testing and interactive development - you can start an in-memory node quickly and with little hassle, which makes it a great tool for unit tests and REPL experimentation.

  1. First, ensure you are running JDK 17+ and then add the xtdb-core Maven coordinates to your dependency manager.

  2. You’ll also need to add the following JVM arguments to run Apache Arrow (included in the :xtdb deps.edn alias above):

    • --add-opens=java.base/java.nio=ALL-UNNAMED

    • -Dio.netty.tryReflectionSetAccessible=true

  3. Once you have a REPL (started with clj -A:xtdb this time), you can create an in-memory XTDB node with:

(require '[xtdb.node :as xtn]
         '[xtdb.api :as xt])

(with-open [node (xtn/start-node {})]
  (xt/status node)

  ;; ...
  )

This node uses exactly the same API as the thin client - so, again, from here, check out the xtdb.api API docs to submit data and run queries.