Connecting Datasources

Learn how to connect databases and document collections to Deep Data Agent.

Database Connections

Supported Databases

Adding a Database

1. Open Deep Data Agent from the Hub
2. Click the Settings icon (gear) in the top right
3. Select Datasources
4. Click Add Datasource

Connection Details

Fill in the required fields:

Connection String (Alternative)

For advanced configurations, use a connection string:

postgresql://user:password@host:5432/database

mysql://user:password@host:3306/database

Testing Connections

After entering details:

1. Click Test Connection
2. Wait for confirmation
3. If successful, click Save

If the test fails, check:

• Hostname and port are correct
• Credentials are valid
• Database allows connections from Calliope’s network
• Firewall rules permit access

Multiple Databases

You can connect multiple datasources:

• Connect different databases (production, staging, analytics)
• Connect the same database with different credentials
• Organize by project or team

Switch between them in the chat:

Use the analytics database

Query the staging datasource

Document Collections (RAG)

What is RAG?

RAG (Retrieval-Augmented Generation) lets Deep Data Agent learn from your documents. When you ask questions, the agent searches your documents and includes relevant context in its responses.

Supported Document Types

Adding Documents

1. Open Settings → RAG
2. Choose how to add documents:

Upload Files

• Drag and drop files
• Or click to browse

Point to Directory

• Enter a path in your workspace
• All matching files will be indexed

Indexing Process

After adding documents:

1. Deep Data Agent processes each file
2. Content is split into searchable chunks
3. Chunks are embedded for semantic search
4. Progress is shown in the interface

Large document collections may take several minutes to index.

Using RAG in Queries

Once documents are indexed, ask questions naturally:

What does our API documentation say about authentication?

Find the section about error handling in the codebase

Summarize the key points from the quarterly report

Updating Documents

To refresh after changes:

1. Open Settings → RAG
2. Click Re-index next to the collection
3. Wait for processing to complete

Or add new files—they’re indexed automatically.

Removing Documents

1. Open Settings → RAG
2. Select the documents to remove
3. Click Remove from index

Security Considerations

Credentials

• Database passwords are encrypted at rest
• Credentials are not visible after saving
• Use read-only database users when possible

Network Access

• Your database must be accessible from Calliope’s infrastructure
• For private databases, contact support about VPN options
• Consider IP allowlisting for additional security

Data Privacy

• Query results pass through the AI model for analysis
• Document content is processed for RAG indexing
• Review your data handling policies before connecting sensitive databases

Read-Only Access

We recommend using read-only database credentials:

PostgreSQL

CREATE USER calliope_reader WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE yourdb TO calliope_reader;
GRANT USAGE ON SCHEMA public TO calliope_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO calliope_reader;

MySQL

CREATE USER 'calliope_reader'@'%' IDENTIFIED BY 'secure_password';
GRANT SELECT ON yourdb.* TO 'calliope_reader'@'%';

Troubleshooting

Connection Refused

• Verify the host and port are correct
• Check that the database server is running
• Ensure firewall allows inbound connections

Authentication Failed

• Double-check username and password
• Verify the user has permission to connect
• Check if the user is locked or expired

Timeout

• Database might be under heavy load
• Network latency might be high
• Try increasing connection timeout in advanced settings

SSL Errors

• Ensure SSL mode matches your database configuration
• Check certificate validity
• Try disabling SSL for testing (not recommended for production)

Permission Denied

• User might lack SELECT privileges
• Some tables might be restricted
• Check schema permissions

Best Practices

Naming Conventions

Use clear, descriptive names:

• ✅ “Production Analytics DB”
• ✅ “Staging - Customer Data”
• ❌ “db1”
• ❌ “test”

Credential Management

• Use service accounts, not personal credentials
• Rotate passwords periodically
• Grant minimum necessary permissions

Performance

• Connect to read replicas when available
• Use database-level query timeouts
• Consider indexing frequently-queried columns

Documentation

Add RAG documents that explain your data:

• Data dictionaries
• Schema documentation
• Business glossaries
• Past analysis reports

This helps the agent understand your data better.