Skip to content

Commit

Permalink
Merge branch 'surrealdb:main' into expose-bind-method
Browse files Browse the repository at this point in the history
  • Loading branch information
@Ce11an
Ce11an authored Aug 26, 2024
2 parents ba11e54 + ffefd8a commit 326b19c
Show file tree
Hide file tree
Showing 19 changed files with 175 additions and 2,884 deletions.
226 changes: 52 additions & 174 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,238 +1,116 @@
<p align="center">
<img width="300" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/icon.png" alt="SurrealDB Icon">
</p>

<br>

<p align="center">
<a href="https://surrealdb.com#gh-dark-mode-only" target="_blank">
<img width="300" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/white/logo.svg" alt="SurrealDB Logo">
</a>
<a href="https://surrealdb.com#gh-light-mode-only" target="_blank">
<img width="300" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/black/logo.svg" alt="SurrealDB Logo">
</a>
<img width=120 src="https://raw.githubusercontent.com/surrealdb/icons/main/surreal.svg" />
&nbsp;
<img width=120 src="https://raw.githubusercontent.com/surrealdb/icons/main/python.svg" />
</p>

<h3 align="center">
<a href="https://surrealdb.com#gh-dark-mode-only" target="_blank">
<img src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/white/text.svg" height="15" alt="SurrealDB">
</a>
<a href="https://surrealdb.com#gh-light-mode-only" target="_blank">
<img src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/black/text.svg" height="15" alt="SurrealDB">
</a>
is the ultimate cloud <br> database for tomorrow's applications
</h3>

<h3 align="center">Develop easier. &nbsp; Build faster. &nbsp; Scale quicker.</h3>
<h3 align="center">The official SurrealDB SDK for Python.</h3>

<br>

<p align="center">
<a href="https://github.com/surrealdb/surrealdb.py"><img src="https://img.shields.io/badge/status-beta-ff00bb.svg?style=flat-square"></a>
&nbsp;
<a href="https://surrealdb.com/docs/integration/libraries/python"><img src="https://img.shields.io/badge/docs-view-44cc11.svg?style=flat-square"></a>
&nbsp;
<a href="https://github.com/surrealdb/surrealdb.py"><img src="https://img.shields.io/badge/license-Apache_License_2.0-00bfff.svg?style=flat-square"></a>
&nbsp;
<a href="https://twitter.com/surrealdb"><img src="https://img.shields.io/badge/twitter-follow_us-1d9bf0.svg?style=flat-square"></a>
&nbsp;
<a href="https://dev.to/surrealdb"><img src="https://img.shields.io/badge/dev-join_us-86f7b7.svg?style=flat-square"></a>
<a href="https://github.com/surrealdb/surrealdb.py"><img src="https://img.shields.io/badge/status-beta-ff00bb.svg?style=flat-square"></a>
&nbsp;
<a href="https://surrealdb.com/docs/integration/libraries/javascript"><img src="https://img.shields.io/badge/docs-view-44cc11.svg?style=flat-square"></a>
&nbsp;
<a href="https://pypi.org/project/surrealdb/"><img src="https://img.shields.io/pypi/v/surrealdb?style=flat-square"></a>
&nbsp;
<a href="https://www.linkedin.com/company/surrealdb/"><img src="https://img.shields.io/badge/linkedin-connect_with_us-0a66c2.svg?style=flat-square"></a>
<a href="https://pypi.org/project/surrealdb/"><img src="https://img.shields.io/pypi/dm/surrealdb?style=flat-square"></a>
&nbsp;
<a href="https://pypi.org/project/surrealdb/"><img src="https://img.shields.io/pypi/pyversions/surrealdb?style=flat-square"></a>
</p>

<p align="center">
<a href="https://surrealdb.com/blog"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/blog.svg" alt="Blog"></a>
&nbsp;
<a href="https://github.com/surrealdb/surrealdb"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/github.svg" alt="Github "></a>
<a href="https://surrealdb.com/discord"><img src="https://img.shields.io/discord/902568124350599239?label=discord&style=flat-square&color=5a66f6"></a>
&nbsp;
<a href="https://www.linkedin.com/company/surrealdb/"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/linkedin.svg" alt="LinkedIn"></a>
&nbsp;
<a href="https://twitter.com/surrealdb"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/twitter.svg" alt="Twitter"></a>
&nbsp;
<a href="https://www.youtube.com/channel/UCjf2teVEuYVvvVC-gFZNq6w"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/youtube.svg" alt="Youtube"></a>
&nbsp;
<a href="https://dev.to/surrealdb"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/dev.svg" alt="Dev"></a>
<a href="https://twitter.com/surrealdb"><img src="https://img.shields.io/badge/twitter-follow_us-1d9bf0.svg?style=flat-square"></a>
&nbsp;
<a href="https://surrealdb.com/discord"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/discord.svg" alt="Discord"></a>
<a href="https://www.linkedin.com/company/surrealdb/"><img src="https://img.shields.io/badge/linkedin-connect_with_us-0a66c2.svg?style=flat-square"></a>
&nbsp;
<a href="https://stackoverflow.com/questions/tagged/surrealdb"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/stack-overflow.svg" alt="StackOverflow"></a>

<a href="https://www.youtube.com/channel/UCjf2teVEuYVvvVC-gFZNq6w"><img src="https://img.shields.io/badge/youtube-subscribe-fc1c1c.svg?style=flat-square"></a>
</p>

# surrealdb.py

The official SurrealDB library for Python.

[See the documentation here](https://surrealdb.com/docs/integration/libraries/python)

## Getting Started
Below is a quick guide on how to get started with SurrealDB in Python.

### Running SurrealDB
Before we can do anything, we need to download SurrealDB and start the server. The easiest, cleanest way to do this
is with [Docker](https://www.docker.com/) abd [docker-compose](https://docs.docker.com/compose/) with the following
docker-compose file:

```yaml
version: '3'
services:
surrealdb:
image: surrealdb/surrealdb
command: start
environment:
- SURREAL_USER=root
- SURREAL_PASS=root
- SURREAL_LOG=trace
ports:
- 8000:8000
```
Here we are pulling the offical SurrealDB image from Docker Hub and starting it with the `start` command. We are also
setting the environment variables `SURREAL_USER` and `SURREAL_PASS` to `root` and `SURREAL_LOG` to `trace`. This will
allow us to connect to the database with the username `root` and password `root` and will set the log level to `trace`.
Finally, we are exposing port `8000` so we can connect to the database.
The official SurrealDB SDK for Python.

Now that we have everything up and running, we can move onto installing the Python library.
## Documentation

### Installing the Python Library
View the SDK documentation [here](https://surrealdb.com/docs/integration/libraries/python).

Right now the library is in beta, so you will need to install it from GitHub with Rust installed on your machine
as Rust will be needed to compile part of the library. Installation for Rust can be found
[here](https://www.rust-lang.org/tools/install). Once Rust is installed, you can install this library with the
following command:
## How to install

```bash
pip install git+https://github.com/surrealdb/surrealdb.py@rust-no-runtime
```sh
pip install surrealdb
```

Installation can take a while as it needs to compile the Rust code. If you want to use the python client in a Docker
build in production you can use a two layered build which will use Rust to compile the library and then copy the
compiled library into a new python image so your production image doesn't need to have Rust installed. Below is an
example of a Dockerfile that will do this for a Flask application:

```dockerfile
FROM rust:latest as builder
RUN apt-get update
RUN apt install python3.9 -y
RUN apt-get install -y python3-dev -y
RUN apt-get install -y python3-pip -y
RUN pip install --upgrade pip setuptools wheel
## Getting started

RUN apt-get install libclang-dev -y
### Running within synchronous code

# Set the working directory to /app
WORKDIR /app
> This example requires SurrealDB to be [installed](https://surrealdb.com/install) and running on port 8000.
# Copy the current directory contents into the container at /app
ADD . /app
# install the python library locally
RUN pip install ./surreal.py/
# or install the python library from github
RUN pip install git+https://github.com/surrealdb/surrealdb.py@rust-no-runtime
# server build
FROM python:3.9
RUN apt-get update \
&& apt-get install -y python3-dev python3-pip \
&& pip install --upgrade pip setuptools wheel \
&& pip install flask gunicorn
WORKDIR /app
# copy the built python packages from the previous stage to the new image
COPY --from=builder /usr/local/lib/python3.9/dist-packages /usr/local/lib/python3.9/site-packages
# copy the python server app code to the new image
COPY --from=builder /app /app
# Run the python server using gunicorn
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5002", "--timeout", "900", "main:app"]
```

You can change the python version and the `CMD` could change depending on your application. Now that we have our
python application installing and running with SurrealDB, we can move onto using the python library.

### Using the blocking Python Library

We can then import the library and create the connection with the following code:
Import the SDK and create the database connection:

```python
from surrealdb import SurrealDB

connection = SurrealDB("ws://localhost:8000/database/namespace")
db = SurrealDB("ws://localhost:8000/database/namespace")
```
Here, we can see that we defined the connection protocol as websocket using `ws://`. We then defined the host as
`localhost` and the port as `8000`. Finally, we defined the database and namespace as `database` and `namespace`.

Here, we can see that we defined the connection protocol as WebSocket using `ws://`. We then defined the host as `localhost` and the port as `8000`.

Finally, we defined the database and namespace as `database` and `namespace`.
We need a database and namespace to connect to SurrealDB.

Now that we have our connection we need to signin using with the following code:
Now that we have our connection we need to signin:

```python
connection.signin({
db.signin({
"username": "root",
"password": "root",
})
```
For our getting started example we are now going to run some simple raw SurrealQL queries to create some users and
then select them. We can then print the outcome of the query with the following code:
We can now run our queries to create some users, select them and print the outcome.

```python
connection.query("CREATE user:tobie SET name = 'Tobie';")
connection.query("CREATE user:jaime SET name = 'Jaime';")
outcome = connection.query("SELECT * FROM user;")
db.query("CREATE user:tobie SET name = 'Tobie';")
db.query("CREATE user:jaime SET name = 'Jaime';")
outcome = db.query("SELECT * FROM user;")
print(outcome)
```

This will give you the following JSON output:

```json
[
{
"id": "user:jaime",
"name": "Jaime"
},
{
"id": "user:tobie",
"name": "Tobie"
}
]
```

### Using the async Python Library

We can then import the library and create the connection with the following code:

```python
from surrealdb import AsyncSurrealDB
### Running within asynchronous code

connection = AsyncSurrealDB("ws://localhost:8000/database/namespace")
await connection.connect()
```
> This example requires SurrealDB to be [installed](https://surrealdb.com/install) and running on port 8000.
Essentially the interface is exactly the same however, the functions are async. Below is a way to run the async code:
The async methods work in the same way, with two main differences:
- Inclusion of `async def / await`.
- You need to call the connect method before signing in.

```python
import asyncio
from surrealdb import AsyncSurrealDB

async def main():
connection = AsyncSurrealDB("ws://localhost:8000/database/namespace")
await connection.connect()
await connection.signin({
db = AsyncSurrealDB("ws://localhost:8000/database/namespace")
await db.connect()
await db.signin({
"username": "root",
"password": "root",
})
await connection.query("CREATE user:tobie SET name = 'Tobie';")
await connection.query("CREATE user:jaime SET name = 'Jaime';")
outcome = await connection.query("SELECT * FROM user;")
await db.query("CREATE user:tobie SET name = 'Tobie';")
await db.query("CREATE user:jaime SET name = 'Jaime';")
outcome = await db.query("SELECT * FROM user;")
print(outcome)


# Run the main function
asyncio.run(main())
```

### Using Jupyter Notebooks

The Python SDK currently only supports the `AsyncSurrealDB` methods.
62 changes: 62 additions & 0 deletions examples/basic_async_example.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
from surrealdb import AsyncSurrealDB

async def main():
"""Example of how to use the SurrealDB client."""
db = AsyncSurrealDB("ws://localhost:8000/database/namespace")

await db.connect()

await db.signin({
"username": "root",
"password": "root",
})

print("Using methods")
print("create: " ,await db.create(
"person",
{
"user": "me",
"pass": "safe",
"marketing": True,
"tags": ["python", "documentation"],
},
))
print("read: ", await db.select("person"))
print("update: ", await db.update("person", {
"user":"you",
"pass":"very_safe",
"marketing": False,
"tags": ["Awesome"]
}))
print("delete: ", await 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
print("Using justawait db.query")
print("create: ", await db.query("""
insert into person {
user: 'me',
pass: 'very_safe',
tags: ['python', 'documentation']
};
"""))
print("read: ", await db.query("select * from person"))

print("update: ", await db.query("""
update person content {
user: 'you',
pass: 'more_safe',
tags: ['awesome']
};
"""))
print( "delete: ", await db.query("delete person"))

if __name__ == "__main__":
import asyncio

asyncio.run(main())
Loading

0 comments on commit 326b19c

Please sign in to comment.