Connection API Reference¶

This module provides connection management for SurrealDB with pooling and registry support.

Connection Classes¶

class surrealengine.connection.SurrealEngineAsyncConnection(url=None, namespace=None, database=None, username=None, password=None, name=None, make_default=False, use_pool=False, pool_size=10, max_idle_time=60, connect_timeout=30, operation_timeout=30, retry_limit=3, retry_delay=1.0, retry_backoff=2.0, validate_on_borrow=True, health_check_interval=30)[source]¶

Bases: object

Asynchronous connection manager for SurrealDB.

This class manages the asynchronous connection to a SurrealDB database, providing methods for connecting, disconnecting, and executing transactions. It also provides access to the database through the db property.

url¶: The URL of the SurrealDB server

namespace¶: The namespace to use

database¶: The database to use

username¶: The username for authentication

password¶: The password for authentication

client¶: The SurrealDB async client instance or ConnectionPoolClient

use_pool¶: Whether to use a connection pool

pool¶: The connection pool if use_pool is True

pool_size¶: The size of the connection pool

max_idle_time¶: Maximum time in seconds a connection can be idle before being closed

__init__(url=None, namespace=None, database=None, username=None, password=None, name=None, make_default=False, use_pool=False, pool_size=10, max_idle_time=60, connect_timeout=30, operation_timeout=30, retry_limit=3, retry_delay=1.0, retry_backoff=2.0, validate_on_borrow=True, health_check_interval=30)[source]¶

Initialize a new SurrealEngineAsyncConnection.

Parameters:

url (str | None) – The URL of the SurrealDB server
namespace (str | None) – The namespace to use
database (str | None) – The database to use
username (str | None) – The username for authentication
password (str | None) – The password for authentication
name (str | None) – The name to register this connection under in the registry
make_default (bool) – Whether to set this connection as the default
use_pool (bool) – Whether to use a connection pool
pool_size (int) – The size of the connection pool
max_idle_time (int) – Maximum time in seconds a connection can be idle before being closed
connect_timeout (int) – Timeout in seconds for establishing a connection
operation_timeout (int) – Timeout in seconds for operations
retry_limit (int) – Maximum number of retries for failed operations
retry_delay (float) – Initial delay in seconds between retries
retry_backoff (float) – Backoff multiplier for retry delay
validate_on_borrow (bool) – Whether to validate connections when borrowing from the pool

async __aenter__()[source]¶

Enter the async context manager.

Returns:: The connection instance
Return type:: SurrealEngineAsyncConnection

async __aexit__(exc_type, exc_val, exc_tb)[source]¶

Exit the async context manager.

Parameters:

exc_type (Type[BaseException] | None) – The exception type, if an exception was raised
exc_val (BaseException | None) – The exception value, if an exception was raised
exc_tb (Any | None) – The exception traceback, if an exception was raised

property db: SurrealEngine¶

Get dynamic table accessor.

Returns:: A SurrealEngine instance for accessing tables dynamically

async connect()[source]¶

Connect to the database.

This method creates a new client if one doesn’t exist. If use_pool is True, it creates a connection pool and a ConnectionPoolClient. Otherwise, it creates a direct connection to the database.

Returns:: The SurrealDB client instance or ConnectionPoolClient
Return type:: Any

async disconnect()[source]¶

Disconnect from the database.

This method closes the client connection if one exists. If use_pool is True, it closes the connection pool.

async transaction(coroutines)[source]¶

Execute multiple operations in a transaction.

This method executes a list of coroutines within a transaction, committing the transaction if all operations succeed or canceling it if any operation fails.

Parameters:: coroutines (list) – List of coroutines to execute in the transaction
Returns:: List of results from the coroutines
Raises:: Exception – If any operation in the transaction fails
Return type:: list

class surrealengine.connection.SurrealEngineSyncConnection(url=None, namespace=None, database=None, username=None, password=None, name=None, make_default=False)[source]¶

Bases: object

Synchronous connection manager for SurrealDB.

This class manages the synchronous connection to a SurrealDB database, providing methods for connecting, disconnecting, and executing transactions. It also provides access to the database through the db property.

url¶: The URL of the SurrealDB server

namespace¶: The namespace to use

database¶: The database to use

username¶: The username for authentication

password¶: The password for authentication

client¶: The SurrealDB sync client instance

__init__(url=None, namespace=None, database=None, username=None, password=None, name=None, make_default=False)[source]¶

Initialize a new SurrealEngineSyncConnection.

Parameters:

url (str | None) – The URL of the SurrealDB server
namespace (str | None) – The namespace to use
database (str | None) – The database to use
username (str | None) – The username for authentication
password (str | None) – The password for authentication
name (str | None) – The name to register this connection under in the registry
make_default (bool) – Whether to set this connection as the default

__enter__()[source]¶

Enter the sync context manager.

Returns:: The connection instance
Return type:: SurrealEngineSyncConnection

__exit__(exc_type, exc_val, exc_tb)[source]¶

Exit the sync context manager.

Parameters:

exc_type (Type[BaseException] | None) – The exception type, if an exception was raised
exc_val (BaseException | None) – The exception value, if an exception was raised
exc_tb (Any | None) – The exception traceback, if an exception was raised

property db: SurrealEngine¶

Get dynamic table accessor.

Returns:: A SurrealEngine instance for accessing tables dynamically

connect()[source]¶

Connect to the database.

This method creates a new client if one doesn’t exist, signs in if credentials are provided, and sets the namespace and database.

Returns:: The SurrealDB client instance
Return type:: Any

disconnect()[source]¶

Disconnect from the database.

This method closes the client connection if one exists.

transaction(callables)[source]¶

Execute multiple operations in a transaction.

This method executes a list of callables within a transaction, committing the transaction if all operations succeed or canceling it if any operation fails.

Parameters:: callables (list) – List of callables to execute in the transaction
Returns:: List of results from the callables
Raises:: Exception – If any operation in the transaction fails
Return type:: list

class surrealengine.connection.BaseSurrealEngineConnection(*args, **kwargs)[source]¶

Bases: Protocol

Protocol defining the interface for SurrealDB connections.

This protocol defines the common interface that both synchronous and asynchronous connections must implement.

url: str | None¶

namespace: str | None¶

database: str | None¶

username: str | None¶

password: str | None¶

client: Any¶

property db: SurrealEngine¶: Get dynamic table accessor.

__init__(*args, **kwargs)¶

Connection Pooling¶

class surrealengine.connection.ConnectionPoolBase(url, namespace=None, database=None, username=None, password=None, pool_size=10, max_idle_time=60, connect_timeout=30, operation_timeout=30, retry_limit=3, retry_delay=1.0, retry_backoff=2.0, validate_on_borrow=True, health_check_interval=30)[source]¶

Bases: ABC

Base class for connection pools.

This abstract class defines the common interface and functionality for both synchronous and asynchronous connection pools.

url¶: The URL of the SurrealDB server

namespace¶: The namespace to use

database¶: The database to use

username¶: The username for authentication

password¶: The password for authentication

pool_size¶: Maximum number of connections in the pool

max_idle_time¶: Maximum time in seconds a connection can be idle before being closed

connect_timeout¶: Timeout in seconds for establishing a connection

operation_timeout¶: Timeout in seconds for operations

retry_limit¶: Maximum number of retries for failed operations

retry_delay¶: Initial delay in seconds between retries

retry_backoff¶: Backoff multiplier for retry delay

validate_on_borrow¶: Whether to validate connections when borrowing from the pool

__init__(url, namespace=None, database=None, username=None, password=None, pool_size=10, max_idle_time=60, connect_timeout=30, operation_timeout=30, retry_limit=3, retry_delay=1.0, retry_backoff=2.0, validate_on_borrow=True, health_check_interval=30)[source]¶

Initialize a new ConnectionPoolBase.

Parameters:

url (str) – The URL of the SurrealDB server
namespace (str | None) – The namespace to use
database (str | None) – The database to use
username (str | None) – The username for authentication
password (str | None) – The password for authentication
pool_size (int) – Maximum number of connections in the pool
max_idle_time (int) – Maximum time in seconds a connection can be idle before being closed
connect_timeout (int) – Timeout in seconds for establishing a connection
operation_timeout (int) – Timeout in seconds for operations
retry_limit (int) – Maximum number of retries for failed operations
retry_delay (float) – Initial delay in seconds between retries
retry_backoff (float) – Backoff multiplier for retry delay
validate_on_borrow (bool) – Whether to validate connections when borrowing from the pool

abstractmethod create_connection()[source]¶

Create a new connection.

Returns:: A new connection
Return type:: Any

abstractmethod validate_connection(connection)[source]¶

Validate a connection.

Parameters:: connection (Any) – The connection to validate
Returns:: True if the connection is valid, False otherwise
Return type:: bool

abstractmethod close_connection(connection)[source]¶

Close a connection.

Parameters:: connection (Any) – The connection to close

abstractmethod get_connection()[source]¶

Get a connection from the pool.

Returns:: A connection from the pool
Return type:: Any

abstractmethod return_connection(connection)[source]¶

Return a connection to the pool.

Parameters:: connection (Any) – The connection to return

abstractmethod close()[source]¶

Close the pool and all connections.

class surrealengine.connection.AsyncConnectionPool(url, namespace=None, database=None, username=None, password=None, pool_size=10, max_idle_time=60, connect_timeout=30, operation_timeout=30, retry_limit=3, retry_delay=1.0, retry_backoff=2.0, validate_on_borrow=True, health_check_interval=30)[source]¶

Bases: ConnectionPoolBase

Asynchronous connection pool for SurrealDB.

This class manages a pool of asynchronous connections to a SurrealDB database. It handles connection creation, validation, and reuse, and provides methods for acquiring and releasing connections.

The connections returned by this pool are wrapped in SurrealEngineAsyncConnection objects, which can be used with the Document class and other SurrealEngine functionality that expects a SurrealEngineAsyncConnection.

pool¶: List of available connections

in_use¶: Dictionary of connections currently in use and their timestamps

lock¶: Asyncio lock for thread-safe operations

closed¶: Whether the pool is closed

Initialize a new AsyncConnectionPool.

Parameters:

url (str) – The URL of the SurrealDB server
namespace (str | None) – The namespace to use
database (str | None) – The database to use
username (str | None) – The username for authentication
password (str | None) – The password for authentication
pool_size (int) – Maximum number of connections in the pool
max_idle_time (int) – Maximum time in seconds a connection can be idle before being closed
connect_timeout (int) – Timeout in seconds for establishing a connection
operation_timeout (int) – Timeout in seconds for operations
retry_limit (int) – Maximum number of retries for failed operations
retry_delay (float) – Initial delay in seconds between retries
retry_backoff (float) – Backoff multiplier for retry delay
validate_on_borrow (bool) – Whether to validate connections when borrowing from the pool

async create_connection()[source]¶

Create a new connection.

Returns:: A new connection wrapped in SurrealEngineAsyncConnection
Raises:: Exception – If the connection cannot be created
Return type:: SurrealEngineAsyncConnection

async validate_connection(connection)[source]¶

Validate a connection.

Parameters:: connection (SurrealEngineAsyncConnection) – The connection to validate (SurrealEngineAsyncConnection)
Returns:: True if the connection is valid, False otherwise
Return type:: bool

async close_connection(connection)[source]¶

Close a connection.

Parameters:: connection (SurrealEngineAsyncConnection) – The connection to close (SurrealEngineAsyncConnection)

async get_connection()[source]¶

Get a connection from the pool.

Returns:

A SurrealEngineAsyncConnection from the pool

Raises:

RuntimeError – If the pool is closed
Exception – If a connection cannot be obtained

Return type:

SurrealEngineAsyncConnection

async return_connection(connection)[source]¶

Return a connection to the pool.

Parameters:: connection (SurrealEngineAsyncConnection) – The connection to return (SurrealEngineAsyncConnection)

async close()[source]¶

Close the pool and all connections.

class surrealengine.connection.SyncConnectionPool(url, namespace=None, database=None, username=None, password=None, pool_size=10, max_idle_time=60, connect_timeout=30, operation_timeout=30, retry_limit=3, retry_delay=1.0, retry_backoff=2.0, validate_on_borrow=True, health_check_interval=30)[source]¶

Bases: ConnectionPoolBase

Synchronous connection pool for SurrealDB.

This class manages a pool of synchronous connections to a SurrealDB database. It handles connection creation, validation, and reuse, and provides methods for acquiring and releasing connections.

The connections returned by this pool are wrapped in SurrealEngineSyncConnection objects, which can be used with the Document class and other SurrealEngine functionality that expects a SurrealEngineSyncConnection.

pool¶: Queue of available connections

in_use¶: Set of connections currently in use

lock¶: Lock for thread-safe operations

closed¶: Whether the pool is closed

Initialize a new SyncConnectionPool.

Parameters:

url (str) – The URL of the SurrealDB server
namespace (str | None) – The namespace to use
database (str | None) – The database to use
username (str | None) – The username for authentication
password (str | None) – The password for authentication
pool_size (int) – Maximum number of connections in the pool
max_idle_time (int) – Maximum time in seconds a connection can be idle before being closed
connect_timeout (int) – Timeout in seconds for establishing a connection
operation_timeout (int) – Timeout in seconds for operations
retry_limit (int) – Maximum number of retries for failed operations
retry_delay (float) – Initial delay in seconds between retries
retry_backoff (float) – Backoff multiplier for retry delay
validate_on_borrow (bool) – Whether to validate connections when borrowing from the pool

create_connection()[source]¶

Create a new connection.

Returns:: A new connection wrapped in SurrealEngineSyncConnection
Raises:: Exception – If the connection cannot be created
Return type:: SurrealEngineSyncConnection

validate_connection(connection)[source]¶

Validate a connection.

Parameters:: connection (SurrealEngineSyncConnection) – The connection to validate (SurrealEngineSyncConnection)
Returns:: True if the connection is valid, False otherwise
Return type:: bool

close_connection(connection)[source]¶

Close a connection.

Parameters:: connection (SurrealEngineSyncConnection) – The connection to close (SurrealEngineSyncConnection)

get_connection()[source]¶

Get a connection from the pool.

Returns:

A SurrealEngineSyncConnection from the pool

Raises:

RuntimeError – If the pool is closed
Exception – If a connection cannot be obtained

Return type:

SurrealEngineSyncConnection

return_connection(connection)[source]¶

Return a connection to the pool.

Parameters:: connection (SurrealEngineSyncConnection) – The connection to return (SurrealEngineSyncConnection)

close()[source]¶

Close the pool and all connections.

Connection Registry¶

class surrealengine.connection.ConnectionRegistry[source]¶

Bases: object

Global connection registry for SurrealDB.

This class provides a centralized registry for managing database connections. It allows setting a default connection and registering named connections that can be retrieved throughout the application.

_default_async_connection¶

The default async connection to use when none is specified

Type:: surrealengine.connection.SurrealEngineAsyncConnection | None

_default_sync_connection¶

The default sync connection to use when none is specified

Type:: surrealengine.connection.SurrealEngineSyncConnection | None

_async_connections¶

Dictionary of named async connections

Type:: Dict[str, surrealengine.connection.SurrealEngineAsyncConnection]

_sync_connections¶

Dictionary of named sync connections

Type:: Dict[str, surrealengine.connection.SurrealEngineSyncConnection]

classmethod set_default_async_connection(connection)[source]¶

Set the default async connection.

Parameters:: connection (SurrealEngineAsyncConnection) – The async connection to set as default

classmethod set_default_sync_connection(connection)[source]¶

Set the default sync connection.

Parameters:: connection (SurrealEngineSyncConnection) – The sync connection to set as default

classmethod set_default_connection(connection)[source]¶

Set the default connection based on its type.

Parameters:: connection (SurrealEngineAsyncConnection | SurrealEngineSyncConnection) – The connection to set as default

classmethod get_default_async_connection()[source]¶

Get the default async connection.

Returns:: The default async connection
Raises:: RuntimeError – If no default async connection has been set
Return type:: SurrealEngineAsyncConnection

classmethod get_default_sync_connection()[source]¶

Get the default sync connection.

Returns:: The default sync connection
Raises:: RuntimeError – If no default sync connection has been set
Return type:: SurrealEngineSyncConnection

classmethod get_default_connection(async_mode=True)[source]¶

Get the default connection based on the mode.

Parameters:: async_mode (bool) – Whether to get the async or sync connection
Returns:: The default connection of the requested type
Raises:: RuntimeError – If no default connection of the requested type has been set
Return type:: SurrealEngineAsyncConnection | SurrealEngineSyncConnection

classmethod add_async_connection(name, connection)[source]¶

Add a named async connection to the registry.

Parameters:

name (str) – The name to register the connection under
connection (SurrealEngineAsyncConnection) – The async connection to register

classmethod add_sync_connection(name, connection)[source]¶

Add a named sync connection to the registry.

Parameters:

name (str) – The name to register the connection under
connection (SurrealEngineSyncConnection) – The sync connection to register

classmethod add_connection(name, connection)[source]¶

Add a named connection to the registry based on its type.

Parameters:

name (str) – The name to register the connection under
connection (SurrealEngineAsyncConnection | SurrealEngineSyncConnection) – The connection to register

classmethod get_async_connection(name)[source]¶

Get a named async connection from the registry.

Parameters:: name (str) – The name of the async connection to retrieve
Returns:: The requested async connection
Raises:: KeyError – If no async connection with the given name exists
Return type:: SurrealEngineAsyncConnection

classmethod get_sync_connection(name)[source]¶

Get a named sync connection from the registry.

Parameters:: name (str) – The name of the sync connection to retrieve
Returns:: The requested sync connection
Raises:: KeyError – If no sync connection with the given name exists
Return type:: SurrealEngineSyncConnection

classmethod get_connection(name, async_mode=True)[source]¶

Get a named connection from the registry based on the mode.

Parameters:

name (str) – The name of the connection to retrieve
async_mode (bool) – Whether to get an async or sync connection

Returns:

The requested connection of the requested type

Raises:

KeyError – If no connection of the requested type with the given name exists

Return type:

SurrealEngineAsyncConnection | SurrealEngineSyncConnection

Utility Functions¶

surrealengine.connection.create_connection(url=None, namespace=None, database=None, username=None, password=None, name=None, make_default=False, async_mode=True, use_pool=False, pool_size=10, max_idle_time=60, connect_timeout=30, operation_timeout=30, retry_limit=3, retry_delay=1.0, retry_backoff=2.0, validate_on_borrow=True, auto_connect=False, health_check_interval=30)[source]¶

Factory function to create a connection of the appropriate type.

Parameters:

url (str | None) – The URL of the SurrealDB server
namespace (str | None) – The namespace to use
database (str | None) – The database to use
username (str | None) – The username for authentication
password (str | None) – The password for authentication
name (str | None) – The name to register this connection under in the registry
make_default (bool) – Whether to set this connection as the default
async_mode (bool) – Whether to create an async or sync connection
use_pool (bool) – Whether to use a connection pool (async_mode only)
pool_size (int) – The size of the connection pool
max_idle_time (int) – Maximum time in seconds a connection can be idle before being closed
connect_timeout (int) – Timeout in seconds for establishing a connection
operation_timeout (int) – Timeout in seconds for operations
retry_limit (int) – Maximum number of retries for failed operations
retry_delay (float) – Initial delay in seconds between retries
retry_backoff (float) – Backoff multiplier for retry delay
validate_on_borrow (bool) – Whether to validate connections when borrowing from the pool
auto_connect (bool) – Whether to automatically connect the connection
health_check_interval (int) – Background health check interval (seconds) for pools

Returns:

A connection of the requested type

Return type:

SurrealEngineAsyncConnection | SurrealEngineSyncConnection

Examples

Basic async connection:

>>> connection = create_connection(
...     url="ws://localhost:8001/rpc",
...     namespace="test_ns",
...     database="test_db",
...     username="root",
...     password="root",
...     make_default=True
... )
>>> # await connection.connect()  # in async context

Sync connection:

>>> connection = create_connection(
...     url="ws://localhost:8001/rpc",
...     namespace="test_ns",
...     database="test_db",
...     username="root",
...     password="root",
...     async_mode=False,
...     make_default=True
... )
>>> connection.connect()

Connection with pooling:

>>> connection = create_connection(
...     url="ws://localhost:8000/rpc",
...     namespace="production",
...     database="app_db",
...     username="app_user",
...     password="secure_password",
...     use_pool=True,
...     pool_size=20,
...     make_default=True
... )

Named connection with context manager:

>>> connection = create_connection(
...     url="ws://db:8000/rpc",
...     namespace="test_ns",
...     database="test_db",
...     username="root",
...     password="root",
...     name="test_connection"
... )
>>> # async with connection:  # in async context
... #     # Use connection
... #     pass

surrealengine.connection.parse_connection_string(connection_string)[source]¶

Parse a connection string into a dictionary of connection parameters.

Supports the following formats: - surrealdb://user:pass@host:port/namespace/database?param1=value1&param2=value2 (maps to ws://) - wss://user:pass@host:port/namespace/database?param1=value1&param2=value2 - ws://user:pass@host:port/namespace/database?param1=value1&param2=value2 - http://user:pass@host:port/namespace/database?param1=value1&param2=value2 - https://user:pass@host:port/namespace/database?param1=value1&param2=value2

Connection string parameters: - pool_size: Maximum number of connections in the pool (default: 10) - max_idle_time: Maximum time in seconds a connection can be idle before being closed (default: 60) - connect_timeout: Timeout in seconds for establishing a connection (default: 30) - operation_timeout: Timeout in seconds for operations (default: 30) - retry_limit: Maximum number of retries for failed operations (default: 3) - retry_delay: Initial delay in seconds between retries (default: 1) - retry_backoff: Backoff multiplier for retry delay (default: 2) - validate_on_borrow: Whether to validate connections when borrowing from the pool (default: true)

Parameters:: connection_string (str) – The connection string to parse
Returns:: A dictionary containing the parsed connection parameters
Raises:: ValueError – If the connection string is invalid
Return type:: Dict[str, Any]

Event Handling¶

class surrealengine.connection.ConnectionEvent[source]¶

Bases: object

Event types for connection events.

This class defines the event types that can be emitted by connections.

CONNECTED = 'connected'¶

DISCONNECTED = 'disconnected'¶

RECONNECTING = 'reconnecting'¶

RECONNECTED = 'reconnected'¶

CONNECTION_FAILED = 'connection_failed'¶

RECONNECTION_FAILED = 'reconnection_failed'¶

CONNECTION_CLOSED = 'connection_closed'¶

class surrealengine.connection.ConnectionEventListener[source]¶

Bases: object

Listener for connection events.

This class defines the interface for connection event listeners.

on_event(event_type, connection, **kwargs)[source]¶

Handle a connection event.

Parameters:

event_type (str) – The type of event
connection (Any) – The connection that emitted the event
**kwargs – Additional event data

class surrealengine.connection.ConnectionEventEmitter[source]¶

Bases: object

Emitter for connection events.

This class provides methods for registering listeners and emitting events.

listeners¶: List of registered event listeners

__init__()[source]¶

Initialize a new ConnectionEventEmitter.

add_listener(listener)[source]¶

Add a listener for connection events.

Parameters:: listener (ConnectionEventListener) – The listener to add

remove_listener(listener)[source]¶

Remove a listener for connection events.

Parameters:: listener (ConnectionEventListener) – The listener to remove

emit_event(event_type, connection, **kwargs)[source]¶

Emit a connection event.

Parameters:

event_type (str) – The type of event
connection (Any) – The connection that emitted the event
**kwargs – Additional event data

Operation Queue¶

class surrealengine.connection.OperationQueue(maxsize=0, drop_policy='block')[source]¶

Bases: object

Queue for operations during reconnection with backpressure and metrics.

This class manages a queue of operations that are waiting for a connection to be reestablished. Once the connection is restored, the operations are executed in the order they were queued.

sync_operations¶: Queue of synchronous operations

async_operations¶: Queue of asynchronous operations

is_reconnecting¶: Whether the connection is currently reconnecting

reconnection_event¶: Event that is set when reconnection is complete

async_reconnection_event¶: Asyncio event that is set when reconnection is complete

__init__(maxsize=0, drop_policy='block')[source]¶

Initialize a new OperationQueue. :param maxsize: Maximum queued operations per list (0 = unbounded) :param drop_policy: One of ‘block’ | ‘drop_oldest’ | ‘error’

start_reconnection()[source]¶

Start the reconnection process.

This method marks the connection as reconnecting and clears the reconnection events.

end_reconnection()[source]¶

End the reconnection process.

This method marks the connection as no longer reconnecting and sets the reconnection events.

queue_operation(operation, args=None, kwargs=None)[source]¶

Queue a synchronous operation.

Parameters:

operation (Callable) – The operation to queue
args (List) – The positional arguments for the operation
kwargs (Dict) – The keyword arguments for the operation

queue_async_operation(operation, args=None, kwargs=None)[source]¶

Queue an asynchronous operation.

Parameters:

operation (Callable) – The operation to queue
args (List) – The positional arguments for the operation
kwargs (Dict) – The keyword arguments for the operation

execute_queued_operations()[source]¶

Execute all queued synchronous operations.

async execute_queued_async_operations()[source]¶

Execute all queued asynchronous operations.

wait_for_reconnection(timeout=None)[source]¶

Wait for reconnection to complete.

Parameters:: timeout (float | None) – Maximum time to wait in seconds
Returns:: True if reconnection completed, False if timed out
Return type:: bool

async wait_for_async_reconnection(timeout=None)[source]¶

Wait for reconnection to complete asynchronously.

Parameters:: timeout (float | None) – Maximum time to wait in seconds
Returns:: True if reconnection completed, False if timed out
Return type:: bool

Reconnection Strategy¶

class surrealengine.connection.ReconnectionStrategy(max_attempts=10, initial_delay=1.0, max_delay=60.0, backoff_factor=2.0)[source]¶

Bases: object

Strategy for reconnecting to the database.

This class provides methods for reconnecting to the database with configurable retry limits and backoff strategies.

max_attempts¶: Maximum number of reconnection attempts

initial_delay¶: Initial delay in seconds between reconnection attempts

max_delay¶: Maximum delay in seconds between reconnection attempts

backoff_factor¶: Backoff multiplier for reconnection delay

__init__(max_attempts=10, initial_delay=1.0, max_delay=60.0, backoff_factor=2.0)[source]¶

Initialize a new ReconnectionStrategy.

Parameters:

max_attempts (int) – Maximum number of reconnection attempts
initial_delay (float) – Initial delay in seconds between reconnection attempts
max_delay (float) – Maximum delay in seconds between reconnection attempts
backoff_factor (float) – Backoff multiplier for reconnection delay

get_delay(attempt)[source]¶

Get the delay for a reconnection attempt.

Parameters:: attempt (int) – The reconnection attempt number (0-based)
Returns:: The delay in seconds for the reconnection attempt
Return type:: float

Retry Strategy¶

class surrealengine.connection.RetryStrategy(retry_limit=3, retry_delay=1.0, retry_backoff=2.0)[source]¶

Bases: object

Strategy for retrying operations with exponential backoff.

This class provides methods for retrying operations with configurable retry limits and backoff strategies.

retry_limit¶: Maximum number of retries

retry_delay¶: Initial delay in seconds between retries

retry_backoff¶: Backoff multiplier for retry delay

__init__(retry_limit=3, retry_delay=1.0, retry_backoff=2.0)[source]¶

Initialize a new RetryStrategy.

Parameters:

retry_limit (int) – Maximum number of retries
retry_delay (float) – Initial delay in seconds between retries
retry_backoff (float) – Backoff multiplier for retry delay

get_retry_delay(attempt)[source]¶

Get the delay for a retry attempt.

Parameters:: attempt (int) – The retry attempt number (0-based)
Returns:: The delay in seconds for the retry attempt
Return type:: float

should_retry(attempt, exception)[source]¶

Determine whether to retry an operation.

Parameters:

attempt (int) – The retry attempt number (0-based)
exception (Exception) – The exception that caused the operation to fail

Returns:

True if the operation should be retried, False otherwise

Return type:

bool

execute_with_retry(operation)[source]¶

Execute an operation with retry.

Parameters:: operation (Callable[[], Any]) – The operation to execute
Returns:: The result of the operation
Raises:: Exception – If the operation fails after all retries
Return type:: Any

async execute_with_retry_async(operation)[source]¶

Execute an asynchronous operation with retry.

Parameters:: operation (Callable[[], Any]) – The asynchronous operation to execute
Returns:: The result of the operation
Raises:: Exception – If the operation fails after all retries
Return type:: Any