index.rst

CrateDB Python Client

Introduction

The Python client library for CrateDB implements the Python Database API Specification v2.0 (PEP 249).

The Python driver can be used to connect to both CrateDB and CrateDB Cloud, and is verified to work on Linux, macOS, and Windows. It is used by the Crash CLI, as well as other libraries and applications connecting to CrateDB from the Python ecosystem. It is verified to work with CPython, but it has also been tested successfully with PyPy.

Please make sure to also visit the section about :ref:`other-options`, using the :ref:`crate-reference:interface-postgresql` interface of CrateDB.

Documentation

For general help about the Python Database API, please consult PEP 249. For more detailed information about how to install the client driver, how to connect to a CrateDB cluster, and how to run queries, consult the resources referenced below.

.. toctree::
    :titlesonly:

    getting-started
    connect
    query
    blobs

DB API

Install package from PyPI.

pip install crate

Connect to CrateDB instance running on localhost.

# Connect using DB API.
from crate import client
from pprint import pp

query = "SELECT country, mountain, coordinates, height FROM sys.summits ORDER BY country;"

with client.connect("localhost:4200", username="crate") as connection:
    cursor = connection.cursor()
    cursor.execute(query)
    pp(cursor.fetchall())
    cursor.close()

Connect to CrateDB Cloud.

# Connect using DB API.
from crate import client
connection = client.connect(
    servers="https://example.aks1.westeurope.azure.cratedb.net:4200",
    username="admin",
    password="<PASSWORD>")

Data types

The DB API driver supports :ref:`CrateDB's data types <crate-reference:data-types>` to different degrees. For more information, please consult the :ref:`data-types` documentation page.

.. toctree::
    :maxdepth: 2

    data-types

Migration Notes

The :ref:`CrateDB dialect <sqlalchemy-cratedb:index>` for SQLAlchemy is provided by the sqlalchemy-cratedb package.

If you are migrating from previous versions of crate[sqlalchemy]<1.0.0, you will find that the newer releases crate>=1.0.0 no longer include the SQLAlchemy dialect for CrateDB.

See migrate to sqlalchemy-cratedb for relevant guidelines about how to successfully migrate to the sqlalchemy-cratedb package.

Examples

• The :ref:`by-example` section enumerates concise examples demonstrating the different API interfaces of the CrateDB Python client library. Those are DB API, HTTP, and BLOB interfaces.
• Executable code examples are maintained within the cratedb-examples repository. sqlalchemy-cratedb, python-dataframe-examples, and python-sqlalchemy-examples provide relevant code snippets about how to connect to CrateDB using SQLAlchemy, pandas, or Dask, and how to load and export data.
• The sample application and the corresponding sample application documentation demonstrate the use of the driver on behalf of an example "guestbook" application, using Flask.

.. toctree::
    :maxdepth: 2

    by-example/index

.. seealso::

    The CrateDB Python client library is an open source project and is `managed
    on GitHub`_. Contributions, feedback, or patches are highly welcome!