Embedded databases

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

Connection URL schemes

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

See the 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.

		from surrealdb import Surreal

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

		from surrealdb import AsyncSurreal

		async with AsyncSurreal("mem://") as db:
		    await db.use("test", "test")
		    await db.signin({"username": "root", "password": "root"})
		    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.

		from surrealdb import Surreal

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

		from surrealdb import AsyncSurreal

		async with AsyncSurreal("file://data/mydb") as db:
		    await db.use("app", "main")
		    await db.signin({"username": "root", "password": "root"})
		    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.

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

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

Learn more

• Surreal API reference for complete method signatures and parameters

• Connecting to SurrealDB for an overview of all connection protocols

• UrlScheme type reference for the full list of URL schemes