https://github.com/surrealdb/surrealdb.py
SurrealDB SDK for Python
https://github.com/surrealdb/surrealdb.py
database database-connector database-sdk iot-database python python-library python-module realtime-database surreal surrealdb
Last synced: 4 months ago
JSON representation
SurrealDB SDK for Python
- Host: GitHub
- URL: https://github.com/surrealdb/surrealdb.py
- Owner: surrealdb
- License: apache-2.0
- Created: 2022-04-07T16:16:39.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-03T10:47:50.000Z (4 months ago)
- Last Synced: 2025-03-07T05:02:07.384Z (4 months ago)
- Topics: database, database-connector, database-sdk, iot-database, python, python-library, python-module, realtime-database, surreal, surrealdb
- Language: Python
- Homepage: https://surrealdb.com
- Size: 74.6 MB
- Stars: 207
- Watchers: 22
- Forks: 58
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-surreal - surrealdb.py - <a href="https://surrealdb.com#gh-dark-mode-only" target="_blank"><img src="/img/white/text.svg" height="12" alt="SurrealDB"></a> <a href="https://surrealdb.com#gh-light-mode-only" target="_blank"><img src="/img/black/text.svg" height="12" alt="SurrealDB"></a> official driver for Python. (Client libraries)
README
The official SurrealDB SDK for Python.
# surrealdb.py
The official SurrealDB SDK for Python.
## Documentation
View the SDK documentation [here](https://surrealdb.com/docs/integration/libraries/python).
## How to install
```sh
pip install surrealdb
```
# Quick start
In this short guide, you will learn how to install, import, and initialize the SDK, as well as perform the basic data manipulation queries.
This guide uses the `Surreal` class, but this example would also work with `AsyncSurreal` class, with the addition of `await` in front of the class methods.
## Install
```sh
pip install surrealdb
```
## Learn the basics
```python
# Import the Surreal class
from surrealdb import Surreal
# Using a context manger to automatically connect and disconnect
with Surreal("ws://localhost:8000/rpc") as db:
db.signin({"username": 'root', "password": 'root'})
db.use("namepace_test", "database_test")
# Create a record in the person table
db.create(
"person",
{
"user": "me",
"password": "safe",
"marketing": True,
"tags": ["python", "documentation"],
},
)
# Read all the records in the table
print(db.select("person"))
# Update all records in the table
print(db.update("person", {
"user":"you",
"password":"very_safe",
"marketing": False,
"tags": ["Awesome"]
}))
# Delete all records in the table
print(db.delete("person"))
# You can also use the query method
# doing all of the above and more in SurrealQl
# In SurrealQL you can do a direct insert
# and the table will be created if it doesn't exist
# Create
db.query("""
insert into person {
user: 'me',
password: 'very_safe',
tags: ['python', 'documentation']
};
""")
# Read
print(db.query("select * from person"))
# Update
print(db.query("""
update person content {
user: 'you',
password: 'more_safe',
tags: ['awesome']
};
"""))
# Delete
print(db.query("delete person"))
```
## Next steps
Now that you have learned the basics of the SurrealDB SDK for Python, you can learn more about the SDK and its methods [in the methods section](https://surrealdb.com/docs/sdk/python/methods) and [data types section](https://surrealdb.com/docs/sdk/python/data-types).
## Contributing
Contributions to this library are welcome! If you encounter issues, have feature requests, or
want to make improvements, feel free to open issues or submit pull requests.
If you want to contribute to the Github repo please read the general contributing guidelines on concepts such as how to create a pull requests [here](https://github.com/surrealdb/surrealdb.py/blob/main/CONTRIBUTING.md).
## Getting the repo up and running
To contribute, it's a good idea to get the repo up and running first. We can do this by running the tests. If the tests pass, your `PYTHONPATH` works and the client is making successful calls to the database. To do this we must run the database with the following command:
```bash
# if the docker-compose binary is installed
docker-compose up -d
# if you are running docker compose directly through docker
docker compose up -d
```
Now that the database is running, we can enter a terminal session with all the requirements installed and `PYTHONPATH` configured with the command below:
```bash
bash scripts/term.sh
```
You will now be running an interactive terminal through a python virtual environment with all the dependencies installed. We can now run the tests with the following command:
```bash
python -m unittest discover
```
The number of tests might increase but at the time of writing this you should get a printout like the one below:
```bash
.........................................................................................................................................Error in live subscription: sent 1000 (OK); no close frame received
..........................................................................................
----------------------------------------------------------------------
Ran 227 tests in 6.313s
OK
```
Finally, we clean up the database with the command below:
```bash
# if the docker-compose binary is installed
docker-compose down
# if you are running docker compose directly through docker
docker compose down
```
To exit the terminal session merely execute the following command:
```bash
exit
```
And there we have it, our tests are passing.