Skip to content

Getting started

XTDB can run in-process (in a JVM), or through traditional client-server connections.

Client/Server

You can start an XTDB server using the 'standalone' Docker image:

docker pull ghcr.io/xtdb/xtdb-standalone-ea

docker run -tip 3000:3000 ghcr.io/xtdb/xtdb-standalone-ea

This starts a server on http://localhost:3000. By default, your data will be saved in a local directory in the Docker image, but you can also attach a host volume in the usual Docker way, to preserve your data on your host machine:

docker run \
  -tip 3000:3000 \
  -v /path/to/host/dir:/var/lib/xtdb \
  ghcr.io/xtdb/xtdb-standalone-ea

Connecting through HTTP

You can then connect to your XTDB server using cURL, or similar tools. For example, to check its status:

curl http://localhost:3000/status

To run your first query:

sql="SELECT t1.doc.foo[1]
     FROM (VALUES ({'foo':['Hello', 'world!']})) AS t1(doc)"; \
curl -X POST localhost:3000/query \
     -H "Content-Type: application/json" -H "Accept: application/jsonl" \
     -d "{\"query\": {\"sql\": \"${sql}\"}}"

From here, check out the HTTP OpenAPI docs to see what else is available.

Connecting from a client library

If you’re running on the JVM, you can use the JVM client library to connect to this node.

Clojure Clojure Clojure

For more details, check out the relevant instructions for your language:

In process (JVM)

If you’re running a JVM (17+), you can also use XTDB directly, in-process, using the same API interface as the remote client. 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.

Clojure Clojure Clojure

For more details, check out the relevant instructions for your language: