Connecting to SurrealDB
The first step towards interacting with SurrealDB is to create a new connection to a database instance. This involves initializing a new Surreal instance, connecting it to an endpoint, and selecting a namespace and database. The SDK supports remote connections over WebSocket and HTTP, as well as embedded in-process databases.
API References
Opening a connection
Create a new Surreal instance and call .connect() with a connection string pointing to your SurrealDB instance. The Surreal class implements AutoCloseable, so you can use it in a try-with-resources block to ensure the connection is closed automatically.
Surreal db = new Surreal();
db.connect("ws://localhost:8000");
Connection string protocols
The connection string determines the protocol and transport used to communicate with SurrealDB. For more on server configuration, see the start command documentation.
| Protocol | Description |
|---|
ws:// | Plain WebSocket connection |
wss:// | Secure WebSocket connection (TLS) |
http:// | Plain HTTP connection |
https:// | Secure HTTP connection (TLS) |
memory:// | In-memory embedded database |
surrealkv:// | Disk-based embedded database |
The memory:// and surrealkv:// protocols run SurrealDB in-process using JNI, which eliminates network overhead. See Embedded databases for details on configuring embedded connections.
Feature support by protocol
Not all features are available on every protocol. The table below summarizes what is supported for each connection type.
| Feature | WebSocket | HTTP | Embedded |
|---|
| Authentication | Yes | Yes | Yes |
| Queries | Yes | Yes | Yes |
| CRUD operations | Yes | Yes | Yes |
| Live queries | Yes | No | No |
| Transactions | Yes | No | Yes |
| Multiple sessions | Yes | No | Yes |
| Export / Import | Yes | Yes | Yes |
Selecting a namespace and database
After connecting, select a namespace and database using .useNs() and .useDb(). These methods return the Surreal instance, so they can be chained.
db.useNs("surrealdb").useDb("docs");
To reset the namespace and database to the server defaults, call .useDefaults().
db.useDefaults();
Using try-with-resources
Since Surreal implements AutoCloseable, Java’s try-with-resources statement ensures that .close() is called when the block exits, even if an exception is thrown. This is the recommended pattern for managing connections.
import com.surrealdb.Surreal;
import com.surrealdb.signin.RootCredential;
public class Example {
public static void main(String[] args) {
try (Surreal db = new Surreal()) {
db.connect("ws://localhost:8000");
db.useNs("surrealdb").useDb("docs");
db.signin(new RootCredential("root", "root"));
String version = db.version();
System.out.println("Connected to SurrealDB " + version);
}
}
}
Effect of connection protocol on token and session duration
The connection protocol affects how authentication tokens and sessions behave.
- WebSocket connections are stateful and long-lived. After the initial authentication, the session persists for the lifetime of the connection. The session duration defaults to
NONE, meaning it never expires unless explicitly configured. - HTTP connections are stateless. Each request must include a valid token, and the server creates a short-lived session for the duration of that request. The token duration defaults to 1 hour.
You can configure token and session durations using the DURATION clause on DEFINE ACCESS or DEFINE USER statements. See the security best practices documentation for guidance on choosing appropriate durations.
Closing a connection
The .close() method releases all resources associated with the connection. If you are not using try-with-resources, call .close() explicitly when you are done with the connection.
db.close();
Learn more
