The official SurrealDB SDK for Java

     

     

surrealdb.java

The official SurrealDB SDK for Java.

Documentation

View the SDK documentation here.

Features

• A thread-safe native JAVA client for SurrealDB.
• Simple API: see docs.
• Support of 'memory' (embedded SurrealDB).
• Support of remote connection to SurrealDB.
• Mutable POJOs (Java 8+) and immutable record classes (JDK 16+) for create / select.
• Supported on JAVA JDK 8, 11, 17, 21, 25.
• Supported architectures:
  • Linux (ARM) aarch64
  • Linux (INTEL) x86_64
  • Windows (INTEL) x86_64
  • MacOS (ARM) aarch64
  • MacOS (INTEL) x86_64
  • Android (Linux ARM) aarch64
  • Android (Linux INTEL) x86_64
• Zero dependencies

Minimum requirements

• Java 8

How to install

Stable release

Released to Maven Central.

Gradle:

ext {
    surrealdbVersion = "2.0.3"
}

dependencies {
    implementation "com.surrealdb:surrealdb:${surrealdbVersion}"
}

Maven:

<dependency>
    <groupId>com.surrealdb</groupId>
    <artifactId>surrealdb</artifactId>
    <version>2.0.3</version>
</dependency>

Snapshot release

Published to the Maven Central snapshots repository on every push to main. Use it to try out unreleased changes.

Gradle:

repositories {
    mavenCentral()
    maven {
        url = uri("https://central.sonatype.com/repository/maven-snapshots/")
        mavenContent { snapshotsOnly() }
    }
}

ext {
    surrealdbVersion = "2.1.0-SNAPSHOT"
}

dependencies {
    implementation "com.surrealdb:surrealdb:${surrealdbVersion}"
}

Maven:

<repositories>
    <repository>
        <id>central-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <releases><enabled>false</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
</repositories>

<dependency>
    <groupId>com.surrealdb</groupId>
    <artifactId>surrealdb</artifactId>
    <version>2.1.0-SNAPSHOT</version>
</dependency>

Getting started

package org.example;

import com.surrealdb.Surreal;
import com.surrealdb.RecordId;

import java.util.Iterator;

public class Example {
    public static void main(String[] args) {
        try (final Surreal driver = new Surreal()) {
            // Connect to the instance
            driver.connect("memory");
            // namespace & database
            driver.useNs("test").useDb("test");
            // Create a person
            Person person = new Person("Founder & CEO", "Tobie", "Morgan Hitchcock", true);
            // Insert a record
            List<Person> tobie = driver.create(Person.class, "person", person);
            // Read records
            Iterator<Person> people = driver.select(Person.class, "person");
            // Print them out
            System.out.println("Tobie = " + tobie);
            System.out.println("people = " + people.next());
        }
    }

    static class Person {
        RecordId id;
        String title;
        String firstName;
        String lastName;
        boolean marketing;

        //  A default constructor is required
        public Person() {
        }

        public Person(String title, String firstName, String lastName, boolean marketing) {
            this.title = title;
            this.firstName = firstName;
            this.lastName = lastName;
            this.marketing = marketing;
        }

        @Override
        public String toString() {
            return "Person{" +
                    "id='" + id + '\'' +
                    ", title='" + title + '\'' +
                    ", firstName='" + firstName + '\'' +
                    ", lastName='" + lastName + '\'' +
                    ", marketing=" + marketing +
                    '}';
        }
    }
}

Reports

• Javadoc
• Test summary
• Coverage report

Developing

On Linux/Mac:

cargo build
./gradlew -i test

On Windows:

cargo build
./gradlew.bat -i test

Planned Features

• All Geometry types (actually only points)
• Ranges
• Future
• Live queries

Open an issue for feature requests