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