ctk shell¶

The database shell interface of CrateDB Toolkit is based on the crash application. It can connect to both managed clusters on CrateDB Cloud, and self-hosted instances of CrateDB.

Synopsis¶

ctk shell

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¶

The ctk shell subcommand accepts configuration settings per CLI options and environment variables, like outlined above.

CrateDB Cloud¶

Connect to CrateDB Cloud.

ctk shell --cluster-name hotzenplotz --command "SELECT * from sys.summits LIMIT 2;"

echo "SELECT * from sys.summits LIMIT 2;" | ctk shell --cluster-name testcluster

CrateDB standalone¶

Connect to a standalone CrateDB instance on localhost, authenticating with the default user crate.

ctk shell --cluster-url 'crate://localhost:4200' --command "SELECT 42;"

When working with self-hosted or standalone CrateDB instances, include authentication credentials into the SQLAlchemy or HTTP connection URLs. We recommend using the SQLAlchemy connection URL variant.

export CRATEDB_CLUSTER_URL='https://admin:dZ...6LqB@testdrive.eks1.eu-west-1.aws.cratedb.net:4200/'

export CRATEDB_CLUSTER_URL='crate://admin:dZ...6LqB@testdrive.eks1.eu-west-1.aws.cratedb.net:4200/?ssl=true'

When using environment variables to configure ctk, the command itself becomes even shorter.

ctk shell --command "SELECT 42;"