Java SDK

Install the SDK

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

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}"
}

Connecting to SurrealDB

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("Jaime").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.

.new()

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

Method Syntax
new SurrealWebSocketConnection(host, port, tls)

Arguments

.connect()

Connects to the SurrealDB instance within the timeout of seconds.

Method Syntax
SurrealWebSocketConnection.connect(timeout)

Arguments

.SyncSurrealDriver()

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

Method Syntax
new SyncSurrealDriver(conn)

Arguments

.signIn()

Signs in a user to a specific authentication scope.

Method Syntax
driver.signIn(user, pass)

Arguments

.signUp()

Signs up a user to a specific authentication scope.

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

Arguments

.authenticate()

Authenticates the current connection with a JWT token.

Method Syntax
driver.authenticate(token)

Arguments

.invalidate()

Invalidates the authentication for the current connection.

Method Syntax
driver.invalidate()

.use()

Switch to a specific namespace and database.

Method Syntax
driver.use(namespace, database)

Arguments

.let()

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

Method Syntax
driver.let(key, value)

Arguments

.query()

Runs a set of SurrealQL statements against the database.

Method Syntax
driver.query(query, args, rowType)

Arguments

.select()

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

Method Syntax
driver.select(thing, rowType)

Arguments

.create()

Creates a record in the database.

Method Syntax
driver.create(thing, data)

Arguments

.update()

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

Method Syntax
driver.update(thing, data)

Arguments

.change()

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

Method Syntax
driver.change(thing, data, rowType)

Arguments

.patch()

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

Method Syntax
driver.patch(thing, patches)

Arguments

.delete()

Deletes all records, or a specific record.

Method Syntax
driver.delete(thing)

Arguments