Connecting to SurrealDB

The Python SDK supports connecting to SurrealDB over WebSocket, HTTP, or as an embedded in-process database. Connections can be synchronous or asynchronous, and the SDK automatically selects the correct connection class based on the URL scheme you provide.

This page covers how to create, configure, and manage connections to a SurrealDB instance.

API References

Choosing between synchronous and asynchronous

The SDK provides two factory functions: Surreal for synchronous (blocking) connections and AsyncSurreal for asynchronous connections. Both return a connection object with the same set of methods — the async variants must be awaited.

Use Surreal when your application is synchronous or when you are writing scripts, CLI tools, or other non-async code. Use AsyncSurreal when working with async frameworks such as FastAPI, aiohttp, or any asyncio-based application.

		from surrealdb import Surreal

		db = Surreal("ws://localhost:8000")
		db.connect()

		from surrealdb import AsyncSurreal

		db = AsyncSurreal("ws://localhost:8000")
		await db.connect()

Opening a connection

The Surreal and AsyncSurreal factory functions accept a URL and return the appropriate connection class. The SDK inspects the URL scheme to determine whether to use a WebSocket, HTTP, or embedded connection.

You can connect to a remote SurrealDB instance over WebSocket or HTTP.

		from surrealdb import Surreal

		ws_db = Surreal("ws://localhost:8000")
		ws_db.connect()

		http_db = Surreal("https://cloud.surrealdb.com")
		http_db.connect()

		from surrealdb import AsyncSurreal

		ws_db = AsyncSurreal("ws://localhost:8000")
		await ws_db.connect()

		http_db = AsyncSurreal("https://cloud.surrealdb.com")
		await http_db.connect()

You can also run SurrealDB as an embedded in-process database, which is useful for testing or standalone applications.

from surrealdb import Surreal

mem_db = Surreal("mem://")
mem_db.connect()

disk_db = Surreal("surrealkv://path/to/database")
disk_db.connect()

The .connect() method optionally accepts a URL to override the one provided to the factory. See the API reference for parameter details.

Connection string protocols

The URL scheme determines the connection type and its capabilities.

WebSocket and HTTP are used to connect to remote SurrealDB instances, while the embedded protocols run the database engine directly in your Python process. See Embedded databases for more on in-process connections.

Selecting a namespace and database

After connecting, use .use() to select the namespace and database you want to work with. Most operations require a namespace and database to be selected first.

		db.use("surrealdb", "docs")

		await db.use("surrealdb", "docs")

You can call .use() multiple times to switch between namespaces and databases on the same connection.

Using context managers

Python's context manager protocol (with / async with) provides a convenient way to manage connection lifecycle. The connection is automatically opened when entering the context and closed when exiting, even if an exception occurs.

		from surrealdb import Surreal

		with Surreal("ws://localhost:8000") as db:
		    db.use("surrealdb", "docs")
		    db.signin({"username": "root", "password": "root"})
		    results = db.select("users")

		from surrealdb import AsyncSurreal

		async with AsyncSurreal("ws://localhost:8000") as db:
		    await db.use("surrealdb", "docs")
		    await db.signin({"username": "root", "password": "root"})
		    results = await db.select("users")

Using context managers is the recommended approach, as it guarantees resources are released even when errors occur.

Effect of connection protocol on token and session duration

The connection protocol affects how authentication tokens and sessions behave.

WebSocket connections (ws://, wss://) are long-lived and stateful. After the initial authentication, the session persists for the lifetime of the connection. The session duration defaults to NONE, meaning it never expires unless configured otherwise.

HTTP connections (http://, https://) are short-lived and stateless. Each request is independent and requires its own authentication token. The token duration defaults to 1 hour.

You can configure token and session durations using the DURATION clause in the DEFINE ACCESS METHOD or DEFINE USER statements.

Closing a connection

When you are done with a connection, call .close() to release the underlying resources. If you use a context manager, this happens automatically.

		db.close()

		await db.close()

Learn more

• Surreal API reference for complete method signatures and parameters

• Authentication for signing in and managing user sessions

• Embedded databases for running SurrealDB in-process

• Error handling for handling connection and authentication errors