Embedded databases

The Java SDK can run SurrealDB as an embedded in-process database, eliminating the need for a separate server. Embedded databases use JNI to run the SurrealDB engine directly within your application, which removes network overhead and simplifies deployment for testing, prototyping, and standalone applications.

API References

Method	Description
`db.connect(url)`	Connects using an embedded protocol
`db.exportSql(path)`	Exports the database to a file
`db.importSql(path)`	Imports data from a file

Running an in-memory database

Use the memory:// scheme to start an in-memory embedded database. All data is stored in memory and is lost when the connection closes. This is ideal for unit tests and rapid prototyping where persistence is not required.

try (Surreal db = new Surreal()) {
    db.connect("memory://");
    db.useNs("test").useDb("test");
}

Running a disk-based database

Use the surrealkv:// scheme with a file path to start a disk-based embedded database. Data is persisted to the specified directory and survives application restarts.

try (Surreal db = new Surreal()) {
    db.connect("surrealkv://path/to/database");
    db.useNs("app").useDb("main");
}

Exporting and importing data

The .exportSql() method writes the current database contents to a SurrealQL file. The .importSql() method reads a SurrealQL file and applies it to the database.

try (Surreal db = new Surreal()) {
    db.connect("surrealkv://path/to/database");
    db.useNs("app").useDb("main");

    db.exportSql("backup.surql");
    db.importSql("backup.surql");
}

When to use embedded databases

Embedded databases are well suited for scenarios where running a separate SurrealDB server is unnecessary or impractical:

Testing — use memory:// for fast, isolated tests that start with a clean database on every run.
Desktop and mobile applications — use surrealkv:// to bundle a persistent database directly within the application.
CLI tools — embed a database to store local state or configuration without requiring users to install SurrealDB.
Prototyping — iterate quickly without managing a server process.

Learn more

Surreal API reference for complete method signatures
Connecting to SurrealDB for all connection protocols
SurrealDB deployment for production server deployment
SurrealDB CLI start for server configuration and storage backends
SurrealDB CLI import and export for command-line data management