# Embedded databases

The Java SDK can run SurrealDB as an embedded in-process database for testing and standalone applications.

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

<table>
	<thead>
		<tr>
			<th scope="col">Method</th>
			<th scope="col">Description</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/java/api/core/surreal.md#connect"><code>db.connect(url)</code></a></td>
			<td scope="row" data-label="Description">Connects using an embedded protocol</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/java/api/core/surreal.md#export-sql"><code>db.exportSql(path)</code></a></td>
			<td scope="row" data-label="Description">Exports the database to a file</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/java/api/core/surreal.md#import-sql"><code>db.importSql(path)</code></a></td>
			<td scope="row" data-label="Description">Imports data from a file</td>
		</tr>
	</tbody>
</table>

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

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

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

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

## Exporting and importing data

The [`.exportSql()`](/docs/reference/java/api/core/surreal.md#export-sql) method writes the current database contents to a SurrealQL file. The [`.importSql()`](/docs/reference/java/api/core/surreal.md#import-sql) method reads a SurrealQL file and applies it to the database.

```java
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](/docs/reference/java/api/core/surreal.md) for complete method signatures
- [Connecting to SurrealDB](/docs/reference/java/concepts/connecting-to-surrealdb.md) for all connection protocols
- [Deployment models](/docs/manage/self-hosted/deployment-models.md) for production server deployment
- [SurrealDB CLI start](/docs/reference/cli/surrealdb-cli/commands/start.md) for server configuration and storage backends
- [SurrealDB CLI import](/docs/reference/cli/surrealdb-cli/commands/import.md) and [export](/docs/reference/cli/surrealdb-cli/commands/export.md) for command-line data management