Using XTDB from Clojure

Clojure users can execute SQL queries using standard JDBC tooling, via XTDB’s PostgreSQL wire-compatible server. Additionally, there is an XTDB Clojure API for both SQL and XTQL queries.

JDBC

SQL queries can be executed using the PostgreSQL JDBC driver:

{:deps {org.postgresql/postgresql {:mvn/version "42.7.4"}

        ;; other JDBC/Postgres libraries are available
        com.github.seancorfield/next.jdbc {:mvn/version "1.3.939"}}}

Then, once you’ve started the XTDB node, follow the usual Clojure JDBC process for connecting to a PostgreSQL database:

(require '[next.jdbc :as jdbc])

(def db
  {:dbtype "postgresql"
   :dbname "xtdb"
   :user "xtdb"
   :password "xtdb"
   :host "localhost"
   :port 5432})

;; this is relatively low-level code - the usual connection pooling
;; and SQL abstraction libraries can be used too.

(with-open [conn (jdbc/get-connection db)]
  (jdbc/execute! conn ["INSERT INTO users RECORDS {_id: 'jms', name: 'James'}, {_id: 'joe', name: 'Joe'}"])

  (prn (jdbc/execute! conn ["SELECT * FROM users"])))

;; => [{:_id "joe", :name "Joe"}
;;     {:_id "jms", :name "James"}]

Clojure API

API documentation

The XTDB Clojure API supports both SQL and XTQL queries. You can run XTDB nodes either in-process, or connect to a remote XTDB server via an (internal) HTTP API.

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

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

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

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

 ;; 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.

Remote node

First, ensure you’ve included the xtdb-http-client-jvm library in your dependencies. Once your XTDB server is running, you then can connect to it with the following code:

(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 21+ and then add the xtdb-core library 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.