Skip to content

Installation Guide

This guide covers installing surql and setting up SurrealDB for development.

Table of Contents

Requirements

Python

  • Python 3.12 or higher
  • pip or uv package manager

Check your Python version:

python --version
# or
python3 --version

SurrealDB

  • SurrealDB 1.0 or higher

Installing surql

Using pip

pip install oneiriq-surql

uv is a fast Python package installer and resolver.

# Install uv if you haven't already
pip install uv

# Add surql to your project
uv add oneiriq-surql

From Source

For development or to use the latest features:

# Clone the repository
git clone https://github.com/Oneiriq/surql-py.git
cd surql

# Install with uv
uv sync

# Or with pip
pip install -e .

Installing SurrealDB

macOS

Using Homebrew:

brew install surrealdb/tap/surreal

Linux

curl -sSf https://install.surrealdb.com | sh

Windows

Using PowerShell:

iwr https://windows.surrealdb.com -useb | iex

Using WSL or Git Bash:

curl -sSf https://install.surrealdb.com | sh

Docker

docker pull surrealdb/surrealdb:latest

Verify SurrealDB Installation

surreal version

You should see output similar to:

surreal 1.0.0 for linux on x86_64

Running SurrealDB

Local Development

Start SurrealDB in memory mode (data is not persisted):

surreal start --log trace --user root --pass root memory

Start with file storage:

surreal start --log trace --user root --pass root file://mydb.db

Start with RocksDB (recommended for production):

surreal start --log trace --user root --pass root rocksdb://mydb

Using Docker

docker run --rm --pull always -p 8000:8000 \
  surrealdb/surrealdb:latest \
  start --user root --pass root memory

With persistent storage:

docker run --rm --pull always -p 8000:8000 \
  -v $(pwd)/mydb:/mydb \
  surrealdb/surrealdb:latest \
  start --user root --pass root file://mydb/db.surreal

Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  surrealdb:
    image: surrealdb/surrealdb:latest
    ports:
      - "8000:8000"
    command: start --user root --pass root memory
    # For persistent storage:
    # volumes:
    #   - ./data:/data
    # command: start --user root --pass root file://data/db.surreal

Start the service:

docker-compose up -d

Configuration

Environment Variables

Create a .env file in your project root:

# Database Connection
SURREAL_URL=ws://localhost:8000/rpc
SURREAL_NAMESPACE=test
SURREAL_DATABASE=test
SURREAL_USERNAME=root
SURREAL_PASSWORD=root

# Connection Pool
SURREAL_MAX_CONNECTIONS=10

# Retry Configuration
SURREAL_RETRY_MAX_ATTEMPTS=3
SURREAL_RETRY_MIN_WAIT=1.0
SURREAL_RETRY_MAX_WAIT=10.0
SURREAL_RETRY_MULTIPLIER=2.0

# Logging
LOG_LEVEL=INFO

Python Configuration

Create a configuration file in your project:

from surql.connection.config import ConnectionConfig

config = ConnectionConfig(
  url='ws://localhost:8000/rpc',
  namespace='test',
  database='test',
  username='root',
  password='root',
  max_connections=10,
)

Loading from Environment

surql automatically loads configuration from environment variables:

from surql.settings import get_db_config

# Loads from environment variables
config = get_db_config()

Verification

Verify surql Installation

surql --help

You should see the CLI help output:

Usage: surql [OPTIONS] COMMAND [ARGS]...

  surql - Code-first database toolkit for SurrealDB.

Options:
  --verbose, -v  Enable verbose logging
  --help         Show this message and exit.

Commands:
  db       Database management commands
  migrate  Database migration commands
  schema   Schema inspection commands
  version  Show surql version information

Test Database Connection

Create a test script test_connection.py:

import asyncio
from surql.connection.client import get_client
from surql.connection.config import ConnectionConfig

async def test_connection():
  config = ConnectionConfig(
    url='ws://localhost:8000/rpc',
    namespace='test',
    database='test',
    username='root',
    password='root',
  )

  async with get_client(config) as client:
    result = await client.execute('SELECT * FROM $session')
    print('Connected successfully!')
    print(f'Session info: {result}')

if __name__ == '__main__':
  asyncio.run(test_connection())

Run the test:

python test_connection.py

Using the CLI

# Check database connection
surql db ping

# Show database info
surql db info

Project Setup

Initialize Migration Directory

Create a migrations directory in your project:

mkdir migrations

Create First Migration

surql migrate create "Initial setup"

This creates a migration file in migrations/ with the current timestamp.

Project Structure

Your project should look like this:

my-project/
├── .env                 # Environment variables
├── migrations/          # Migration files
│   └── 20260102_120000_initial_setup.py
├── schemas/             # Schema definitions (optional)
│   └── user.py
└── main.py             # Your application

Troubleshooting

Connection Refused

If you get a connection refused error:

  1. Ensure SurrealDB is running:

    surreal version

  2. Check the URL matches your SurrealDB instance:

    # Default is ws://localhost:8000/rpc

  3. Verify port 8000 is not blocked by firewall

Import Errors

If you get import errors:

# Reinstall surql
pip install --force-reinstall surql

# Or with uv
uv sync --reinstall

Permission Errors

If you get permission errors on Linux/macOS:

# Run with sudo (not recommended for pip)
sudo pip install oneiriq-surql

# Or use virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install oneiriq-surql

SurrealDB Not Found

If surreal command is not found after installation:

  1. Check if the binary is in your PATH:
which surreal  # Linux/macOS
where surreal  # Windows

  1. Add to PATH or use full path to binary

  2. On Windows, restart your terminal after installation

Next Steps

Now that you have surql installed and configured:

  1. Follow the Quick Start Tutorial to create your first schema and migration
  2. Read the Schema Definition Guide to learn about schema features
  3. Explore the Query Builder & ORM Guide for data operations
  4. Check out the Examples for working code samples

Additional Resources