The extension module provides the following classes and helpers:

• - a subclass of PostgresqlDatabase, designed specifically for working with CRDB.
• - like the above, but implements connection-pooling.
• run_transaction() - runs a function inside a transaction and provides automatic client-side retry logic.

Special field-types that may be useful when using CRDB:

• - a primary-key field implementation that uses CRDB’s UUID type with a default randomly-generated UUID.
• RowIDField - a primary-key field implementation that uses CRDB’s INT type with a default unique_rowid().
• - same as the Postgres extension (but does not support multi-dimensional arrays).

CRDB is compatible with Postgres’ wire protocol and exposes a very similar SQL interface, so it is possible (though not recommended) to use PostgresqlDatabase with CRDB:

1. CRDB does not support nested transactions (savepoints), so the method has been implemented to enforce this when using CockroachDatabase. For more info .
2. CRDB may have subtle differences in field-types, date functions and introspection from Postgres.
3. CRDB-specific features are exposed by the CockroachDatabase, such as specifying a transaction priority or the clause.

CRDB does not support nested transactions (savepoints), so the method on the CockroachDatabase has been modified to raise an exception if an invalid nesting is encountered. If you would like to be able to nest transactional code, you can use the method, which will ensure that the outer-most block will manage the transaction (e.g., exiting a nested-block will not cause an early commit).

Example:

CRDB provides client-side transaction retries, which are available using a special run_transaction() helper. This helper method accepts a callable, which is responsible for executing any transactional statements that may need to be retried.

Simplest possible example of :

Note

The cockroachdb.ExceededMaxAttempts exception will be raised if the transaction cannot be committed after the given number of attempts. If the SQL is mal-formed, violates a constraint, etc., then the function will raise the exception to the caller.

CRDB APIs

class CockroachDatabase(database[, \*kwargs*])

CockroachDB implementation, based on the and using the psycopg2 driver.

Additional keyword arguments are passed to the psycopg2 connection constructor, and may be used to specify the database user, port, etc.

• run_transaction(callback[, max_attempts=None[, system_time=None[, priority=None]]])

  Run SQL in a transaction with automatic client-side retries.

  User-provided callback:

  • Must accept one parameter, the db instance representing the connection the transaction is running under.
  • Must not attempt to commit, rollback or otherwise manage the transaction.
  • May be called more than one time.
  • Should ideally only contain SQL operations.

  Additionally, the database must not have any open transactions at the time this function is called, as CRDB does not support nested transactions. Attempting to do so will raise a NotImplementedError.

class PooledCockroachDatabase(database[, \*kwargs*])

CockroachDB connection-pooling implementation, based on PooledPostgresqlDatabase. Implements the same APIs as , but will do client-side connection pooling.

run_transaction(db, callback[, max_attempts=None[, system_time=None[, priority=None]]])

Run SQL in a transaction with automatic client-side retries. See CockroachDatabase.run_transaction() for details.

Note

This function is equivalent to the identically-named method on the CockroachDatabase class.

class UUIDKeyField

UUID primary-key field that uses the CRDB gen_random_uuid() function to automatically populate the initial value.

class RowIDField

See also:

• from the Postgresql extension.