Skip to main content

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.

FunctionDescription
new SurrealWebSocketConnection(host, port, tls)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)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()Signs this connection in to a specific authentication scope
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()

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

Method Syntax
new SurrealWebSocketConnection(host, port, tls)

Arguments

ArgumentsDescription
hostREQUIRED

The database endpoint to connect to.

portREQUIRED

The database port to connect to.

tlsREQUIRED

Whether to use TLS or not.


.connect()

Connects to the SurrealDB instance within the timeout of seconds.

Method Syntax
SurrealWebSocketConnection.connect(timeout)

Arguments

ArgumentsDescription
timeoutREQUIRED

The time to wait to connect before erroring, in seconds.


.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

ArgumentsDescription
connREQUIRED

The connection to the database.


.signIn()

Signs in a user to a specific authentication scope.

Method Syntax
driver.signIn(user, pass)

Arguments

ArgumentsDescription
userREQUIRED

The user used for authentication.

passREQUIRED

The password used for authentication.


.signUp()

Signs up a user to a specific authentication scope.

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

Arguments

ArgumentsDescription
namespaceREQUIRED

The namespace to sign up for.

databaseREQUIRED

The database to sign up for.

scopeREQUIRED

The scope to sign up for.

emailREQUIRED

The email for sign up.

passwordREQUIRED

The password used for authentication.


.authenticate()

Authenticates the current connection with a JWT token.

Method Syntax
driver.authenticate(token)

Arguments

ArgumentsDescription
tokenREQUIRED

The JWT authentication token.


.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

ArgumentsDescription
namespaceREQUIRED

The namespace to use throughout the database session.

databaseREQUIRED

The database to use throughout the database session.


.let()

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

Method Syntax
driver.let(key, value)

Arguments

ArgumentsDescription
keyREQUIRED

The key of the variable being used within queries.

valueREQUIRED

The value of the variable being used within queries.


.query()

Runs a set of SurrealQL statements against the database.

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

Arguments

ArgumentsDescription
queryREQUIRED

The database endpoint to connect to.

argsREQUIRED

The arguments passed to the query in place of named parameters.

rowTypeREQUIRED

The class of the return type of the response.


.select()

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

Method Syntax
driver.select(thing, rowType)

Arguments

ArgumentsDescription
thingREQUIRED

The thing we are selecting, table or specific rows.

rowTypeREQUIRED

The class of the expected result.


.create()

Creates a record in the database.

Method Syntax
driver.create(thing, data)

Arguments

ArgumentsDescription
thingREQUIRED

The thing being created - table or specific records.

dataREQUIRED

The data being used for creation.


.update()

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

Method Syntax
driver.update(thing, data)

Arguments

ArgumentsDescription
thingREQUIRED

What is being updated - table or specific records.

dataREQUIRED

The data being replaced in the record.


.change()

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

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

Arguments

ArgumentsDescription
thingREQUIRED

What is being changed - table or records.

dataREQUIRED

What data is used to apply the change.

rowTypeREQUIRED

The returned type of the query.


.patch()

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

Method Syntax
driver.patch(thing, patches)

Arguments

ArgumentsDescription
thingREQUIRED

What is being patched - table or records.

patchesREQUIRED

The list of patches to apply.


.delete()

Deletes all records, or a specific record.

Method Syntax
driver.delete(thing)

Arguments

ArgumentsDescription
thingREQUIRED

What is being deleted - table or selected records.