Documentation / Connecting to a Data Source

Connecting to a Data Source

Getting Started 📖 12 min read Last updated: Nov 10, 2025

Connecting your database to Treeo is the first step to unlocking AI-powered analytics for your organization. This guide will walk you through the complete process of setting up your data source connection.

Overview

Treeo connects to your data warehouse with read-only access, ensuring your data remains secure while enabling powerful analytics capabilities. The connection process is straightforward and takes just a few minutes.

Prerequisites

Before you begin, make sure you have:

Step 1: Access Database Settings

  1. Click on the user menu (avatar or initials) in the top right corner of the screen
  2. Select Settings from the dropdown menu
  3. Choose Database from the settings sidebar

You'll see a list of all currently connected databases (if any) and an option to add new connections.

Step 2: Add a New Database Connection

  1. Click on the Add Database button in the top right
  2. This will open the database connection configuration form

Step 3: Select Database Type

Currently, PostgreSQL is the supported database type for initial connections.

📝 Note: MySQL and SQL Server support are on the roadmap and will be available in future updates. If you need support for other databases, please contact our support team.

Supported Databases (Full Platform)

While the UI currently shows PostgreSQL, Treeo's full platform supports:

Step 4: Enter Connection Details

Provide the following connection information in the form:

Required Fields

Host

Port

Database Name

Username

Password

Example Configuration

Host:     db.example.com
Port:     5432
Database: analytics_prod
Username: treeo_readonly
Password: ••••••••••••
SSL Mode: Require

Step 5: Test Connection

Before saving, it's crucial to test your connection:

  1. Click the Test Connection button
  2. Treeo will attempt to connect using your provided credentials
  3. You'll see one of these results:

✅ Success

✓ Connection successful!
Connected to database: analytics_prod
Server version: PostgreSQL 14.5

If successful, proceed to save your connection.

❌ Connection Failed

Common errors and solutions:

Error: "Could not connect to server"

Error: "Authentication failed"

Error: "Database does not exist"

Error: "SSL connection required"

Step 6: Save and Verify

  1. After a successful connection test, click Save
  2. Your database connection will be added to the list
  3. Treeo will begin syncing your database schema
  4. You can now start creating metrics and asking questions!

Setting Up Read-Only Access

For security best practices, create a dedicated read-only user for Treeo:

PostgreSQL Read-Only User

-- Create a read-only user
CREATE USER treeo_readonly WITH PASSWORD 'secure_password_here';

-- Grant connection to the database
GRANT CONNECT ON DATABASE analytics_prod TO treeo_readonly;

-- Grant schema usage
GRANT USAGE ON SCHEMA public TO treeo_readonly;

-- Grant SELECT on all existing tables
GRANT SELECT ON ALL TABLES IN SCHEMA public TO treeo_readonly;

-- Grant SELECT on future tables (recommended)
ALTER DEFAULT PRIVILEGES IN SCHEMA public 
GRANT SELECT ON TABLES TO treeo_readonly;

-- Optional: Grant access to specific schemas
GRANT USAGE ON SCHEMA sales, marketing TO treeo_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA sales, marketing TO treeo_readonly;

Verify Permissions

Test that your read-only user works correctly:

-- Connect as the read-only user and test
SELECT table_schema, table_name 
FROM information_schema.tables 
WHERE table_schema IN ('public', 'sales', 'marketing');

-- Try to query a table
SELECT COUNT(*) FROM your_table_name LIMIT 1;

-- Verify you CANNOT write (this should fail)
INSERT INTO your_table_name VALUES (...);  -- Should return error

Managing Database Connections

Viewing Connected Databases

In Settings → Database, you'll see:

Editing a Connection

  1. Click on the database name in the list
  2. Update any connection details
  3. Test the connection again
  4. Save changes

⚠️ Warning: Changing connection details may affect existing metrics and dashboards. Test thoroughly before saving.

Removing a Connection

  1. Click the delete icon next to the database
  2. Confirm you want to remove the connection
  3. All metrics using this database will be affected

⚠️ Warning: Removing a database connection will disable all metrics and dashboards that rely on it. Consider archiving instead of deleting.

Pausing a Connection

If you need to temporarily disable a connection:

  1. Edit the connection
  2. Toggle "Active" to Off
  3. Save changes

This preserves your configuration while stopping data syncs.

Troubleshooting

Connection Issues

Performance Issues

Problem: Connection is slow or times out

Solutions:

Best Practices

Security

✅ Do:

❌ Don't:

Performance

✅ Do:

❌ Don't:

Maintenance

Next Steps

Now that your database is connected:

  1. Explore Your Schema
    • Browse tables in the Schema Explorer
    • Understand your data structure
  2. Create Your First Metric
  3. Start Asking Questions
    • Use Chat Mode to query your data
    • Reference your new metrics
  4. Build Dashboards
    • Create visualizations
    • Share insights with your team

Related Documentation

Support

Need help connecting your database?

Our support team can help with:

← Previous: Introduction