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.
| Scheme | Connection type | Description |
|---|
ws:// | WebSocket | Unencrypted stateful connection |
wss:// | WebSocket | TLS-encrypted stateful connection |
http:// | HTTP | Unencrypted stateless connection |
https:// | HTTP | TLS-encrypted stateless connection |
mem:// | Embedded (in-memory) | In-process database that does not persist data |
file:// | Embedded (on-disk) | In-process database backed by SurrealKV storage |
surrealkv:// | Embedded (on-disk) | In-process database backed by SurrealKV storage |
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.
Learn more about token and session duration in the security best practices documentation.
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.
Learn more
