PySurrealDB

An unofficial library to connect to SurrealDB.

Minimal dependencies, easy to use.

Getting Started

If you don't already have it, install SurrealDB

Linux:

$ curl -sSf https://install.surrealdb.com | sh
# then
$ surreal start --user test --pass test

Install PySurrealDB

pip install pysurrealdb

Examples

import pysurrealdb as surreal

conn = surreal.connect(user='test', password='test')

conn.create('person', {'name': 'Mike'})
conn.query('select * from person')

You can specify additional connection info either in the connect call, or in a config file.

import pysurrealdb as surreal
conn = surreal.connect(host='surreal.com', port=8000, user='user', password='pass', database='db', namespace='ns')

Both http and websocket are supported. Specify which to use with the client keyword.

conn = surreal.connect(client='websocket')
# Websocket was added as of version 0.3 (requires websockets library). Try http if you run into issues, and please report any bugs you find!

Optional Config file:

# use a configured connection. 
conn = surreal.connection('default')
# Requires pysurrealdb.json file. Place it in your root directory, or specify the file location with the env variable 'PYSURREALDB_CONFIG'.

Example pysurrealdb.json:
{
    "connections": {
        "default": {
            "host": "localhost",
            "port": 8000,
            "user": "test",
            "password": "test"
            "database": "test",
            "namespace": "test",
            "client": "http",
        }
    }
}

# when using a config file, you do not even need to connect, you can access most functions directly:
import pysurrealdb as surreal

surreal.query('select * from test') # uses the last connection from connect() or the default connection if connect() has not been called.

Query Builder

You can write queries using Laravel and Orator style syntax:

import pysurrealdb as surreal
conn = surreal.connection()

# setup data
conn.drop('person')
conn.insert('person', [{'name': 'Mike', 'age': 31}, {'name':'Mr P'}])

# query builder examples
first_person = conn.table('person').where('name', 'Mike').first()

adults = conn.table('person').where('age', '>=', 18).order_by('age', 'desc').limit(10).get()

Methods

Some of the basic methods available:

query(sql)
get(table, id='')
insert(table, data)
create(table, data)
update(table, data)
upsert(table, data)
delete(table, id)
drop(table)
relate(noun, verb, noun2, data={})

# Most methods accept a table or table:id as the main arguement. The data is also checked for an ID when relevant.

This project is a work in progress. Questions and feedback are welcome! Please create an issue or use the gitter chat link at the top. Thanks!

aurelion314 / pysurrealdb