{"id":24672,"library":"surrealdb","title":"SurrealDB Python Client","description":"Official Python client for SurrealDB, a distributed, multi-model database. Current version 2.0.0, supports Python >=3.10. Active development, releases aligned with SurrealDB server updates.","status":"active","version":"2.0.0","language":"python","source_language":"en","source_url":"https://github.com/surrealdb/surrealdb.py","tags":["database","surrealdb","async","client"],"install":[{"cmd":"pip install surrealdb","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required for WebSocket connection to SurrealDB.","package":"websockets","optional":false}],"imports":[{"note":"In v2.x the class is named 'Surreal', not 'SurrealDB' as in older versions.","wrong":"from surrealdb import SurrealDB","symbol":"Surreal","correct":"from surrealdb import Surreal"},{"note":"Async client class, available since v2.0.","wrong":"","symbol":"AsyncSurreal","correct":"from surrealdb import AsyncSurreal"}],"quickstart":{"code":"import os\nfrom surrealdb import Surreal\n\nurl = os.environ.get('SURREAL_URL', 'ws://localhost:8000/rpc')\nnspace = os.environ.get('SURREAL_NS', 'test')\ndbname = os.environ.get('SURREAL_DB', 'test')\n\nasync def main():\n    async with Surreal(url) as db:\n        await db.signin({'user': 'root', 'pass': 'root'})\n        await db.use(nspace, dbname)\n        # Create a record\n        created = await db.create('person', {'name': 'John', 'age': 30})\n        print(created)\n        # Select all records\n        records = await db.select('person')\n        print(records)\n\nimport asyncio\nasyncio.run(main())","lang":"python","description":"Connect to SurrealDB, authenticate, use namespace/database, create and select records."},"warnings":[{"fix":"Use 'from surrealdb import Surreal' instead of 'from surrealdb import SurrealDB'.","message":"Breaking change in v2.0: The class 'SurrealDB' was renamed to 'Surreal'. Old imports will fail.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Use async/await syntax. Wrap call in asyncio.run().","message":"Breaking change in v2.0: The client is now fully async. Synchronous methods were removed.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Use 'wss://host:port/rpc' for secure connections.","message":"Connecting to an HTTPS endpoint requires specifying 'wss://' instead of 'ws://'. Auto-detection is not supported.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'pip install surrealdb' in the correct Python environment.","cause":"Library not installed or installed in wrong environment.","error":"ModuleNotFoundError: No module named 'surrealdb'"},{"fix":"Use 'from surrealdb import Surreal' instead.","cause":"Using old import path 'from surrealdb import SurrealDB' with v2.x.","error":"AttributeError: module 'surrealdb' has no attribute 'SurrealDB'"},{"fix":"Ensure all Surreal methods are called with 'await' inside an async function.","cause":"Trying to use sync methods or forgetting 'async' on function definition.","error":"TypeError: object Surreal can't be used in 'await' expression"},{"fix":"Verify server is running and URL is correct (e.g., ws://localhost:8000/rpc).","cause":"SurrealDB server not running or wrong URL/port.","error":"ConnectionRefusedError: [Errno 111] Connection refused"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}