Database Setup¶

CALISTA uses PostgreSQL by default.

Quick start (PostgreSQL)¶

Point CALISTA at your database:

export CALISTA_DB_URL=postgresql+psycopg://calista:changeme@localhost:5432/calista

Optional (omit the password if your system supplies it via ~/.pgpass or a Postgres service):

export CALISTA_DB_URL=postgresql+psycopg://calista@localhost:5432/calista

Check database status:

Before applying migrations, verify CALISTA can reach your database:
```
calista db status
```
Typical output

Uninitialized (fresh database):
```
✅  Database reachable
Backend : postgresql
URL     : postgresql+psycopg://USER:***@localhost:5432/calista
Schema  : uninitialized
```
If you see " Cannot connect to database", double-check CALISTA_DB_URL and that your DB is running.
Initialize the schema:
```
calista db upgrade
```
(Optional) Verify the current revision:
```
calista db current
```
or
```
calista db status
```

If you don’t already have a PostgreSQL database¶

macOS (Homebrew)

brew install postgresql@17
brew services start postgresql@17

Note: you may need to update your PATH per Homebrew’s post-install message.

Ubuntu/Debian

sudo apt-get update && sudo apt-get install -y postgresql
sudo systemctl enable --now postgresql

Docker (quick local database)

docker run --name calista-pg \
  -e POSTGRES_USER=calista \
  -e POSTGRES_PASSWORD=changeme \
  -e POSTGRES_DB=calista \
  -p 5432:5432 -d postgres:17

Create a role and database (example, your setup may differ):

psql -U postgres -h localhost -c "CREATE ROLE calista LOGIN PASSWORD 'changeme';"
psql -U postgres -h localhost -c "CREATE DATABASE calista OWNER calista;"

Verify connectivity:

psql "postgresql://calista:changeme@localhost:5432/calista" -c "SELECT 1;"

Alternate engine (SQLite, limited features)¶

export CALISTA_DB_URL=sqlite:///./calista.db
calista db upgrade

SQLite is supported for quick local runs and CI, but it lacks some PostgreSQL features (e.g., JSONB indexes, certain CHECK constraints).

For more advanced database commands, see the CLI reference.