Back to top
Documentation Integrations SDKs Java

Java SDK for SurrealDB

The SurrealDB SDK for Java enables simple and advanced querying of a remote database from client or server-side code. Remote connections automatically reconnect when the connection is terminated.

To contribute to this documentation, edit this file on GitHub.

To contribute to the SDK code, submit an Issue or Pull Request here.

Install the SDK

You can add the SDK to your project like you would any standard dependency.

GroupID com.surrealdb
Artifact surrealdb-driver
Version 0.1.0

To include the driver in your maven project it is sufficient to add the following dependency to your dependency block.

<dependency>
	<groupId>com.surrealdb</groupId>
	<artifactId>surrealdb-driver</artifactId>
	<version>0.1.0</version>
</dependency>

To include the driver in your gradle project, add the following

ext {
	surrealdbVersion = "0.1.0"
}

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

Connect

Below is a snippet of code that demonstrates how you can connect to SurrealDB.

import com.surrealdb.connection.SurrealWebSocketConnection;
import com.surrealdb.driver.SyncSurrealDriver;

import java.util.List;
import java.util.Map;

public class App
{
    public static void main( String[] args )
    {
        SurrealWebSocketConnection conn = new SurrealWebSocketConnection("localhost", 8000, false);
        conn.connect(5);
        SyncSurrealDriver driver = new SyncSurrealDriver(conn);
        driver.signIn("root", "root");
        driver.use("namespace-name", "database-name");
        String tableName = "user";
        driver.delete(tableName);
        User tobie = driver.create(tableName, User.builder().name("Tobie").build());
        User jaime = driver.create(tableName, User.builder().name("Tobie").build());
        List<Map<String, String>> updates = driver.update(jaime.id, Map.of(
                "name", "Jaime"));
        List<User> allUsers = driver.select(tableName, User.class);
        System.out.printf("All users = %s", allUsers);
        conn.disconnect();
    }
}

SDK methods

The Java SDK comes with a number of built-in functions.

Function Description
new SurrealWebSocketConnection(host, port, tls) static Creates a new connection instance. The connection will upgrade the protocol to WebSockets, providing better performance and functionality. This class is used to connect to the database but is not the driver.
SurrealWebSocketConnection.connect(timeout) Initiates the connection to the database. This is necessary before the driver can be used.
new SyncSurrealDriver(conn) static Creates an instance of the driver to interact with the database remotely.
driver.signIn(user, pass) Sign in to the database. This is a necessary step before using the database.
driver.signUp(namespace, database, scope, email, password) Signs up a user to a specific authentication scope.
driver.authenticate(token) Authenticates the current connection with a JWT token.
driver.invalidate() Invalidates the authentication for the current connection.
driver.use(namespace, database) Switch to a specific namespace and database.
driver.let(key, value) Set a variable that can be used throughout the database session.
driver.query(query, args, rowType) Runs a set of SurrealQL statements against the database.
driver.select(thing, rowType) Selects all records in a table, or a specific record.
driver.create(thing, data) Creates a record in the database.
driver.update(thing, data) Updates all records in a table, or a specific record.
driver.change(thing, data, rowType) Change all records in a table, or a specific record.
driver.patch(thing, patches) Patch all records in a table, or a specific record.
driver.delete(thing) Deletes all records, or a specific record.

new SurrealWebSocketConnection(host, port, tls)

Initiates a connection instance that can be used to make a connection to a SurrealDB instance.

Arguments Description
host Required The database endpoint to connect to.
port Required The database port to connect to.
tls Required Whether to use TLS or not.

SurrealWebSocketConnection.connect(timeout)

Connects to the SurrealDB instance within the timeout of seconds.

Arguments Description
timeout Required The time to wait to connect before erroring, in seconds.

new SyncSurrealDriver(conn)

Creates an instance of the synchronous driver. There is an asynchronous counterpart - AsyncSurrealDriver that fills the same functionality.

Arguments Description
conn Required The connection to the database.

driver.signIn(user, pass)

Sign in to the database. This is a necessary step before using the database.

Arguments Description
user Required The user used for authentication.
pass Required The password used for authentication.

driver.signUp(namespace, database, scope, email, password)

Signs up a user to a specific authentication scope.

Arguments Description
namespace Required The namespace to sign up for.
database Required The database to sign up for.
scope Required The scope to sign up for.
email Required The email for sign up.
password Required The password used for authentication.

driver.authenticate(token)

Authenticates the current connection with a JWT token.

Arguments Description
token Required The JWT authentication token.

driver.invalidate()

Invalidates the authentication for the current connection.

driver.use(namespace, database)

Switch to a specific namespace and database.

Arguments Description
namespace Required The namespace to use throughout the database session.
database Required The database to use throughout the database session.

driver.let(key, value)

Set a variable that can be used throughout the database session.

Arguments Description
key Required The key of the variable being used within queries.
value Required The value of the variable being used within queries.

driver.query(query, args, rowType)

Runs a set of SurrealQL statements against the database.

Arguments Description
query Required The database endpoint to connect to.
args Required The arguments passed to the query in place of named parameters.
rowType Required The class of the return type of the response.

driver.select(thing, rowType)

Selects all records in a table, or a specific record.

Arguments Description
thing Required The thing we are selecting, table or specific rows.
rowType Required The class of the expected result.

driver.create(thing, data)

Creates a record in the database.

Arguments Description
thing Required The thing being created - table or specific records.
data Required The data being used for creation.

driver.update(thing, data)

Updates all records in a table, or a specific record.

Arguments Description
thing Required What is being updated - table or specific records.
data Required The data being replaced in the record.

driver.change(thing, data, rowType)

Change all records in a table, or a specific record.

Arguments Description
thing Required What is being changed - table or records.
data Required What data is used to apply the change.
rowType Required The returned type of the query.

driver.patch(thing, patches)

Patch all records in a table, or a specific record.

Arguments Description
thing Required What is being patched - table or records.
patches Required The list of patches to apply.

driver.delete(thing)

Deletes all records, or a specific record.

Arguments Description
thing Required What is being deleted - table or selected records.