# Surreal

The Surreal class is the main entry point for connecting to and interacting with a SurrealDB instance from Java.

The `Surreal` class is the main entry point for the Java SDK. It provides methods for connecting to a SurrealDB instance, authenticating, querying, and managing data. The class implements `AutoCloseable`, so it can be used in a try-with-resources block to ensure the connection is closed automatically.

**Source:** [surrealdb.java](https://github.com/surrealdb/surrealdb.java)

---

## Connection methods

### `Surreal()` {#constructor}

Creates a new `Surreal` instance. The instance is not connected to any server until `.connect()` is called.

```java title="Method Syntax"
Surreal db = new Surreal();
```

**Returns:** `Surreal`

```java title="Example"
Surreal db = new Surreal();
```

### `.connect(url)` {#connect}

Connects the instance to a SurrealDB server using the specified URL. The URL scheme determines the connection protocol. See the [start command](/docs/reference/cli/surrealdb-cli/commands/start.md) documentation for server configuration options.

```java title="Method Syntax"
db.connect(url)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>url</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The connection URL. Supported schemes: <code>ws://</code>, <code>wss://</code>, <code>http://</code>, <code>https://</code>, <code>memory://</code>, <code>surrealkv://</code>.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Surreal` (for method chaining)

```java title="Example"
db.connect("ws://localhost:8000");
```

### `.close()` {#close}

Closes the active connection and releases all associated resources. This is called automatically when using try-with-resources.

```java title="Method Syntax"
db.close()
```

**Returns:** `void`

```java title="Example"
db.close();
```

### `.useNs(namespace)` {#use-ns}

Switches the connection to a specific namespace.

```java title="Method Syntax"
db.useNs(ns)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>ns</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The namespace to switch to.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Surreal` (for method chaining)

```java title="Example"
db.useNs("surrealdb").useDb("docs");
```

### `.useDb(database)` {#use-db}

Switches the connection to a specific database.

```java title="Method Syntax"
db.useDb(database)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>db</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The database to switch to.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Surreal` (for method chaining)

```java title="Example"
db.useDb("docs");
```

### `.useDefaults()` {#use-defaults}

Resets the namespace and database to the server defaults.

```java title="Method Syntax"
db.useDefaults()
```

**Returns:** `Surreal` (for method chaining)

```java title="Example"
db.useDefaults();
```

### `.getNamespace()` {#get-namespace}

Returns the namespace currently in use on this connection.

```java title="Method Syntax"
db.getNamespace()
```

**Returns:** `String`

```java title="Example"
String ns = db.getNamespace();
```

### `.getDatabase()` {#get-database}

Returns the database currently in use on this connection.

```java title="Method Syntax"
db.getDatabase()
```

**Returns:** `String`

```java title="Example"
String database = db.getDatabase();
```

### `.newSession()` {#new-session}

Creates a new isolated session that shares the underlying connection but maintains its own namespace, database, authentication state, and variables.

```java title="Method Syntax"
db.newSession()
```

**Returns:** `Surreal`

```java title="Example"
Surreal session = db.newSession();
session.useNs("other_ns").useDb("other_db");
```

---

## Authentication methods

### `.signin(credential)` {#signin}

Signs in to the database with the provided credentials. The credential type determines the authentication level: root, namespace, database, or record access.

```java title="Method Syntax"
db.signin(credential)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>credential</code> _(required)_</td>
            <td><code>Credential</code></td>
            <td>The credentials to sign in with. Use <code>RootCredential</code>, <code>NamespaceCredential</code>, <code>DatabaseCredential</code>, or <code>RecordCredential</code>.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Token`

```java title="Example"
Token token = db.signin(new RootCredential("root", "root"));
```

### `.signup(credential)` {#signup}

Signs up a new record user using a record access method defined with [`DEFINE ACCESS`](/docs/reference/query-language/statements/define/access.md).

```java title="Method Syntax"
db.signup(credential)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>credential</code> _(required)_</td>
            <td><code>RecordCredential</code></td>
            <td>The record access credentials including namespace, database, access method, and any additional fields required by the access definition.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Token`

```java title="Example"
Token token = db.signup(new RecordCredential(
    "surrealdb", "docs", "user_access",
    Map.of("email", "user@example.com", "password", "s3cret")
));
```

### `.authenticate(token)` {#authenticate}

Authenticates the current connection using an existing JWT token.

```java title="Method Syntax"
db.authenticate(token)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>token</code> _(required)_</td>
            <td><code>String</code></td>
            <td>A valid JWT token string.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Surreal` (for method chaining)

```java title="Example"
db.authenticate("eyJhbGciOiJIUzI1NiIs...");
```

### `.invalidate()` {#invalidate}

Invalidates the current authentication, removing the associated session token.

```java title="Method Syntax"
db.invalidate()
```

**Returns:** `Surreal` (for method chaining)

```java title="Example"
db.invalidate();
```

---

## Query methods

### `.query(sql)` {#query}

Executes one or more SurrealQL statements and returns a `Response` containing the results of each statement.

```java title="Method Syntax"
db.query(sql)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>sql</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The SurrealQL query string to execute.</td>
        </tr>
    </tbody>
</table>

**Returns:** [`Response`](/docs/reference/java/api/core/response.md)

```java title="Example"
Response response = db.query("SELECT * FROM users");
List<User> users = response.take(User.class, 0);
```

### `.queryBind(sql, params)` {#query-bind}

Executes a parameterised SurrealQL query. Parameters are safely injected into the query, preventing SurrealQL injection.

```java title="Method Syntax"
db.queryBind(sql, params)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>sql</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The SurrealQL query string with parameter placeholders.</td>
        </tr>
        <tr>
            <td><code>params</code> _(required)_</td>
            <td><code>Map&lt;String, ?&gt;</code></td>
            <td>A map of parameter names to values.</td>
        </tr>
    </tbody>
</table>

**Returns:** [`Response`](/docs/reference/java/api/core/response.md)

```java title="Example"
Response response = db.queryBind(
    "SELECT * FROM users WHERE age > $min_age",
    Map.of("min_age", 18)
);
```

### `.run(name, args)` {#run}

Runs a server-side SurrealDB function defined with [`DEFINE FUNCTION`](/docs/reference/query-language/statements/define/function.md).

```java title="Method Syntax"
db.run(name, args)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>name</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The function name (e.g. <code>"fn::calculate_total"</code>).</td>
        </tr>
        <tr>
            <td><code>args</code> _(optional)_</td>
            <td><code>Object...</code></td>
            <td>Arguments to pass to the function.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Value`

```java title="Example"
Value result = db.run("fn::calculate_total", 100, 0.2);
```

---

## Data methods

> [!NOTE]
> Most data methods have multiple overloads. The typed variants accepting `Class<T>` are shown below. Untyped variants returning `Value` or `Iterator<Value>` are also available.

### `.create(type, target, content)` {#create}

Creates one or more records. When called with a table name, SurrealDB generates random IDs. When called with a `RecordId`, the record is created with that specific ID.

```java title="Method Syntax"
<T> List<T> create(Class<T> type, String target, T... contents)
<T> T create(Class<T> type, RecordId recordId, T content)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>type</code> _(required)_</td>
            <td><code>Class&lt;T&gt;</code></td>
            <td>The class to deserialise results into.</td>
        </tr>
        <tr>
            <td><code>target</code> _(required)_</td>
            <td><code>String</code> or <code>RecordId</code></td>
            <td>The table name or specific record ID.</td>
        </tr>
        <tr>
            <td><code>contents</code> _(required)_</td>
            <td><code>T</code> or <code>T...</code></td>
            <td>The record content(s) to create.</td>
        </tr>
    </tbody>
</table>

**Returns:** `List<T>` (table target) or `T` (record ID target)

```java title="Example"
Person alice = new Person();
alice.name = "Alice";
alice.age = 30;

List<Person> created = db.create(Person.class, "person", alice);

Person specific = db.create(Person.class, new RecordId("person", "tobie"), alice);
```

### `.select(type, target)` {#select}

Selects records from a table or retrieves specific records by ID.

```java title="Method Syntax"
<T> Iterator<T> select(Class<T> type, String target)
<T> Optional<T> select(Class<T> type, RecordId recordId)
<T> List<T> select(Class<T> type, RecordId... recordIds)
<T> List<T> select(Class<T> type, RecordIdRange range)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>type</code> _(required)_</td>
            <td><code>Class&lt;T&gt;</code></td>
            <td>The class to deserialise results into.</td>
        </tr>
        <tr>
            <td><code>target</code> _(required)_</td>
            <td><code>String</code>, <code>RecordId</code>, <code>RecordId...</code>, or <code>RecordIdRange</code></td>
            <td>The table name, a single record ID, multiple record IDs, or a record ID range.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Iterator<T>` (table), `Optional<T>` (single ID), `List<T>` (multiple IDs or range)

```java title="Example"
Iterator<Person> all = db.select(Person.class, "person");

Optional<Person> one = db.select(Person.class, new RecordId("person", "tobie"));

List<Person> range = db.select(Person.class,
    new RecordIdRange("person", Id.from("a"), Id.from("m")));
```

### `.selectSync(type, target)` {#select-sync}

Thread-safe variant of [`.select()`](#select) for table-level queries. Returns a synchronized iterator safe for use across multiple threads.

```java title="Method Syntax"
<T> Iterator<T> selectSync(Class<T> type, String target)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>type</code> _(required)_</td>
            <td><code>Class&lt;T&gt;</code></td>
            <td>The class to deserialise results into.</td>
        </tr>
        <tr>
            <td><code>target</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The table name to select from.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Iterator<T>` (synchronized)

```java title="Example"
Iterator<Person> all = db.selectSync(Person.class, "person");
```

### `.insert(type, target, content)` {#insert}

Inserts one or more records into a table.

```java title="Method Syntax"
<T> List<T> insert(Class<T> type, String target, T... contents)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>type</code> _(required)_</td>
            <td><code>Class&lt;T&gt;</code></td>
            <td>The class to deserialise results into.</td>
        </tr>
        <tr>
            <td><code>target</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The table to insert into.</td>
        </tr>
        <tr>
            <td><code>contents</code> _(required)_</td>
            <td><code>T...</code></td>
            <td>The record content(s) to insert.</td>
        </tr>
    </tbody>
</table>

**Returns:** `List<T>`

```java title="Example"
Person alice = new Person();
alice.name = "Alice";

List<Person> inserted = db.insert(Person.class, "person", alice);
```

### `.update(type, target, upType, content)` {#update}

Updates existing records. Use `UpType.CONTENT` to replace the entire record, `UpType.MERGE` to merge fields into the existing record, or `UpType.PATCH` to apply a JSON Patch.

```java title="Method Syntax"
<T> T update(Class<T> type, RecordId recordId, UpType upType, T content)
<T> Iterator<T> update(Class<T> type, String target, UpType upType, T content)
<T> Value update(RecordIdRange range, UpType upType, T content)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>type</code> _(required)_</td>
            <td><code>Class&lt;T&gt;</code></td>
            <td>The class to deserialise results into.</td>
        </tr>
        <tr>
            <td><code>target</code> _(required)_</td>
            <td><code>RecordId</code>, <code>RecordIdRange</code>, or <code>String</code></td>
            <td>The record ID, record ID range, or table name to update.</td>
        </tr>
        <tr>
            <td><code>upType</code> _(required)_</td>
            <td><code>UpType</code></td>
            <td>The update strategy: <code>UpType.CONTENT</code> (replace), <code>UpType.MERGE</code> (merge), or <code>UpType.PATCH</code> (JSON Patch).</td>
        </tr>
        <tr>
            <td><code>content</code> _(required)_</td>
            <td><code>T</code></td>
            <td>The update content.</td>
        </tr>
    </tbody>
</table>

**Returns:** `T` (single record) or `Iterator<T>` (table)

```java title="Example"
Person updated = new Person();
updated.name = "Alice Smith";
updated.age = 31;

Person result = db.update(Person.class, new RecordId("person", "alice"), UpType.CONTENT, updated);
```

### `.updateSync(type, target, upType, content)` {#update-sync}

Thread-safe variant of [`.update()`](#update) for table-level updates. Returns a synchronized iterator safe for use across multiple threads.

```java title="Method Syntax"
<T> Iterator<T> updateSync(Class<T> type, String target, UpType upType, T content)
```

**Returns:** `Iterator<T>` (synchronized)

```java title="Example"
Iterator<Person> results = db.updateSync(Person.class, "person", UpType.MERGE, updates);
```

### `.upsert(type, target, upType, content)` {#upsert}

Updates an existing record or creates a new one if it does not exist. Accepts the same parameters as [`.update()`](#update).

```java title="Method Syntax"
<T> T upsert(Class<T> type, RecordId recordId, UpType upType, T content)
<T> Iterator<T> upsert(Class<T> type, String target, UpType upType, T content)
<T> Value upsert(RecordIdRange range, UpType upType, T content)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>type</code> _(required)_</td>
            <td><code>Class&lt;T&gt;</code></td>
            <td>The class to deserialise results into.</td>
        </tr>
        <tr>
            <td><code>target</code> _(required)_</td>
            <td><code>RecordId</code>, <code>RecordIdRange</code>, or <code>String</code></td>
            <td>The record ID, record ID range, or table name to upsert.</td>
        </tr>
        <tr>
            <td><code>upType</code> _(required)_</td>
            <td><code>UpType</code></td>
            <td>The update strategy: <code>UpType.CONTENT</code> (replace), <code>UpType.MERGE</code> (merge), or <code>UpType.PATCH</code> (JSON Patch).</td>
        </tr>
        <tr>
            <td><code>content</code> _(required)_</td>
            <td><code>T</code></td>
            <td>The record content.</td>
        </tr>
    </tbody>
</table>

**Returns:** `T` (single record) or `Iterator<T>` (table)

```java title="Example"
Person person = new Person();
person.name = "Alice";
person.age = 30;

Person result = db.upsert(Person.class, new RecordId("person", "alice"), UpType.CONTENT, person);
```

### `.upsertSync(type, target, upType, content)` {#upsert-sync}

Thread-safe variant of [`.upsert()`](#upsert) for table-level upserts. Returns a synchronized iterator safe for use across multiple threads.

```java title="Method Syntax"
<T> Iterator<T> upsertSync(Class<T> type, String target, UpType upType, T content)
```

**Returns:** `Iterator<T>` (synchronized)

```java title="Example"
Iterator<Person> results = db.upsertSync(Person.class, "person", UpType.CONTENT, person);
```

### `.delete(target)` {#delete}

Deletes records from the database. Supports deleting a single record, multiple records by ID, a range of records, or all records in a table.

```java title="Method Syntax"
void delete(RecordId recordId)
void delete(RecordId... recordIds)
void delete(RecordIdRange range)
void delete(String target)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>target</code> _(required)_</td>
            <td><code>RecordId</code>, <code>RecordId...</code>, <code>RecordIdRange</code>, or <code>String</code></td>
            <td>A single record ID, multiple record IDs, a record ID range, or a table name.</td>
        </tr>
    </tbody>
</table>

**Returns:** `void`

```java title="Example"
db.delete(new RecordId("person", "tobie"));

db.delete(new RecordId("person", "alice"), new RecordId("person", "bob"));

db.delete(new RecordIdRange("person", Id.from("a"), Id.from("f")));

db.delete("temp_data");
```

### `.relate(from, table, to)` {#relate}

Creates a graph relation between two records.

```java title="Method Syntax"
Value relate(RecordId from, String table, RecordId to)
<T extends Relation> T relate(Class<T> type, RecordId from, String table, RecordId to)
<T> Value relate(RecordId from, String table, RecordId to, T content)
<R extends Relation, T> R relate(Class<R> type, RecordId from, String table, RecordId to, T content)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>type</code> _(optional)_</td>
            <td><code>Class&lt;T extends Relation&gt;</code></td>
            <td>The class to deserialise the relation into. Omit for untyped <code>Value</code> return.</td>
        </tr>
        <tr>
            <td><code>from</code> _(required)_</td>
            <td><code>RecordId</code></td>
            <td>The source record.</td>
        </tr>
        <tr>
            <td><code>table</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The relation table name.</td>
        </tr>
        <tr>
            <td><code>to</code> _(required)_</td>
            <td><code>RecordId</code></td>
            <td>The target record.</td>
        </tr>
        <tr>
            <td><code>content</code> _(optional)_</td>
            <td><code>T</code></td>
            <td>Additional data to attach to the edge record.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Value` or `T`

```java title="Example"
Value relation = db.relate(
    new RecordId("person", "alice"),
    "likes",
    new RecordId("post", "post1")
);

Value withContent = db.relate(
    new RecordId("person", "alice"),
    "likes",
    new RecordId("post", "post1"),
    Map.of("timestamp", "2026-01-01T00:00:00Z")
);
```

### `.insertRelation(target, content)` {#insert-relation}

Inserts a relation record into a relation table with additional data.

```java title="Method Syntax"
<T extends InsertRelation> T insertRelation(Class<T> type, String target, T content)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>type</code> _(required)_</td>
            <td><code>Class&lt;T extends InsertRelation&gt;</code></td>
            <td>The relation class to deserialise into.</td>
        </tr>
        <tr>
            <td><code>target</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The relation table name.</td>
        </tr>
        <tr>
            <td><code>content</code> _(required)_</td>
            <td><code>T</code></td>
            <td>The relation content, including <code>in</code> and <code>out</code> fields.</td>
        </tr>
    </tbody>
</table>

**Returns:** `T`

```java title="Example"
Likes like = new Likes();
like.in = new RecordId("person", "alice");
like.out = new RecordId("post", "post1");
like.createdAt = "2025-01-01T00:00:00Z";

Likes result = db.insertRelation(Likes.class, "likes", like);
```

### `.insertRelations(target, contents)` {#insert-relations}

Inserts multiple relation records into a relation table using varargs.

```java title="Method Syntax"
<T extends InsertRelation> List<T> insertRelations(Class<T> type, String target, T... contents)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>type</code> _(required)_</td>
            <td><code>Class&lt;T extends InsertRelation&gt;</code></td>
            <td>The relation class to deserialise into.</td>
        </tr>
        <tr>
            <td><code>target</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The relation table name.</td>
        </tr>
        <tr>
            <td><code>contents</code> _(required)_</td>
            <td><code>T...</code></td>
            <td>The relation records to insert, each including <code>in</code> and <code>out</code> fields.</td>
        </tr>
    </tbody>
</table>

**Returns:** `List<T>`

```java title="Example"
Likes like1 = new Likes();
like1.in = new RecordId("person", "alice");
like1.out = new RecordId("post", "post1");

Likes like2 = new Likes();
like2.in = new RecordId("person", "alice");
like2.out = new RecordId("post", "post2");

List<Likes> results = db.insertRelations(Likes.class, "likes", like1, like2);
```

---

## Live query methods

> [!NOTE]
> Live queries require a WebSocket connection (`ws://` or `wss://`).

### `.selectLive(table)` {#select-live}

Starts a live query that receives real-time notifications when records in the specified table are created, updated, or deleted.

```java title="Method Syntax"
db.selectLive(table)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>table</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The table to watch for changes.</td>
        </tr>
    </tbody>
</table>

**Returns:** [`LiveStream`](/docs/reference/java/api/core/live-stream.md)

```java title="Example"
LiveStream stream = db.selectLive("person");
```

---

## Transaction methods

### `.beginTransaction()` {#begin-transaction}

Starts a new atomic transaction. All operations performed on the returned `Transaction` are grouped and only applied when committed.

```java title="Method Syntax"
db.beginTransaction()
```

**Returns:** [`Transaction`](/docs/reference/java/api/core/transaction.md)

```java title="Example"
Transaction tx = db.beginTransaction();
```

---

## Utility methods

### `.version()` {#version}

Returns the version string of the connected SurrealDB server.

```java title="Method Syntax"
db.version()
```

**Returns:** `String`

```java title="Example"
String version = db.version();
```

### `.health()` {#health}

Checks the health of the connected SurrealDB server.

```java title="Method Syntax"
db.health()
```

**Returns:** `boolean`

```java title="Example"
boolean healthy = db.health();
```

### `.exportSql(path)` {#export-sql}

Exports the current database to a file at the specified path.

```java title="Method Syntax"
db.exportSql(path)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>path</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The file path to export the database to.</td>
        </tr>
    </tbody>
</table>

**Returns:** `boolean`

```java title="Example"
boolean success = db.exportSql("/tmp/backup.surql");
```

### `.importSql(path)` {#import-sql}

Imports a database from a file at the specified path.

```java title="Method Syntax"
db.importSql(path)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>path</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The file path to import the database from.</td>
        </tr>
    </tbody>
</table>

**Returns:** `boolean`

```java title="Example"
boolean success = db.importSql("/tmp/backup.surql");
```

---

## See also

- [Transaction](/docs/reference/java/api/core/transaction.md) - Transaction reference
- [Response](/docs/reference/java/api/core/response.md) - Query response reference
- [LiveStream](/docs/reference/java/api/core/live-stream.md) - Live query reference
- [Connecting to SurrealDB](/docs/reference/java/concepts/connecting-to-surrealdb.md) - Connection protocols and patterns
- [Authentication](/docs/reference/java/concepts/authentication.md) - Authentication concepts
- [SurrealQL](/docs/reference/query-language.md) - Query language reference
- [DEFINE USER](/docs/reference/query-language/statements/define/user.md) - System user configuration
- [DEFINE ACCESS](/docs/reference/query-language/statements/define/access.md) - Record access method configuration