Datalevin Installation

Datalevin can be installed with different methods, depending on how you plan to use it.

Platforms

Supported platforms are:

• Windows AMD64
• MacOS ARM64
• Linux AMD64
• Linux ARM64

Languages

Supported programming languages are:

• Java
• Javascript (Node.js)
• Python
• Clojure

See the language compatibility matrix for current API parity across these languages.

Clojure Library

The core of Datalevin is a JVM Clojure library with some native dependencies. In many cases, one can simply add it to your Clojure project as a dependency and start using it!

If you use Leiningen build tool, add this to the :dependencies section of your project.clj file:

[datalevin "0.10.18"]

If you use Clojure CLI and deps.edn, declare the dependency like so:

{:deps {datalevin/datalevin {:mvn/version "0.10.18"}}}

The above library is a full release that includes everything. For embedded-only use cases, a lean artifact is available that keeps the local APIs and datalevin.client and excludes the server, CLI, and babashka pod runtime code.

If you use Leiningen:

[org.datalevin/datalevin-embedded "0.10.18"]

If you use Clojure CLI:

{:deps {org.datalevin/datalevin-embedded {:mvn/version "0.10.18"}}}

This library supports Java 21 and above.

Java Library

Java users can use the Maven Central artifact org.datalevin:datalevin-java. It includes the Java API, Datalevin runtime, and bundled native Datalevin libraries for supported platforms. It requires Java 21 and above.

Maven:

<dependency>
  <groupId>org.datalevin</groupId>
  <artifactId>datalevin-java</artifactId>
  <version>0.10.18</version>
</dependency>

Gradle:

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.datalevin:datalevin-java:0.10.18")
}

To embed a Datalevin server in a Java process, add the server add-on artifact:

<dependency>
  <groupId>org.datalevin</groupId>
  <artifactId>datalevin-java-server</artifactId>
  <version>0.10.18</version>
</dependency>

datalevin-java-server depends on datalevin-java and provides datalevin.DatalevinServer for in-process server lifecycle management.

See the Java example for a Datalog quick start.

JavaScript Library

Node.js users can use the npm package datalevin-node. It vendors the shared Datalevin runtime jar, so normal usage does not require building Datalevin from source. It requires Node.js 20+ and Java 21+.

npm install datalevin-node

See the Node binding README for Datalog and KV examples.

Python Library

Python users can install the PyPI package datalevin. It vendors the shared Datalevin runtime jar, so normal usage does not require building Datalevin from source. It requires Python 3.10+ and Java 21+.

pip install datalevin

See the Python binding README for Datalog and KV examples.

Native Dependencies

If the native dependencies of Datalevin are not met, Datalevin may fail to load and report java.lang.UnsatisfiedLinkError.

Datalevin requires system library libc (whatever version appropriate for your OS) to be present in your system. Other native dependencies such as libomp are bundled in the release jar, so you normally do not need to do anything.

If the bundled libraries do not work on your machine, you may get them yourself:

• Linux needs OpenMP and Vectorized Math from GCC, e.g. on Debian/Ubuntu, apt-get install libgomp1 or apt-get install g++-12 gcc-12.

• MacOSX needs the same libraries as the above from Clang, e.g. brew install libomp llvm

JVM Options

You also want to add the following JVM options to your Java/Clojure project:

--add-opens=java.base/java.nio=ALL-UNNAMED
--add-opens=java.base/sun.nio.ch=ALL-UNNAMED

For lein, add a top level :jvm-opts in your project.clj like so:

:jvm-opts ["--add-opens=java.base/java.nio=ALL-UNNAMED"
           "--add-opens=java.base/sun.nio.ch=ALL-UNNAMED"]

For dep.edn, this is known to work:

:aliases {:jvm-base
           {:jvm-opts ["--add-opens=java.base/java.nio=ALL-UNNAMED"
                       "--add-opens=java.base/sun.nio.ch=ALL-UNNAMED"]}}

Then clj -A:jvm-base

Python and Javascript libraries have added these options automatically.

Java 24 and above

You want to add --enable-native-access=ALL-UNNAMED JVM options to disable warnings about native access.

Other JVM Languages

Datalevin can be used in other JVM languages than Clojure and Java, such as Scala, Kotlin, and so on, by wrapping the Java library. If you have done so, we will be happy to link to it here if you have done so.

Unreleased Code

The master branch of this project is kept fully functional, so if you need to use some yet-to-be released fixes or features, you can declare the dependency in deps.edn (remember to change the :sha):

{:deps {datalevin/datalevin
        {:git/url "https://github.com/datalevin/datalevin.git"
         :sha "d3251eb29e4b6baf6cce6c161f6f585c7a61acbc"}}}

Make sure to go to ~/.gitlibs/libs/datalevin/datalevin/$SHA and run lein test to compile and run tests first.

Command Line Tool

A command line tool dtlv is built to work with Datalevin databases in shell scripting, doing work such as database backup/compaction, data import/export, query/transaction execution, server administration, and so on. The same binary can also run as a Datalevin server. This tool also includes a REPL with a Clojure interpreter, in addition to support all the database functions.

Unlike many other database software (e.g. SQLite, Postgres, etc.) that introduces a separate language for the command line, the same Clojure code works in both Datalevin library and Datalevin command line tool.

A native Datalevin is built by compiling into GraalVM native image.

These are the ways to get the Datalevin command line tool:

MacOS and Linux Package

Install using homebrew

brew install huahaiy/brew/datalevin

Windows Package

Install using scoop

# Note: if you get an error you might need to change the execution policy (i.e. enable Powershell) with
# Set-ExecutionPolicy RemoteSigned -scope CurrentUser
Invoke-Expression (New-Object System.Net.WebClient).DownloadString('https://get.scoop.sh')

scoop bucket add scoop-clojure https://github.com/littleli/scoop-clojure
scoop bucket add extras
scoop install datalevin

Docker

docker pull huahaiy/datalevin

See README on Docker hub for usage.

Direct Download

Or download the executable binary from github:

• MacOS on arm64 (AARCH64)
• Linux on x86_64 (AMD64)
• Linux on arm64 (AARCH64)
• Windows on x86-64 (AMD64)

Unzip to get a dtlv executable, put it on your path.

You may want to launch dtlv in rlwrap to get a better REPL experience.

Uberjar

A JVM uberjar is downloadable to use as the command line tool. It is useful when one wants to run a Datalevin server and needs the efficiency of JVM's JIT, as GraalVM native image is not as efficient as Hotspot JVM for long running programs, or when a pre-built native version is not available for your platform. For example:

java --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED -jar datalevin-0.10.18-standalone.jar

This will start the Datalevin REPL.

java --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED -jar datalevin-0.10.18-standalone.jar serv -r /tmp/test-server

Will run the Datalevin server on default port 8898, with root data path at /tmp/test-server.

Babashka Pod

The dtlv executable can also run as a Babashka pod. It is also possible to download Datalevin directly from pod registry within a Babashka script (not all versions are registered):

#!/usr/bin/env bb

(require '[babashka.pods :as pods])
(pods/load-pod 'huahaiy/datalevin "0.10.18")

For pod usage, an extra macro defpodfn is provided to define a custom function that can be used in a query, e.g.:

$ rlwrap bb
Babashka v1.3.181 REPL.
Use :repl/quit or :repl/exit to quit the REPL.
Clojure rocks, Bash reaches.

user=> (require '[babashka.pods :as pods])
nil
user=> (pods/load-pod "dtlv")
#:pod{:id "pod.huahaiy.datalevin"}
user=> (require '[pod.huahaiy.datalevin :as d])
nil
user=> (d/defpodfn custom-fn [n] (str "hello " n))
#:pod.huahaiy.datalevin{:inter-fn custom-fn}
user=> (d/q '[:find ?greeting :where [(custom-fn "world") ?greeting]])
#{["hello world"]}
user=> (def conn (d/get-conn "/tmp/bb-test"))
#'user/conn
user=> (d/transact! conn [{:name "hello"}])
{:datoms-transacted 1}
user=> (d/q '[:find ?n :where [_ :name ?n]] (d/db conn))
#{["hello"]}
user=> (d/close conn)
nil
user=>

The example above uses dtlv binary in the PATH.