Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/evidence-dev/evidence/llms.txt

Use this file to discover all available pages before exploring further.

Evidence can connect to multiple data sources including databases, data warehouses, and flat files. This guide covers everything you need to know about data connections.

​
Supported Data Sources

Evidence supports these data sources out of the box:
  • Databases: PostgreSQL, MySQL, SQL Server, SQLite
  • Warehouses: Snowflake, BigQuery, Databricks, Redshift
  • Files: CSV, Parquet, DuckDB
  • Query Engines: Trino, Athena

​
Connection Configuration

1

Create a Connection File

Data source connections are defined in YAML files in the sources/ directory. Each subdirectory represents a separate data source.Create a directory and connection file:
mkdir -p sources/my_warehouse
Create sources/my_warehouse/connection.yaml:
name: my_warehouse
type: postgres
options:
  host: database.example.com
  port: 5432
  database: analytics
  user: evidence_user
  password: ${EVIDENCE_PASSWORD}
  ssl: true
Use environment variables (like ${EVIDENCE_PASSWORD}) to keep credentials secure.
2

Configure Environment Variables

Create a .env file in your project root:
EVIDENCE_PASSWORD=your_secure_password
SNOWFLAKE_USER=analytics_user
SNOWFLAKE_PASSWORD=another_secure_password
Important: Add .env to your .gitignore to keep credentials out of version control.
3

Test Your Connection

Create a test query in your source directory:sources/my_warehouse/test.sql:
SELECT 1 as test_value
Run your Evidence app and check that the query executes successfully.

​
Connection Examples

​
DuckDB (Local Database)

DuckDB is perfect for local development and small to medium datasets:
sources/local/connection.yaml
name: local
type: duckdb
options:
  filename: ./local.duckdb
DuckDB automatically loads and can query CSV and Parquet files directly: 
SELECT * FROM read_csv_auto('data/sales.csv')

​
CSV Files

Evidence can read CSV files as a data source:
sources/csv/connection.yaml
name: csv
type: csv
options: {}
Place your CSV files in sources/csv/ and query them:
sources/csv/sales_data.sql
SELECT * FROM sales_data.csv

​
PostgreSQL

sources/postgres/connection.yaml
name: postgres_db
type: postgres
options:
  host: ${POSTGRES_HOST}
  port: 5432
  database: ${POSTGRES_DATABASE}
  user: ${POSTGRES_USER}
  password: ${POSTGRES_PASSWORD}
  ssl: true

​
Snowflake

sources/snowflake/connection.yaml
name: snowflake
type: snowflake
options:
  account: ${SNOWFLAKE_ACCOUNT}
  username: ${SNOWFLAKE_USER}
  password: ${SNOWFLAKE_PASSWORD}
  database: ANALYTICS
  warehouse: COMPUTE_WH
  schema: PUBLIC

​
BigQuery

sources/bigquery/connection.yaml
name: bigquery
type: bigquery
options:
  project_id: ${GCP_PROJECT_ID}
  credentials_path: ./credentials.json
Or use a service account key directly: 
options:
  project_id: my-project
  client_email: ${GCP_CLIENT_EMAIL}
  private_key: ${GCP_PRIVATE_KEY}

​
Databricks

sources/databricks/connection.yaml
name: databricks
type: databricks
options:
  server_hostname: ${DATABRICKS_HOST}
  http_path: ${DATABRICKS_HTTP_PATH}
  access_token: ${DATABRICKS_TOKEN}

​
Working with Multiple Sources

​
Querying Multiple Databases

You can query different data sources on the same page: 
---
title: Cross-Database Analytics
queries:
  - warehouse_sales: warehouse_sales.sql      # From Snowflake
  - app_events: app_events.sql                # From PostgreSQL
  - local_targets: local_targets.sql          # From DuckDB
---

​
Joining Across Sources

Use inline SQL to join data from different sources:
combined_metrics
SELECT 
  w.month,
  w.total_sales,
  a.total_events,
  t.target
FROM ${warehouse_sales} w
LEFT JOIN ${app_events} a ON w.month = a.month
LEFT JOIN ${local_targets} t ON w.month = t.month

​
Query Organization

​
Source-Specific Queries

Store queries alongside their connection configuration: 
sources/
  snowflake/
    connection.yaml
    orders.sql
    customers.sql
  postgres/
    connection.yaml
    events.sql
    users.sql
Reference the full path in your pages: 
queries:
  - orders: snowflake/orders.sql
  - events: postgres/events.sql

​
Shared Queries

Place reusable queries in the queries/ directory: 
queries/
  orders_by_month.sql
  customer_summary.sql
  product_metrics.sql
Reference without a path: 
queries:
  - orders_by_month: orders_by_month.sql

​
Real Example: E-commerce Database

Here’s a complete example from the Evidence project:
sources/ecommerce/connection.yaml
name: ecommerce
type: duckdb
options:
  filename: ./ecommerce.duckdb
sources/ecommerce/orders.sql
SELECT * FROM orders
sources/ecommerce/orders_by_month.sql
SELECT 
  DATE_TRUNC('month', order_datetime) as month,
  COUNT(*) as num_orders,
  SUM(sales) as total_sales,
  SUM(sales) / COUNT(*) as avg_order_value
FROM orders
GROUP BY DATE_TRUNC('month', order_datetime)
ORDER BY month
Use in your page: 
---
queries:
  - orders_by_month: ecommerce/orders_by_month.sql
---

# E-commerce Dashboard

<LineChart 
  data={orders_by_month}
  x="month"
  y="total_sales"
  yAxisTitle="Revenue"
/>

​
Best Practices

​
Security

  • Never commit credentials - Use environment variables
  • Use read-only accounts - Evidence only needs SELECT permissions
  • Limit access scope - Grant access only to necessary schemas/tables
  • Rotate credentials - Update passwords regularly

​
Performance

  • Pre-aggregate data - Create summary tables in your warehouse
  • Use materialized views - For complex, frequently-used queries
  • Limit result sets - Use LIMIT or date filters for large tables
  • Index appropriately - Ensure your database has proper indexes

​
Organization

  • One source per directory - Keep connection files organized
  • Descriptive names - Use clear names like snowflake_prod or postgres_staging
  • Document connections - Add comments to YAML files explaining purpose
  • Version control - Commit connection files (without credentials)

​
Troubleshooting

​
Connection Fails

Check network access: Ensure your database allows connections from your IP Verify credentials: Test credentials using a database client Review SSL settings: Some databases require ssl: true or specific SSL modes

​
Queries Run Slowly

Add filters: Limit date ranges or row counts 
SELECT * FROM orders 
WHERE order_date >= CURRENT_DATE - INTERVAL '90 days'
Create indexes: Work with your DBA to add indexes on frequently queried columns Use query caching: Evidence caches query results during development

​
Environment Variables Not Working

Check .env file location: Must be in project root Restart dev server: Changes to .env require a restart Use correct syntax: ${VARIABLE_NAME} in YAML files

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us