Quickstart

The Python SDK for SurrealDB makes it straightforward to connect to your instance and start querying data. This guide walks you through connecting, authenticating, and performing basic operations.

1. Install the SDK

Follow the installation guide to install the SDK as a dependency in your project. Once installed, import the SDK to start using it.

		from surrealdb import Surreal

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

		from surrealdb import AsyncSurreal

		db = AsyncSurreal("ws://localhost:8000")

The Surreal and AsyncSurreal factory functions accept a connection URL and return the appropriate connection class based on the protocol.

2. Connect to SurrealDB

You can use the .connect() method to open the connection, then .use() to select a namespace and database, and .signin() to authenticate.

Supported connection protocols include:

• WebSocket (ws://, wss://) for long-lived stateful connections

• HTTP (http://, https://) for short-lived stateless connections

• Embedded (mem://, file://, surrealkv://) for in-process databases

		from surrealdb import Surreal

		db = Surreal("ws://localhost:8000")
		db.connect()
		db.use("company_name", "project_name")
		db.signin({"username": "root", "password": "root"})

		from surrealdb import AsyncSurreal

		db = AsyncSurreal("ws://localhost:8000")
		await db.connect()
		await db.use("company_name", "project_name")
		await db.signin({"username": "root", "password": "root"})

You can also use a context manager to automatically close the connection when you are done.

		with Surreal("ws://localhost:8000") as db:
		    db.use("company_name", "project_name")
		    db.signin({"username": "root", "password": "root"})

		async with AsyncSurreal("ws://localhost:8000") as db:
		    await db.use("company_name", "project_name")
		    await db.signin({"username": "root", "password": "root"})

3. Inserting data into SurrealDB

Once connected, you can use the .create() method to create records. Pass a table name or a RecordID as the first argument and the record data as the second.

		from surrealdb import RecordID

		user = db.create("users", {
		    "name": "John",
		    "email": "john@example.com",
		    "age": 32,
		})

		product = db.create(RecordID("products", "apple"), {
		    "name": "Apple",
		    "price": 1.50,
		    "category": "fruit",
		})

		from surrealdb import RecordID

		user = await db.create("users", {
		    "name": "John",
		    "email": "john@example.com",
		    "age": 32,
		})

		product = await db.create(RecordID("products", "apple"), {
		    "name": "Apple",
		    "price": 1.50,
		    "category": "fruit",
		})

4. Retrieving data from SurrealDB

Selecting records

The .select() method retrieves all records from a table, or a single record by its RecordID.

		users = db.select("users")

		apple = db.select(RecordID("products", "apple"))

		users = await db.select("users")

		apple = await db.select(RecordID("products", "apple"))

Running SurrealQL queries

For more advanced use cases, you can use the .query() method to run SurrealQL statements directly. Use the vars parameter to safely pass dynamic values.

		result = db.query(
		    "SELECT name, price FROM products WHERE price < $max_price ORDER BY price",
		    {"max_price": 5.00},
		)

		result = await db.query(
		    "SELECT name, price FROM products WHERE price < $max_price ORDER BY price",
		    {"max_price": 5.00},
		)

5. Closing the connection

Always close the connection when you are done to release resources. If you use a context manager, this happens automatically.

		db.close()

		await db.close()

What's next?

You have learned how to install the SDK, connect to SurrealDB, create records, and retrieve data. There is a lot more you can do with the SDK, including updating and deleting records, handling authentication, live queries, sessions, and transactions.