# Embedded databases

The Python SDK supports running SurrealDB as an embedded database directly within your application.

The Python SDK can run SurrealDB directly within your application process, eliminating the need for a separate server. Embedded databases are useful for testing, development, desktop applications, and scenarios where a standalone database server is impractical.

To use an embedded database, pass a `mem://`, `file://`, or `surrealkv://` URL to the `Surreal` or `AsyncSurreal` factory function.

## 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/python/api/core/surreal.md#surreal-sync"><code>Surreal(url)</code></a></td>
			<td scope="row" data-label="Description">Creates a synchronous embedded connection based on the URL scheme</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/python/api/core/surreal.md#surreal-sync"><code>AsyncSurreal(url)</code></a></td>
			<td scope="row" data-label="Description">Creates an asynchronous embedded connection based on the URL scheme</td>
		</tr>
	</tbody>
</table>

## Connection URL schemes

The URL scheme determines whether the embedded database stores data in memory or on disk.

| Scheme | Storage | Persistence |
|---|---|---|
| `mem://` | In-memory | Data is lost when the process exits |
| `file://path` | On-disk (SurrealKV) | Data persists to the specified directory |
| `surrealkv://path` | On-disk (SurrealKV) | Data persists to the specified directory |

See the [UrlScheme](/docs/reference/python/api/types/#urlscheme) type reference for the full list of supported schemes.

## In-memory databases

An in-memory database runs entirely in RAM and does not persist data between process restarts. This is well suited for unit tests, temporary workloads, and prototyping where durability is not required.

**Synchronous**

		```python
		from surrealdb import Surreal

		with Surreal("mem://") as db:
		    db.use("main", "main")
		    db.signin({"username": "root", "password": "secret"})
		    db.create("users", {"name": "Alice", "age": 30})
		    print(db.select("users"))
		```

**Asynchronous**

		```python
		from surrealdb import AsyncSurreal

		async with AsyncSurreal("mem://") as db:
		    await db.use("main", "main")
		    await db.signin({"username": "root", "password": "secret"})
		    await db.create("users", {"name": "Alice", "age": 30})
		    print(await db.select("users"))
		```

Each `mem://` connection creates an independent database instance. Data is not shared between separate connections.

## Persistent databases

The `file://` and `surrealkv://` schemes persist data to a directory on disk. This is useful for desktop applications, local-first architectures, and development workflows where you want data to survive restarts.

**Synchronous**

		```python
		from surrealdb import Surreal

		with Surreal("surrealkv://data/mydb") as db:
		    db.use("app", "main")
		    db.signin({"username": "root", "password": "secret"})
		    db.create("settings", {"theme": "dark", "lang": "en"})
		```

**Asynchronous**

		```python
		from surrealdb import AsyncSurreal

		async with AsyncSurreal("file://data/mydb") as db:
		    await db.use("app", "main")
		    await db.signin({"username": "root", "password": "secret"})
		    await db.create("settings", {"theme": "dark", "lang": "en"})
		```

The path is relative to the working directory of your process. Use an absolute path for a fixed location on disk.

## Feature limitations

Embedded connections do not support the full set of features available with WebSocket or HTTP connections. Attempting to use an unsupported feature raises an [`UnsupportedFeatureError`](/docs/reference/python/api/errors/#unsupportedfeatureerror).

The following features are **not available** with embedded connections:

- **Sessions**: `.new_session()` is not supported
- **Transactions**: `.new_transaction()` is not supported
- **Live queries**: `.live()` and `.subscribe_live()` are not supported

> [!NOTE]
> If your application requires sessions, transactions, or live queries, use a WebSocket connection (`ws://` or `wss://`) instead.

All other operations - queries, CRUD methods, authentication, and parameter binding - work as expected with embedded connections.

## Learn more

- [Surreal API reference](/docs/reference/python/api/core/surreal.md) for complete method signatures and parameters
- [Connecting to SurrealDB](/docs/reference/python/concepts/connecting-to-surrealdb.md) for an overview of all connection protocols
- [UrlScheme type reference](/docs/reference/python/api/types/#urlscheme) for the full list of URL schemes