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