CrateDB Cluster Python API¶

The cratedb_toolkit.ManagedCluster class provides the higher level API/SDK entrypoints to start/deploy/resume a database cluster, inquire information about it, and stop/suspend it again.

The subsystem is implemented on top of the Croud CLI application, which gets installed along the lines and is used later on this page.

Install¶

We recommend using the uv package manager to install the framework per uv pip install, or add it to your application using uv add. Otherwise, using pip install is a viable alternative.

uv pip install --upgrade 'cratedb-toolkit'

Authenticate¶

When working with CrateDB Cloud, you can select between two authentication variants. Either interactively authorize your terminal session using croud login,

croud login --idp {cognito,azuread,github,google}

or provide API access credentials per environment variables for headless/unattended operations after creating them using the CrateDB Cloud Console or croud api-keys create.

# CrateDB Cloud API credentials.
export CRATEDB_CLOUD_API_KEY='<YOUR_API_KEY_HERE>'
export CRATEDB_CLOUD_API_SECRET='<YOUR_API_SECRET_HERE>'

Configure¶

ManagedCluster accepts configuration settings per constructor parameters or environment variables.

Environment variables:: CRATEDB_CLUSTER_ID, CRATEDB_CLUSTER_NAME, CRATEDB_CLUSTER_URL

Note

All address options are mutually exclusive.
The cluster identifier takes precedence over the cluster name.
The cluster url takes precedence over the cluster id and name.
Environment variables can be stored into an .env file in your working directory.

Usage¶

Acquire a database cluster handle, and run database workload.

from pprint import pprint
from cratedb_toolkit import ManagedCluster

# Connect to CrateDB Cloud and run the database workload.
with ManagedCluster.from_env() as cluster:
    pprint(cluster.query("SELECT * from sys.summits LIMIT 2;"))

By default, the cluster will spin up, but not shut down after exiting the context manager. If you want to do it, use the stop_on_exit=True option.

from cratedb_toolkit import ManagedCluster

with ManagedCluster.from_env(stop_on_exit=True) as cluster:
    # ...