{"id":9627,"library":"crate","title":"CrateDB Python Client","description":"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.","status":"active","version":"2.1.2","language":"en","source_language":"en","source_url":"https://github.com/crate/crate-python","tags":["database","sql","client","cratedb","dbapi"],"install":[{"cmd":"pip install crate","lang":"bash","label":"Install core client"}],"dependencies":[{"reason":"Used for HTTP communication with CrateDB.","package":"requests","optional":false}],"imports":[{"symbol":"connect","correct":"from crate.client import connect"}],"quickstart":{"code":"import os\nfrom crate.client import connect\n\nCRATEDB_HOST = os.environ.get('CRATEDB_HOST', 'http://localhost:4200')\n\ntry:\n    # Connect to CrateDB\n    connection = connect(CRATEDB_HOST)\n    cursor = connection.cursor()\n\n    # Create a table if it doesn't exist\n    cursor.execute(\"CREATE TABLE IF NOT EXISTS my_data (id INTEGER, name TEXT)\")\n    print(\"Table 'my_data' ensured.\")\n\n    # Insert data\n    cursor.execute(\"INSERT INTO my_data (id, name) VALUES (?, ?)\", (1, \"Alice\"))\n    cursor.execute(\"INSERT INTO my_data (id, name) VALUES (?, ?)\", (2, \"Bob\"))\n    connection.commit()\n    print(\"Data inserted.\")\n\n    # Query data\n    cursor.execute(\"SELECT * FROM my_data ORDER BY id\")\n    results = cursor.fetchall()\n\n    print(\"\\nQuery Results:\")\n    for row in results:\n        print(row)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    if 'connection' in locals() and connection:\n        connection.close()\n        print(\"Connection closed.\")","lang":"python","description":"Connects to a CrateDB instance, creates a table, inserts two rows, and then queries them. Requires a running CrateDB instance (default: localhost:4200)."},"warnings":[{"fix":"Install `crate-sqlalchemy` (`pip install crate-sqlalchemy`) and import the dialect from `crate_sqlalchemy.dialect`.","message":"The SQLAlchemy dialect for CrateDB was extracted into a separate package, `crate-sqlalchemy`. Users relying on ORM integration will need to install this new package.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure the connection string starts with `http://` or `https://`, e.g., `http://localhost:4200`.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Convert `datetime` objects to Unix milliseconds (integer) or ISO 8601 strings before passing them in parameters, e.g., `int(dt_object.timestamp() * 1000)`.","message":"Python `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"The CrateDB server is not running, is not accessible at the specified host/port, or a firewall is blocking the connection.","error":"OperationalError: Failed to establish a new connection: [Errno 111] Connection refused"},{"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),))`.","cause":"Attempting to insert a Python `datetime` object directly into a CrateDB `TIMESTAMP` column without proper serialization.","error":"TypeError: Object of type datetime is not JSON serializable"},{"fix":"Install the dedicated SQLAlchemy package: `pip install crate-sqlalchemy`. Then, import the dialect from `crate_sqlalchemy.dialect`.","cause":"Trying to import the SQLAlchemy dialect from the main `crate` package after it was moved to a separate `crate-sqlalchemy` package.","error":"AttributeError: module 'crate.client' has no attribute 'SQLAlchemyDialect'"}]}