Guide: Connecting to a Data Source in Treeo

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:

• Database credentials with read access
• Network access to your database (firewall/VPN configured if needed)
• Database host and port information

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:

• ✅ PostgreSQL (Available now)
• 🔜 MySQL (Coming soon)
• 🔜 SQL Server (Coming soon)

Step 4: Enter Connection Details

Provide the following connection information in the form:

Required Fields

Host

• Description: The server address where your database is hosted
• Format: IP address or domain name
• Examples:
  • db.company.com
  • 192.168.1.100
  • localhost (for local development)

Port

• Description: The port number for the database connection
• Default PostgreSQL Port: 5432
• Format: Numeric value
• Example: 5432

Database Name

• Description: The specific database you want to connect to
• Example: analytics, production, warehouse

Username

• Description: Your database username
• Best Practice: Use a dedicated read-only user for Treeo
• Example: treeo_readonly

Password

• Description: Your database password
• Security: Passwords are encrypted and stored securely
• Note: Never shared or visible after saving

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"

• Check that the host and port are correct
• Verify your firewall allows connections from Treeo
• Confirm the database server is running

Error: "Authentication failed"

• Verify username and password are correct
• Check that the user has database access permissions
• Ensure the user is not locked or expired

Error: "Database does not exist"

• Confirm the database name is spelled correctly
• Check that the database exists on the server
• Verify the user has access to this specific database

Error: "SSL connection required"

• Enable SSL mode in connection settings
• Contact your DBA if SSL certificates are needed

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:

• Database name and type
• Connection status (Connected/Disconnected)
• Last sync time
• Number of tables synced

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:

• Increase connection timeout in settings
• Check network latency between Treeo and your database
• Verify database server has adequate resources
• Consider using a read replica for analytics

Best Practices

Security

✅ Do:

• Use dedicated read-only credentials
• Enable SSL/TLS connections
• Rotate passwords regularly (quarterly)
• Use strong, unique passwords
• Monitor connection logs

❌ Don't:

• Share admin credentials with Treeo
• Use write-access accounts
• Disable SSL in production
• Use default passwords
• Expose databases directly to the internet

Performance

✅ Do:

• Use read replicas for analytics workloads
• Set appropriate connection timeouts
• Monitor query performance
• Create indexes on frequently queried columns
• Schedule heavy queries during off-peak hours

❌ Don't:

• Connect to primary production databases
• Run expensive queries during peak hours
• Ignore slow query warnings
• Skip connection pool configuration

Maintenance

• Review connections monthly
• Update credentials when team members leave
• Test connections after database migrations
• Document connection configurations
• Keep contact info for database admins updated

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

   • Follow the Metrics Documentation
   • Start with simple metrics like row counts

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

• Setup Guide - Complete setup walkthrough
• Data Security - Security best practices
• Metrics - Creating and managing metrics
• VPN Tunnel - Secure connection options
• On-Premise Deployment - Self-hosted setup

Support

Need help connecting your database?

• 📧 Email: support@treeo.ai
• 💬 Live Chat: Available in-app

Our support team can help with:

• Connection troubleshooting
• Firewall configuration
• Read-only user setup
• Performance optimization
• Security best practices