Skip to content

By language

Python

The Python SDK can run SurrealDB inside your Python process, so that your application uses SurrealDB without a separate server. This suits desktop applications, tests, local development and programs that keep their data on the same machine. This page shows how to install the embedded engine and gives a short example. Embedded databases in the Python SDK documentation covers the rest, such as the features that an embedded connection supports and how to move data from an earlier engine.

The embedded engine is an optional part of the SDK, which the embedded extra installs:

pip install "surrealdb[embedded]"
  • In memory (mem:// or memory): the data is kept in the memory of the process and is lost when the connection closes. This suits tests and temporary data.

  • On disk (surrealkv:// or file://): the data is kept in a SurrealKV directory, and it is still there when the program opens the directory again.

An embedded connection needs no sign-in, so call use() and start to query:

import asyncio

from surrealdb import AsyncSurreal, Table


async def main():
    # In-memory database
    async with AsyncSurreal("mem://") as db:
        await db.use("main", "main")
        person = await db.create(Table("person"), {"name": "John Doe"})
        print(person)

    # On-disk database in the directory mydb
    async with AsyncSurreal("surrealkv://mydb") as db:
        await db.use("main", "main")
        company = await db.create(Table("company"), {"name": "TechStart"})
        print(company)


asyncio.run(main())

The same code works with the blocking client: use Surreal in place of AsyncSurreal, with in place of async with, and leave out await.

Was this page helpful?

Last updated