crate

library2.1.2pypypi✓ verified 90d ago

The `crate` library is the official Python client for CrateDB, a distributed SQL database. It provides a DB-API 2.0 compliant interface for connecting to CrateDB clusters, executing SQL queries, and managing data. The current version is 2.1.2, and it typically sees regular updates aligned with CrateDB releases and Python ecosystem changes.

database

pip install crate

package ↗homepage ↗

INSTALL

IMPORT

SIG · CRATE

crate

databasepythonv2.1.2

Install

2.2s avg

Import

272ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.2 · 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

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.281s · 19.5MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.2s · import 0.264s · 20MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

connect

✓ from crate.client import connect

Connects to a CrateDB instance, creates a table, inserts two rows, and then queries them. Requires a running CrateDB instance (default: localhost:4200).

import os from crate.client import connect CRATEDB_HOST = os.environ.get('CRATEDB_HOST', 'http://localhost:4200') try: # Connect to CrateDB connection = connect(CRATEDB_HOST) cursor = connection.cursor() # Create a table if it doesn't exist cursor.execute("CREATE TABLE IF NOT EXISTS my_data (id INTEGER, name TEXT)") print("Table 'my_data' ensured.") # Insert data cursor.execute("INSERT INTO my_data (id, name) VALUES (?, ?)", (1, "Alice")) cursor.execute("INSERT INTO my_data (id, name) VALUES (?, ?)", (2, "Bob")) connection.commit() print("Data inserted.") # Query data cursor.execute("SELECT * FROM my_data ORDER BY id") results = cursor.fetchall() print("\nQuery Results:") for row in results: print(row) except Exception as e: print(f"An error occurred: {e}") finally: if 'connection' in locals() and connection: connection.close() print("Connection closed.")

Debug

Known issues

breakingThe SQLAlchemy dialect for CrateDB was extracted into a separate package, `crate-sqlalchemy`. Users relying on ORM integration will need to install this new package.

fix

Install `crate-sqlalchemy` (`pip install crate-sqlalchemy`) and import the dialect from `crate_sqlalchemy.dialect`.

affects: >=1.0.0

gotchaThe `connect()` function expects a full HTTP URL for the CrateDB host, including the `http://` or `https://` schema. Failing to include the schema (e.g., just `localhost:4200`) will result in a connection error.

fix

Ensure the connection string starts with `http://` or `https://`, e.g., `http://localhost:4200`.

affects: All versions

gotchaPython `datetime` objects are not directly JSON serializable by default, which can lead to `TypeError` when inserting into `TIMESTAMP` columns without explicit conversion. CrateDB expects timestamps as Unix milliseconds or ISO 8601 strings.

fix

Convert `datetime` objects to Unix milliseconds (integer) or ISO 8601 strings before passing them in parameters, e.g., `int(dt_object.timestamp() * 1000)`.

affects: All versions

Errors

Common errors & fixes

OperationalError: Failed to establish a new connection: [Errno 111] Connection refused

The CrateDB server is not running, is not accessible at the specified host/port, or a firewall is blocking the connection.

fix

Ensure CrateDB is running and listening on the correct address (default: `localhost:4200`). Verify firewall rules and the `CRATEDB_HOST` environment variable or hardcoded connection string.

TypeError: Object of type datetime is not JSON serializable

Attempting to insert a Python `datetime` object directly into a CrateDB `TIMESTAMP` column without proper serialization.

fix

Before inserting, convert the `datetime` object to an integer representing milliseconds since epoch, or an ISO 8601 string. Example: `cursor.execute("INSERT INTO my_table (ts_col) VALUES (?) ", (int(my_datetime.timestamp() * 1000),))`.

AttributeError: module 'crate.client' has no attribute 'SQLAlchemyDialect'

Trying to import the SQLAlchemy dialect from the main `crate` package after it was moved to a separate `crate-sqlalchemy` package.

fix

Install the dedicated SQLAlchemy package: `pip install crate-sqlalchemy`. Then, import the dialect from `crate_sqlalchemy.dialect`.

Upgrade

Version history

2.1.2latest on PyPI · released Mar 9, 2026

Audit

Dependencies

requestsrequiredUsed for HTTP communication with CrateDB.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/crate/ ↗

homepagehttps://crate.io ↗