Drivers

coodie uses a pluggable driver system. The driver registry manages connections to one or more Cassandra / ScyllaDB clusters.

Driver Registry

class coodie.drivers.AbstractDriver

Bases: ABC

Abstract base class for coodie execution backends.

needs_row_validation: bool = False
abstractmethod execute(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None, fetch_size: int | None = None, paging_state: bytes | None = None) → list[dict[str, Any]]

Execute stmt with params; return rows as a list of dicts.

abstractmethod sync_table(table: str, keyspace: str, cols: list[Any], table_options: dict[str, Any] | None = None, dry_run: bool = False, drop_removed_indexes: bool = False) → list[str]

Idempotent CREATE TABLE + ALTER TABLE ADD for new columns.

Returns the list of CQL statements that were (or would be) executed. When dry_run is True the database is not modified.

abstractmethod close() → None

Release sync resources.

abstractmethod async execute_async(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None, fetch_size: int | None = None, paging_state: bytes | None = None) → list[dict[str, Any]]

Async version of execute().

abstractmethod async sync_table_async(table: str, keyspace: str, cols: list[Any], table_options: dict[str, Any] | None = None, dry_run: bool = False, drop_removed_indexes: bool = False) → list[str]

Async version of sync_table().

execute_one(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None) → Any

Execute stmt and return the first column of the first row, or None.

async execute_one_async(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None) → Any

Async version of execute_one().

abstractmethod async close_async() → None

Release async resources.

class coodie.drivers.LazyDriver(hosts: list[str] | None, keyspace: str | None, ssl_context: SSLContext | None, kwargs: dict[str, Any])

Bases: AbstractDriver

Driver proxy that defers Cassandra/ScyllaDB connection until first use.

Created by init_coodie(..., lazy=True). The underlying CassandraDriver is instantiated on the first call to execute(), execute_async(), sync_table(), or sync_table_async().

execute(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None, fetch_size: int | None = None, paging_state: bytes | None = None) → list[dict[str, Any]]

Execute stmt with params; return rows as a list of dicts.

sync_table(table: str, keyspace: str, cols: list[Any], table_options: dict[str, Any] | None = None, dry_run: bool = False, drop_removed_indexes: bool = False) → list[str]

Idempotent CREATE TABLE + ALTER TABLE ADD for new columns.

Returns the list of CQL statements that were (or would be) executed. When dry_run is True the database is not modified.

close() → None

Release sync resources.

async execute_async(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None, fetch_size: int | None = None, paging_state: bytes | None = None) → list[dict[str, Any]]

Async version of execute().

async sync_table_async(table: str, keyspace: str, cols: list[Any], table_options: dict[str, Any] | None = None, dry_run: bool = False, drop_removed_indexes: bool = False) → list[str]

Async version of sync_table().

async close_async() → None

Release async resources.

coodie.drivers.get_driver(name: str | None = None) → AbstractDriver
coodie.drivers.init_coodie(hosts: list[str] | None = None, session: Any | None = None, keyspace: str | None = None, driver_type: str = 'scylla', name: str = 'default', ssl_context: SSLContext | None = None, lazy: bool = False, compression: str | bool | None = None, speculative_execution_policy: Any | None = None, **kwargs: Any) → AbstractDriver

Create a driver, register it under name, and make it the default.

This is the synchronous entry point (re-exported as coodie.sync.init_coodie). It can be called from plain sync code; for driver_type="acsylla" and "python-rs" with hosts=, the session is created on a dedicated background event loop, so the returned driver supports both the sync and async APIs (the “sync bridge”).

Parameters:

  • hosts – Contact points. For "scylla"/"cassandra" defaults to ["127.0.0.1"] when neither hosts nor session is given. For "acsylla" and "python-rs" either hosts or session is required.

  • session – Pre-created driver session to wrap (bring your own session). When given, hosts and **kwargs are ignored. An acsylla session passed here is not on the background loop: AcsyllaDriver emits a UserWarning and sync calls may hang.

  • keyspace – Default keyspace. Also passed to Cluster.connect() (scylla/cassandra) and create_session() (acsylla).

  • driver_type – "scylla" (default), "cassandra", "acsylla" or "python-rs". "scylla" and "cassandra" both use CassandraDriver; they differ only in which package provides the cassandra module.

  • name – Registry name, used with get_driver(name) for multi-cluster setups. The new driver always becomes the default.

  • ssl_context – ssl.SSLContext forwarded to Cluster(). scylla/cassandra only.

  • lazy – When True (and no session), return a LazyDriver that connects on first use. scylla/cassandra only. compression and speculative_execution_policy are not applied in lazy mode; pass them via **kwargs instead.

  • compression – Forwarded to Cluster(compression=...) for scylla/cassandra (non-lazy), and to .compression(...) for python-rs (a scylla.session.Compression value).

  • speculative_execution_policy – Forwarded to Cluster(speculative_execution_policy=...). scylla/cassandra only, non-lazy.

  • **kwargs – Extra connection options, used only when coodie creates the session: Cluster(hosts, **kwargs) for scylla/cassandra, acsylla.create_cluster(hosts, **kwargs) for acsylla, and one SessionBuilder method call per kwarg for python-rs (tcp_nodelay=False calls .tcp_nodelay(False); port is applied to every contact point instead).

Returns:

The registered driver.

Raises:

  • ConfigurationError – Unknown driver_type, or acsylla/python-rs without hosts or session.

  • ImportError – The selected driver package is not installed.

async coodie.drivers.init_coodie_async(hosts: list[str] | None = None, session: Any | None = None, keyspace: str | None = None, driver_type: str = 'scylla', name: str = 'default', ssl_context: SSLContext | None = None, ssl_enabled: bool | None = None, ssl_trusted_cert: str | None = None, ssl_cert: str | None = None, ssl_private_key: str | None = None, ssl_verify_flags: int | None = None, **kwargs: Any) → AbstractDriver

Async variant of init_coodie() (re-exported as coodie.aio.init_coodie).

Use it from inside a running event loop. For "acsylla" and "python-rs" with hosts=, the session is created on a dedicated background loop (same as init_coodie()), so the driver works from both sync and async code. With session=, the driver runs the async API directly on the caller’s loop. Every other case ("scylla"/"cassandra") delegates to init_coodie(), which connects synchronously.

Parameters:

  • hosts – Contact points. See init_coodie().

  • session – Pre-created driver session to wrap. When given, hosts and **kwargs are ignored.

  • keyspace – Default keyspace.

  • driver_type – "scylla" (default), "cassandra", "acsylla" or "python-rs".

  • name – Registry name. The new driver always becomes the default.

  • ssl_context – ssl.SSLContext for scylla/cassandra.

  • ssl_enabled – acsylla only (with hosts); forwarded to acsylla.create_cluster().

  • ssl_trusted_cert – acsylla only (with hosts); PEM CA certificate.

  • ssl_cert – acsylla only (with hosts); PEM client certificate.

  • ssl_private_key – acsylla only (with hosts); PEM client key.

  • ssl_verify_flags – acsylla only (with hosts); certificate verification flags.

  • **kwargs – Extra connection options, as in init_coodie(). For scylla/cassandra they are passed through to init_coodie(), so lazy, compression and speculative_execution_policy can be given here too.

Returns:

The registered driver.

Raises:

  • ConfigurationError – Unknown driver_type, or acsylla/python-rs without hosts or session.

  • ImportError – The selected driver package is not installed.

coodie.drivers.register_driver(name: str, driver: AbstractDriver, default: bool = False) → None

Abstract Base Driver

class coodie.drivers.base.AbstractDriver

Bases: ABC

Abstract base class for coodie execution backends.

needs_row_validation: bool = False
abstractmethod execute(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None, fetch_size: int | None = None, paging_state: bytes | None = None) → list[dict[str, Any]]

Execute stmt with params; return rows as a list of dicts.

abstractmethod sync_table(table: str, keyspace: str, cols: list[Any], table_options: dict[str, Any] | None = None, dry_run: bool = False, drop_removed_indexes: bool = False) → list[str]

Idempotent CREATE TABLE + ALTER TABLE ADD for new columns.

Returns the list of CQL statements that were (or would be) executed. When dry_run is True the database is not modified.

abstractmethod close() → None

Release sync resources.

abstractmethod async execute_async(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None, fetch_size: int | None = None, paging_state: bytes | None = None) → list[dict[str, Any]]

Async version of execute().

abstractmethod async sync_table_async(table: str, keyspace: str, cols: list[Any], table_options: dict[str, Any] | None = None, dry_run: bool = False, drop_removed_indexes: bool = False) → list[str]

Async version of sync_table().

execute_one(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None) → Any

Execute stmt and return the first column of the first row, or None.

async execute_one_async(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None) → Any

Async version of execute_one().

abstractmethod async close_async() → None

Release async resources.

CassandraDriver (scylla-driver / cassandra-driver)

class coodie.drivers.cassandra.CassandraDriver(session: Any, default_keyspace: str | None = None)

Bases: AbstractDriver

Driver backed by cassandra-driver / scylla-driver.

execute(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None, fetch_size: int | None = None, paging_state: bytes | None = None) → list[dict[str, Any]]

Execute stmt with params; return rows as a list of dicts.

sync_table(table: str, keyspace: str, cols: list[Any], table_options: dict[str, Any] | None = None, dry_run: bool = False, drop_removed_indexes: bool = False) → list[str]

Idempotent CREATE TABLE + ALTER TABLE ADD for new columns.

Returns the list of CQL statements that were (or would be) executed. When dry_run is True the database is not modified.

execute_one(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None) → Any

Execute stmt and return the first column of the first row, or None.

async execute_one_async(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None) → Any

Async version of execute_one().

close() → None

Release sync resources.

async execute_async(stmt: str, params: list[Any], consistency: str | None = None, timeout: float | None = None, fetch_size: int | None = None, paging_state: bytes | None = None) → list[dict[str, Any]]

Async version of execute().

async sync_table_async(table: str, keyspace: str, cols: list[Any], table_options: dict[str, Any] | None = None, dry_run: bool = False, drop_removed_indexes: bool = False) → list[str]

Async version of sync_table().

async close_async() → None

Release async resources.