CockroachDB¶

CockroachDB adapters with automatic transaction retry logic. Available in asyncpg and psycopg variants.

CockroachDB + AsyncPG¶

Configuration¶

class sqlspec.adapters.cockroach_asyncpg.CockroachAsyncpgConfig[source]¶

Bases: AsyncDatabaseConfig[PoolConnectionProxy, Pool, CockroachAsyncpgDriver]

Configuration for CockroachDB using AsyncPG.

driver_type¶: alias of CockroachAsyncpgDriver

connection_type¶: alias of PoolConnectionProxy

__init__(*, connection_config=None, connection_instance=None, migration_config=None, statement_config=None, driver_features=None, bind_key=None, extension_config=None, observability_config=None, **kwargs)[source]¶

async create_connection()[source]¶

Create a database connection.

Return type:: PoolConnectionProxy

provide_connection(*args, **kwargs)[source]¶

Provide a database connection context manager.

Return type:: CockroachAsyncpgConnectionContext

provide_session(*_args, statement_config=None, follower_reads=None, staleness=None, **_kwargs)[source]¶

Provide a database session context manager.

Return type:: CockroachAsyncpgSessionContext

async provide_pool(*args, **kwargs)[source]¶

Provide pool instance.

Return type:: Pool

get_signature_namespace()[source]¶

Get the signature namespace for this database configuration.

Returns a dictionary of type names to objects (classes, functions, or other callables) that should be registered with Litestar’s signature namespace to prevent serialization attempts on database-specific structures.

Return type:: dict[str, typing.Any]
Returns:: Dictionary mapping type names to objects.

get_event_runtime_hints()[source]¶

Return default event runtime hints for this configuration.

Return type:: EventRuntimeHints

class sqlspec.adapters.cockroach_asyncpg.config.CockroachAsyncpgPoolConfig[source]¶

Bases: CockroachAsyncpgConnectionConfig

AsyncPG pool parameters for CockroachDB.

Driver¶

class sqlspec.adapters.cockroach_asyncpg.CockroachAsyncpgDriver[source]¶

Bases: AsyncpgDriver

CockroachDB AsyncPG driver with retry support.

__init__(connection, statement_config=None, driver_features=None)[source]¶

Initialize driver adapter with connection and configuration.

Parameters:

connection¶ (PoolConnectionProxy) – Database connection instance
statement_config¶ (StatementConfig | None) – Statement configuration for the driver
driver_features¶ (dict[str, typing.Any] | None) – Driver-specific features like extensions, secrets, and connection callbacks
observability¶ – Optional runtime handling lifecycle hooks, observers, and spans

async dispatch_execute(cursor, statement)[source]¶

Execute single SQL statement.

Handles both SELECT queries and non-SELECT operations.

Parameters:

cursor¶ (PoolConnectionProxy) – AsyncPG connection object
statement¶ (SQL) – SQL statement to execute

Return type:

ExecutionResult

Returns:

ExecutionResult with statement execution details

async dispatch_execute_many(cursor, statement)[source]¶

Execute SQL with multiple parameter sets using AsyncPG’s executemany.

Parameters:

cursor¶ (PoolConnectionProxy) – AsyncPG connection object
statement¶ (SQL) – SQL statement with multiple parameter sets

Return type:

ExecutionResult

Returns:

ExecutionResult with batch execution details

async dispatch_execute_script(cursor, statement)[source]¶

Execute SQL script with statement splitting and parameter handling.

Parameters:

cursor¶ (PoolConnectionProxy) – AsyncPG connection object
statement¶ (SQL) – SQL statement containing multiple statements

Return type:

ExecutionResult

Returns:

ExecutionResult with script execution details

handle_database_exceptions()[source]¶

Handle database exceptions with PostgreSQL error codes.

Return type:: CockroachAsyncpgExceptionHandler

property data_dictionary: CockroachAsyncpgDataDictionary¶

Get the data dictionary for this driver.

Returns:: Data dictionary instance for metadata queries

Retry Configuration¶

class sqlspec.adapters.cockroach_asyncpg.core.CockroachAsyncpgRetryConfig[source]¶

Bases: object

CockroachDB asyncpg transaction retry configuration.

classmethod from_features(driver_features)[source]¶

Build retry config from driver feature mappings.

Return type:: CockroachAsyncpgRetryConfig

__init__(max_retries=10, base_delay_ms=50.0, max_delay_ms=5000.0, enable_logging=True)¶

CockroachDB + Psycopg¶

Sync Configuration¶

class sqlspec.adapters.cockroach_psycopg.CockroachPsycopgSyncConfig[source]¶

Bases: SyncDatabaseConfig[CrdbConnection, ConnectionPool, CockroachPsycopgSyncDriver]

Configuration for CockroachDB synchronous connections using psycopg.

driver_type¶: alias of CockroachPsycopgSyncDriver

__init__(*, connection_config=None, connection_instance=None, migration_config=None, statement_config=None, driver_features=None, bind_key=None, extension_config=None, observability_config=None, **kwargs)[source]¶

create_connection()[source]¶

Create a database connection.

Return type:: CrdbConnection

provide_connection(*args, **kwargs)[source]¶

Provide a database connection context manager.

Return type:: CockroachPsycopgSyncConnectionContext

provide_session(*_args, statement_config=None, follower_reads=None, staleness=None, **_kwargs)[source]¶

Provide a database session context manager.

Return type:: CockroachPsycopgSyncSessionContext

provide_pool(*args, **kwargs)[source]¶

Provide pool instance.

Return type:: ConnectionPool

get_signature_namespace()[source]¶

Get the signature namespace for this database configuration.

Return type:: dict[str, typing.Any]
Returns:: Dictionary mapping type names to objects.

get_event_runtime_hints()[source]¶

Return default event runtime hints for this configuration.

Return type:: EventRuntimeHints

Async Configuration¶

class sqlspec.adapters.cockroach_psycopg.CockroachPsycopgAsyncConfig[source]¶

Bases: AsyncDatabaseConfig[AsyncCrdbConnection, AsyncConnectionPool, CockroachPsycopgAsyncDriver]

Configuration for CockroachDB async connections using psycopg.

driver_type¶: alias of CockroachPsycopgAsyncDriver

__init__(*, connection_config=None, connection_instance=None, migration_config=None, statement_config=None, driver_features=None, bind_key=None, extension_config=None, observability_config=None, **kwargs)[source]¶

async create_connection()[source]¶

Create a database connection.

Return type:: AsyncCrdbConnection

provide_connection(*args, **kwargs)[source]¶

Provide a database connection context manager.

Return type:: CockroachPsycopgAsyncConnectionContext

provide_session(*_args, statement_config=None, follower_reads=None, staleness=None, **_kwargs)[source]¶

Provide a database session context manager.

Return type:: CockroachPsycopgAsyncSessionContext

async provide_pool(*args, **kwargs)[source]¶

Provide pool instance.

Return type:: AsyncConnectionPool

get_signature_namespace()[source]¶

Get the signature namespace for this database configuration.

Return type:: dict[str, typing.Any]
Returns:: Dictionary mapping type names to objects.

get_event_runtime_hints()[source]¶

Return default event runtime hints for this configuration.

Return type:: EventRuntimeHints

Sync Driver¶

class sqlspec.adapters.cockroach_psycopg.CockroachPsycopgSyncDriver[source]¶

Bases: PsycopgSyncDriver

CockroachDB sync driver using psycopg.crdb.

__init__(connection, statement_config=None, driver_features=None)[source]¶

dispatch_execute(cursor, statement)[source]¶

Execute single SQL statement.

Parameters:

cursor¶ (Any) – Database cursor
statement¶ (SQL) – SQL statement to execute

Return type:

ExecutionResult

Returns:

ExecutionResult with statement execution details

dispatch_execute_many(cursor, statement)[source]¶

Execute SQL with multiple parameter sets.

Parameters:

cursor¶ (Any) – Database cursor
statement¶ (SQL) – SQL statement with parameter list

Return type:

ExecutionResult

Returns:

ExecutionResult with batch execution details

dispatch_execute_script(cursor, statement)[source]¶

Execute SQL script with multiple statements.

Parameters:

cursor¶ (Any) – Database cursor
statement¶ (SQL) – SQL statement containing multiple commands

Return type:

ExecutionResult

Returns:

ExecutionResult with script execution details

handle_database_exceptions()[source]¶

Handle database-specific exceptions and wrap them appropriately.

Return type:: CockroachPsycopgSyncExceptionHandler

property data_dictionary: CockroachPsycopgSyncDataDictionary¶

Get the data dictionary for this driver.

Returns:: Data dictionary instance for metadata queries

Async Driver¶

class sqlspec.adapters.cockroach_psycopg.CockroachPsycopgAsyncDriver[source]¶

Bases: PsycopgAsyncDriver

CockroachDB async driver using psycopg.crdb.

__init__(connection, statement_config=None, driver_features=None)[source]¶

async dispatch_execute(cursor, statement)[source]¶

Execute single SQL statement (async).

Parameters:

cursor¶ (Any) – Database cursor
statement¶ (SQL) – SQL statement to execute

Return type:

ExecutionResult

Returns:

ExecutionResult with statement execution details

async dispatch_execute_many(cursor, statement)[source]¶

Execute SQL with multiple parameter sets (async).

Parameters:

cursor¶ (Any) – Database cursor
statement¶ (SQL) – SQL statement with parameter list

Return type:

ExecutionResult

Returns:

ExecutionResult with batch execution details

async dispatch_execute_script(cursor, statement)[source]¶

Execute SQL script with multiple statements (async).

Parameters:

cursor¶ (Any) – Database cursor
statement¶ (SQL) – SQL statement containing multiple commands

Return type:

ExecutionResult

Returns:

ExecutionResult with script execution details

handle_database_exceptions()[source]¶

Handle database-specific exceptions and wrap them appropriately.

Return type:: CockroachPsycopgAsyncExceptionHandler

property data_dictionary: CockroachPsycopgAsyncDataDictionary¶

Get the data dictionary for this driver.

Returns:: Data dictionary instance for metadata queries

Retry Configuration¶

class sqlspec.adapters.cockroach_psycopg.core.CockroachPsycopgRetryConfig[source]¶

Bases: object

CockroachDB psycopg transaction retry configuration.

classmethod from_features(driver_features)[source]¶

Build retry config from driver feature mappings.

Return type:: CockroachPsycopgRetryConfig

__init__(max_retries=10, base_delay_ms=50.0, max_delay_ms=5000.0, enable_logging=True)¶