Datasources

Datasources are database connections that you can query with Calliope magic commands. Add, list, and manage your database connections.

Commands

Command	Description
`%calliope list-datasources`	List all datasources
`%calliope get-datasource <id>`	Get details about a datasource
`%%calliope add-database`	Add a new datasource
`%calliope delete-database <id>`	Remove a datasource

Listing Datasources

See all available databases:

%calliope list-datasources

Output shows:

Datasource ID (used in commands)
Display name
Database type
Connection status

Getting Datasource Details

View tables and schema:

%calliope get-datasource sales_db

Shows:

Connection info
Available tables
Column details per table

Adding a Datasource

Add a new database connection:

%%calliope add-database
{
    "datasource_id": "mydb",
    "name": "My Analytics Database",
    "dialect": "postgresql",
    "connection_details": {
        "host": "db.example.com",
        "port": 5432,
        "database": "analytics",
        "user": "readonly_user"
    },
    "password_field": "mydb_password",
    "password_value": "your_password_here"
}

Configuration Fields

Field	Required	Description
`datasource_id`	Yes	Unique ID for commands
`name`	Yes	Display name
`dialect`	Yes	Database type
`connection_details`	Yes	Connection parameters
`password_field`	Yes	Name for stored secret
`password_value`	Yes	Database password

Supported Dialects

Dialect	Value
PostgreSQL	`postgresql`
MySQL	`mysql`
MariaDB	`mariadb`
SQLite	`sqlite`

Connection Details by Dialect

PostgreSQL/MySQL/MariaDB:

{
    "host": "hostname",
    "port": 5432,
    "database": "dbname",
    "user": "username"
}

SQLite:

{
    "database": "/path/to/database.db"
}

What Happens When You Add a Database

Password stored: Securely saved as a secret
Connection tested: Verifies connectivity
Schema introspected: Discovers tables and columns
RAG trained: Schema automatically added to RAG

Deleting a Datasource

Remove a database connection:

%calliope delete-database mydb

This removes:

The datasource configuration
Associated RAG training data
Stored credentials

Managing Secrets

List Secrets

%calliope list-secrets

Delete a Secret

%calliope delete-secret mydb_password

Other Commands

List Available Providers

See AI model providers:

%calliope list-providers

List Available Models

See available AI models:

%calliope list-models

Example: Complete Setup

1. Add the database

%%calliope add-database
{
    "datasource_id": "analytics",
    "name": "Production Analytics",
    "dialect": "postgresql",
    "connection_details": {
        "host": "analytics.internal.company.com",
        "port": 5432,
        "database": "analytics_prod",
        "user": "analyst_readonly"
    },
    "password_field": "analytics_pwd",
    "password_value": "secure_password_123"
}

2. Verify connection

%calliope get-datasource analytics

3. Add business documentation

%%calliope rag-train analytics
{
    "documentation": [
        "user_events contains all product analytics events",
        "users.plan can be: free, starter, pro, enterprise",
        "revenue is in cents, divide by 100 for dollars"
    ]
}

4. Start querying

%%calliope ask-sql analytics
How many active users do we have by plan type?

Troubleshooting

“Connection failed”

Check hostname and port
Verify database is accessible from your workspace
Confirm username and password
Check firewall rules

“Access denied”

Verify user has SELECT permissions
Check if user is allowed from your IP
Ensure database name is correct

“Database not found”

Confirm database name spelling
Check if database exists
Verify user has access to the database

Schema not showing

User may lack permission to read schema
Try querying a specific table to verify access
Some tables may be in non-default schemas

rag-train Models