Crystal DBA Installation

Follow the instructions below to use the Crystal DBA client with the free hosted SaaS back end. We offer alternative deployment models, and we encourage you to contact us for information about other team and custom installation options.

First you will need to choose whether to install via Docker, pipx/pip, or another method:

Docker: We recommend this approach, particularly if you already have Docker installed, because it has no dependencies on your Python installation or system libraries.
pipx: If you are comfortable installing applications using pipx or pip, and if you already have Python 3.10+ installed, then you will find this approach to be fast and convenient.

Installation using Docker

If you need Docker, we recommend:

For Mac or Windows: Install Docker Desktop
For Linux: Install Docker Engine

Once you have Docker installed, launch Crystal DBA using the following command:

docker run -it --rm -v crystaldba:/root/.crystal crystaldba/crystaldba \
  "postgresql://postgres:mysecretpassword@localhost:5432/postgres"

In the example above, we involed Crystal DBA with a Postgres connection URI. The Crystal DBA Docker also image takes a standard set of arguments similar to those you would pass to the psql command. For example, you can provide the connection parameters as independent arguments:

docker run -it --rm -v crystaldba:/root/.crystal crystaldba/crystaldba \
  -h hostname -p 5432 \
  -U username -d dbname

You can always see the full help on Crystal DBA arguments by running:

docker run --rm crystaldba/crystaldba --help

Technical Notes

When Crystal DBA first runs, it generates a cryptographic key pair and registers it with the server. The volume mount (created with -v crystaldba:/root/.crystal) preserves the these cryptographic keys and other configuration settings across runs as the root file system of the running container is ephemeral.

If you are familiar with the internals of Docker you may be aware that it can make network connections work differently. Our Docker image automatically detects and handles connections to localhost in the database connection string. It will remap them automatically to the appropriate Docker host address (host.docker.internal on Mac/Windows, or 172.17.0.1 on Linux).

Installation using pipx or pip

If you prefer a native installation and already have Python installed, you can use Crystal DBA’s Terminal Application directly.

Prerequisites

Python 3.10 or newer

Verify your Python version:
```
python --version
# or
python3 --version
```
If you don’t have Python 3.10+, you’ll need to install it or install Crystal DBA using Docker.
pipx installed

pipx is a tool for installing and running Python applications in isolated environments. Follow the instructions for your platform to install pipx:

For MacOS run:
```
brew install pipx
pipx ensurepath
```
For Linux on Ubuntu/Debian:
```
sudo apt update
sudo apt install python3-pipx
pipx ensurepath
```
For Windows run:
```
python -m pip install --user pipx
python -m pipx ensurepath
```

Crystal DBA Installation using pipx

Once you have Python 3.10+ and pipx:

pipx install crystaldba

After installation, you may need to restart your terminal or reload your shell configuration for the command to be available.

Connect to Your Database

Crystal DBA takes a standard set of arguments similar to those you would pass to the psql command.

To connect with a PostgreSQL URL use the following command:

crystaldba "postgresql://postgres:mysecretpassword@localhost:5432/postgres"

You can also provide the connection parameters as independent arguments:

crystaldba -h hostname -p 5432 -U username -d dbname

If a password is required but not provided in the URI, you’ll be prompted to enter it securely.

Alternative Python Installation Methods

If you can’t use pipx, you have these options:

Using a virtual environment (recommended if not using pipx):
```
python -m venv crystaldba-env
source crystaldba-env/bin/activate  # On Windows: crystaldba-env\Scripts\activate
pip install crystaldba
```
To use Crystal DBA after installation, you’ll need to activate this virtual environment each time.
Using pip directly (not recommended for system-wide installation):
```
pip install crystaldba
```
Warning: Direct pip installation may conflict with system packages. Always prefer pipx or virtual environments.
Using uv (a faster alternative to pip):
```
uv venv
uv pip install crystaldba
```

For other installation methods, such as installing from source, see the advanced installation section of the User Guide.

Usage Reference

Crystal DBA’s Terminal Application supports various command-line options:

usage: crystaldba [-h HOSTNAME] [-p PORT] [-U USERNAME] [-d DBNAME] [-v] [--help] [DBNAME | URI]

Crystal DBA is an AI-powered PostgreSQL expert.

Examples:
  crystaldba dbname
  crystaldba postgresql://<username>:<password>@<host>:<port>/<dbname>
  crystaldba -d dbname -U dbuser

Connection options:
  DBNAME | URI          database name or URI to connect to
  -h, --host HOSTNAME   database server host or socket directory (default: "localhost")
  -p, --port PORT       database server port (default: "5432")
  -U, -u, --username USERNAME
                        database user name (default: "postgres")
  -d, --dbname DBNAME   database name (default: "postgres")

Other options:
  -v, --verbose         increase verbosity level (-v: INFO, -vv: DEBUG)
  --help                show this help message and exit

Contact us:
  Email support@crystaldba.ai if you have questions.

Troubleshooting

Verbose Logging

For troubleshooting, you can increase verbosity level:

# INFO level
crystaldba -v dbname
# or with Docker
docker run -it --rm -v $HOME/.crystal:/root/.crystal crystaldba/crystaldba -v dbname
 
# DEBUG level
crystaldba -vv dbname
# or with Docker
docker run -it --rm -v $HOME/.crystal:/root/.crystal crystaldba/crystaldba -vv dbname

Common Connection Issues

Password Authentication: If not provided in the URI, you’ll be prompted for a password
Docker Connection Issues: See the Docker Cross-platform Usage section below
Permission Errors: Ensure your database user has appropriate permissions
Connection Refused: Verify that your PostgreSQL server is running and accessible from your network

Docker Cross-platform Usage

The Docker container automatically detects and handles connections to services running on your host machine:

Mac & Windows: Uses host.docker.internal automatically
Linux Docker Desktop: Uses 172.17.0.1 or host.docker.internal automatically
Linux Standard Docker: May use 172.17.0.1 or need container networking options

If you’re having problems connecting to the database, you may try manually rewriting a target such as localhost or 127.0.0.1 to the appropriate target for your Docker configuration.

For example:

docker run -it --rm -v $HOME/.crystal:/root/.crystal crystaldba/crystaldba \
  "postgresql://postgres:mysecretpassword@host.docker.internal:5432/postgres"

For additional help, please contact us at support@crystaldba.ai.