CrateDB Cluster CLI¶

The ctk cluster {start,info,stop} subcommands provide higher level CLI 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.

Installation¶

CrateDB Toolkit uses the Python programming language with native performance extensions, which is installed on most machines today. Otherwise, we recommend to download and install Python from the original source. For installing additional Python packages, we recommend to install the uv package manager.

uv tool install --upgrade 'cratedb-toolkit'

An alternative way to install Python packages is to use pipx or pip install --user.

pipx install 'cratedb-toolkit'

Another way to invoke CrateDB Toolkit without installing it is to use its container image with Docker, Podman, Kubernetes, and friends.

docker run --rm ghcr.io/crate/cratedb-toolkit ctk

Prerequisites¶

Before using CrateDB Cloud services, authenticate and select your target database cluster.

Authenticate¶

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

# Replace YOUR_IDP with one of: cognito, azuread, github, google.
croud login --idp YOUR_IDP

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.

# Provide CrateDB Cloud API authentication tokens.
export CRATEDB_CLOUD_API_KEY='<YOUR_API_KEY>'
export CRATEDB_CLOUD_API_SECRET='<YOUR_API_SECRET>'

Select cluster¶

Discover the list of available database clusters.

croud clusters list

Select the designated target database cluster using one of three variants, either by using CLI options or environment variables.

All address options are mutually exclusive.
CLI options take precedence over environment variables.
Environment variables can be stored into an .env file in your working directory.

CLI options:: --cluster-id, --cluster-name, --cluster-url
Environment variables:: CRATEDB_CLUSTER_ID, CRATEDB_CLUSTER_NAME, CRATEDB_CLUSTER_URL

Before invoking any of the next steps, address the CrateDB Cloud Cluster you are aiming to connect to, for example by defining the cluster id using the CRATEDB_CLUSTER_ID environment variable.

export CRATEDB_CLUSTER_ID='<YOUR_CLUSTER_ID>'

Usage¶

Start or resume a cluster, deploying it on demand if it doesn’t exist.

ctk cluster start --cluster-name hotzenplotz

Display cluster information.

ctk cluster info --cluster-name hotzenplotz

Stop (suspend) a cluster.

ctk cluster stop --cluster-name hotzenplotz