Install & Compatibility
Where this runs
tested against v2.0.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.680s · 51.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.4s · import 0.614s · 53MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_engine
✓ from sqlalchemy import create_engine
The CockroachDB dialect auto-registers when `sqlalchemy-cockroachdb` is installed. You create the engine using a `cockroachdb://` URL.
text
✓ from sqlalchemy import text
Used for executing raw SQL statements.
Demonstrates connecting to CockroachDB, executing a simple query, creating a table with a UUID primary key, inserting data, and selecting data. It uses an environment variable for the connection URL, falling back to a common local insecure setup.
import os
from sqlalchemy import create_engine, text
# CockroachDB connection string (replace with your actual connection string)
# For a local insecure instance: "cockroachdb://root@localhost:26257/defaultdb?sslmode=disable"
# For CockroachDB Cloud: "cockroachdb://<username>:<password>@<host>:<port>/<database>?sslmode=require"
DATABASE_URL = os.environ.get(
"COCKROACHDB_URL",
"cockroachdb://root@localhost:26257/defaultdb?sslmode=disable"
)
try:
engine = create_engine(DATABASE_URL)
with engine.connect() as connection:
# Verify connection
result = connection.execute(text("SELECT 1+1"))
print(f"Result of 1+1: {result.scalar()}")
# Example: Create a table with UUID primary key (recommended for CockroachDB)
connection.execute(text("""
CREATE TABLE IF NOT EXISTS accounts (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
balance INT
)
"""))
connection.commit()
print("Table 'accounts' checked/created.")
# Example: Insert data
connection.execute(text("INSERT INTO accounts (balance) VALUES (:balance)"), {"balance": 100})
connection.commit()
print("Inserted a new account.")
# Example: Select data
accounts_result = connection.execute(text("SELECT id, balance FROM accounts LIMIT 5"))
for row in accounts_result:
print(f"Account ID: {row.id}, Balance: {row.balance}")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure CockroachDB is running and your connection string is correct.")
Debug
Known issues
breakingSQLAlchemy 2.0 Compatibility: `sqlalchemy-cockroachdb` v2.x is specifically designed for SQLAlchemy v2.x. Attempting to use a v1.x dialect with SQLAlchemy v2.x, or vice-versa, will result in errors.fixEnsure your `sqlalchemy-cockroachdb` version matches your installed `SQLAlchemy` major version (e.g., `sqlalchemy-cockroachdb==2.x` for `SQLAlchemy==2.x`).
affects: <2.0 (with SQLAlchemy 2.x), >=2.0 (with SQLAlchemy <2.x)
gotchaTransaction Retries: CockroachDB frequently requires client-side transaction retry logic due to its distributed nature, which can lead to `SQLSTATE 40001` (serialization_failure) errors. SQLAlchemy does not inherently provide this.fixImplement application-level transaction retry logic, often by wrapping transaction blocks in a loop. Refer to CockroachDB documentation for Python transaction retry examples, which typically involve catching specific error codes and retrying.
affects: All versions
gotchaPrimary Key Strategy (`SERIAL` vs `UUID`/`UNIQUE_ROWID()`): Using `SERIAL` or `AUTOINCREMENT` for primary keys in CockroachDB can create hotspots and performance bottlenecks. `UUID` or `UNIQUE_ROWID()` are generally preferred for distributed performance.fixDefine primary keys using `UUID` (e.g., `id UUID PRIMARY KEY DEFAULT gen_random_uuid()`) or `UNIQUE_ROWID()` in your table schemas for better scalability in a distributed environment.
affects: All versions
gotchaConnection String `sslmode`: CockroachDB Cloud typically requires `sslmode=require` in the connection string. Local insecure instances might use `sslmode=disable`. Misconfiguring `sslmode` is a common cause of connection failures.fixAlways explicitly set `sslmode` in your CockroachDB connection string to match your database configuration (e.g., `sslmode=require` for secure connections, `sslmode=disable` for insecure local setups).
affects: All versions
Upgrade
Version history
2.0.4latest on PyPI · released Apr 23, 2026
Audit
Dependencies
SQLAlchemyrequiredCore ORM and SQL toolkit that this library extends.
psycopg2-binaryrequiredRecommended database driver for connecting to CockroachDB (PostgreSQL wire-compatible). `pg8000` is another option.