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.

Install¶

We recommend using the uv package manager to install the application per uv tool install. Otherwise, using pipx install or pip install --user are viable alternatives.

uv tool install --upgrade 'cratedb-toolkit'

Synopsis¶

ctk shell

Usage¶

The ctk shell subcommand accepts configuration settings per CLI options and environment variables.

Cluster address

The program provides various options for addressing the database cluster in different situations, managed or not.

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

Note

All address options are mutually exclusive.
CLI options take precedence over environment variables.
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.

CrateDB Cloud¶

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>'

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;"