CockroachDB SQLAlchemy Adapter

0.3.5 verified Mon Apr 27 auth: no python

CockroachDB adapter for SQLAlchemy, allowing SQLAlchemy applications to connect to CockroachDB. Current version 0.3.5. Release cadence is irregular; maintained by Cockroach Labs.

pip install cockroachdb

Common errors

error sqlalchemy.exc.OperationalError: (cockroachdb.sqlalchemy.dialect.CockroachDBDialect) ... ↓

cause Invalid connection string or missing SSL configuration.

fix

Ensure your DATABASE_URL is correct and includes ?sslmode=disable or ?sslmode=require as needed.

error ModuleNotFoundError: No module named 'cockroachdb' ↓

cause The package is not installed or installed in a different environment.

fix

Run 'pip install cockroachdb' in the correct Python environment.

Warnings

gotcha The package name 'cockroachdb' might conflict if you also have CockroachDB Python client installed (cockroachdb-python). This adapter is only for SQLAlchemy. ↓

fix Use pip show to verify, or install in a clean environment.

deprecated Older versions (pre-0.3.0) used a different connection URI pattern. Ensure your URI starts with 'cockroachdb://' not 'cockroach://'. ↓

fix Update to version 0.3.5 and use 'cockroachdb://' scheme.

gotcha Transactions with SERIALIZABLE isolation may behave differently than PostgreSQL. Use the cockroachdb-specific retry logic for transactions. ↓

fix Use the 'run_transaction' helper from the CockroachDB Python client for proper retry support.

Imports

cockroachdb
```
import cockroachdb
```

Quickstart

Create a SQLAlchemy engine for CockroachDB and run a simple query.

from sqlalchemy import create_engine
import os

DATABASE_URL = os.environ.get('DATABASE_URL', 'cockroachdb://user:password@localhost:26257/defaultdb?sslmode=disable')
engine = create_engine(DATABASE_URL)
with engine.connect() as conn:
    result = conn.execute("SELECT version()")
    print(result.fetchone())