The SurrealDB SDK for Python lets you connect to SurrealDB from any Python application. It has a blocking client and an asyncio client, connects to a remote instance over WebSocket or HTTP, and can run an embedded database in the same process. Use it to run SurrealQL queries, read and write records, manage authentication and sessions, and receive changes as they happen with live queries.
The SDK requires Python 3.10 or later, and is available as a PyPI package.
The latest version of the SDK is 3.0.0. It works with SurrealDB 2.x, 3.x and 4.x, and refuses other versions when it connects. The current SurrealDB release is v4.0.0.
If you are upgrading a project from version 2 of the SDK, read Migrating to Python SDK 3.x first. Version 3 changes what several common calls return, and version 2 cannot write datetimes to SurrealDB 4.0.
Getting started
Learn
Concepts
Connecting to SurrealDB - open a connection over WebSocket or HTTP, with timeouts and reconnection
Authentication - sign up, sign in, and keep a token fresh
Executing queries - send SurrealQL and read the results back
Data manipulation - create, select, update, upsert, relate and delete records
Value types - how SurrealDB's types map onto Python ones
Live queries - receive changes as they happen
Transactions - group statements so they succeed or fail together
Error handling - what a failure looks like, and how to catch it
Multiple sessions - run isolated sessions over a single connection
Embedded databases - run SurrealDB in your own process for tests and local use
Streaming results - read the records of a large query as they arrive
Files - store and read files in buckets
Import and export - back up and restore a database as SurrealQL
Contributing
To contribute to the SDK code, submit an Issue or Pull Request in the surrealdb.py repository. To contribute to this documentation, submit an Issue or Pull Request in the docs.surrealdb.com repository.