> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supaboard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Sources

A **Data Source** is a live connection from Supaboard to an external database or service. Every widget on a dashboard, every query run through [Ask Analysts](./ask-agents), and every Agent's knowledge of your data flows through these connections.

# The Connections Page

**Settings → Connections** is the administrative home for all your data source connections.

Each connection is shown as a card displaying:

* The connector logo
* The connection name
* Table count (e.g. *5 tables*)

Click any card to open its **Connection Detail** panel, which has five tabs: **Info**, **Tables**, **Summary**, **Standard Instructions**, and **Advanced**.

**Search** connections by name or connector type using the search bar.

# The Data Source Browser

The **Data Sources** section in the main sidebar is the analyst-facing view — browse, explore, and interact with your connected data.

## Filtering connections

| Filter      | What it shows                            |
| ----------- | ---------------------------------------- |
| **All**     | Every connection                         |
| **Active**  | Connected and ready to query             |
| **Pending** | Connected but currently syncing          |
| **Failed**  | Previously connected but now unreachable |

Search across connections by name, connector type, or database.

## View modes

Toggle between **Card** and **List** views.

## Item actions

From any data source item's action menu:

| Action         | Description                                        |
| -------------- | -------------------------------------------------- |
| **Open**       | Navigate to the table browser for this connection  |
| **Rename**     | Change the display name                            |
| **Favourite**  | Pin to the top of the list                         |
| **Ask Stella** | Start an AI conversation scoped to this connection |
| **Delete**     | Remove the connection                              |

> The **Ask Stella** action opens [Ask Analysts](./ask-agents) — the button label hasn't caught up with the feature's name yet.

# Adding a Connection

Click **New Connection** from either the Connections page or the Data Source Browser. A searchable grid shows all available connectors — select one to open its configuration form.

## Direct database connections

For databases (PostgreSQL, Snowflake, etc.), you connect directly by entering your host, credentials, and any advanced options (SSL, SSH tunnel). See [Available Connectors](#available-connectors) for the full list.

## Non-database connections via Fivetran

For SaaS tools and third-party services (Shopify, Google Analytics, Airtable, Stripe, and others), Supaboard uses **Fivetran** as the ETL layer. Fivetran handles syncing data from those services into a queryable form — you authenticate with the source service through Fivetran's OAuth flow, and Supaboard takes care of the rest.

Some of these connectors are included on every plan and some require an upgrade — see [Available Connectors](#available-connectors). The connector grid tells you which is which before you commit: a connector that needs an upgrade shows an upgrade prompt when you select it.

## What happens after you save

1. Supaboard creates the connection record.
2. Tables in the database are discovered automatically.
3. Schema generation runs in the background — column metadata is extracted for each table.
4. The connection becomes queryable by agents and widgets once schema generation completes.

> For large databases with many tables, schema generation runs as a background job. You can navigate away and return — the connection will show a *Pending* status until it's ready.

# Available Connectors

The connector grid holds well over a hundred integrations and is searchable by name. The tables below cover the ones with a dedicated setup guide, plus which are included on every plan.

## Direct database connectors — all plans

| Connector                                         | Notes                                        |
| ------------------------------------------------- | -------------------------------------------- |
| [**PostgreSQL**](/postgres)                       | Supports SSH tunnel, SSL, JDBC params        |
| [**MySQL**](/mysql)                               | Supports SSH tunnel, SSL, JDBC params        |
| [**Snowflake**](/snowflake)                       | Includes warehouse and schema auto-discovery |
| [**BigQuery**](/big-query)                        | OAuth or Service Account JSON authentication |
| [**Amazon Redshift**](/redshift)                  | Supports SSH tunnel, SSL                     |
| [**MongoDB**](/mongodb)                           | Connection string (URI) based                |
| [**ClickHouse**](/clickhouse)                     | —                                            |
| [**Databricks**](/databricks)                     | Personal access token + HTTP path            |
| [**Supabase**](/supabase)                         | SSL on by default                            |
| [**Microsoft SQL Server**](/microsoft-sql-server) | Supports SSH tunnel, SSL, JDBC params        |
| **MotherDuck / DuckDB**                           | Database, schema, and MotherDuck token       |

## Fivetran-powered connectors

These sync through Fivetran. The following are **included on every plan**, alongside the direct databases above:

Google Analytics · Typeform · Calendly · Stripe · Linear · Asana · YouTube Analytics · Notion · Auth0 · Airtable

Everything else in the catalogue — including Shopify — requires an upgrade. Selecting one shows the upgrade prompt with the plan you'd need; see [pricing](https://supaboard.ai/pricing).

[Learn more about Fivetran-powered connectors here.](/fivetran)

## Fivetran sources keep their own identity

A source synced through Fivetran lands in a shared warehouse, but Supaboard attributes it to the **original service**. A Stripe-via-Fivetran connection shows Stripe's name and logo everywhere — the data source card, the connection header, the resource picker — rather than the warehouse it physically lives in.

# Testing a Connection

Every connector form has a **Test Connection** button in the footer. Click it before saving to verify that Supaboard can reach the database with the credentials provided.

* On success: a toast confirms the database is responding.
* On failure: the error message from the database is shown, helping you diagnose the issue (wrong password, firewall block, incorrect port, etc.).

> Always test before saving. A saved connection that can't connect will show as *Failed* and block agents and widgets that depend on it.

# Connection Detail — Info Tab

Open any connection card to see the **Info** tab, which shows live diagnostics.

## Performance metrics

* Response time
* Query latency
* Connection pool stats

## Security status

* SSL/TLS enabled state
* Encryption status
* Authentication type

## Connection pool *(direct database connectors only)*

* Active connections
* Idle connections
* Maximum pool size

> Pool status is not shown for Fivetran-backed sources. Supaboard does not hold a direct connection to them, so there is no pool to report.

## Tunnel status *(SSH tunnel connections)*

* Tunnel connection state
* Tunnel latency

## Database info

* Database version, charset, and collation
* Visible only to users with resource access

## Warnings & errors

Any active warnings are listed. Errors are shown in a red alert box with details.

# Connection Detail — Tables Tab

The **Tables** tab is where you manage which tables Supaboard knows about and what it knows about them.

## Table list

Every table discovered in the database is listed here. For each table:

| Action                | What it does                                                                                  |
| --------------------- | --------------------------------------------------------------------------------------------- |
| **Hide / Show**       | Toggle whether this table appears in the data browser and is accessible to agents and widgets |
| **Regenerate Schema** | Re-scans this table's columns and rebuilds its metadata                                       |

The footer shows a count of how many tables are currently hidden.

## Missing schema banner

If any tables are missing schema (column metadata hasn't been generated), a yellow banner appears at the top. Click **Regenerate Schemas** to rebuild all of them at once.

> Schema generation polls in the background every 20 seconds. A loading overlay appears during bulk regeneration.

## Remapping tables

Click **Remap Tables** to re-scan the database and discover any tables that have been added or removed since the connection was created. New tables are added to the list; removed tables are flagged.

# Connection Detail — Summary Tab

The **Summary** tab holds a free-text description of the entire database — its purpose, what systems write to it, and any high-level context that helps your agents and your team understand what it contains.

Write in plain language. This summary is read by agents when deciding whether and how to query this data source.

# Connection Detail — Standard Instructions Tab

**Standard Instructions** are rules that apply to every query written against this connection, regardless of which agent asks. Use them for conventions that belong to the *database* rather than to any one agent:

* Which column to join on when several look plausible
* A soft-delete convention every query must respect — *"always exclude rows where `is_archived = true`"*
* A canonical date column when a table has several
* Dialect quirks specific to this deployment

> The difference between this and an agent's [Rules](./agents#rules): standard instructions travel with the *connection*, so every agent that includes this source inherits them. Agent rules travel with the *agent*, across whatever sources it can see.

# Connection Detail — Advanced Tab

The **Advanced** tab contains operations that modify or remove the connection.

## Rename connection

Update the display name that appears across the UI, in agents, and in widget configurations.

## Regenerate schema

Rebuilds schema metadata for all tables in this connection. Use this if your database structure has changed significantly (new columns added, types changed, tables restructured).

> This operation is permanent and cannot be undone — existing schema metadata is replaced.

## Delete connection

Permanently removes the connection from Supaboard. A confirmation is required.

**What happens on deletion:**

* The connection and its table metadata are removed.
* Dashboards with widgets that queried this connection will show errors on those widgets.
* Agents that included this connection in their scope lose access to it.

> Deletion cannot be undone.

# Team Access Control

By default, all workspace members can query any data source. You can restrict a specific connection to only certain team members.

Open the connection's **Advanced** tab and scroll to **Team Access**. Every non-deleted workspace member is listed with a toggle:

| State                 | Meaning                                         |
| --------------------- | ----------------------------------------------- |
| **Toggle on**         | This member can query this connection           |
| **Toggle off**        | This member cannot query this connection        |
| **Owner** (locked on) | Owners always have access and cannot be removed |

Changes are saved automatically with a short debounce.

## How this interacts with agent access

If a team member is blocked from a data source but an agent they use includes that source in its scope, the member will not be able to retrieve data from that source through the agent. The restriction is enforced at the connection level, regardless of agent configuration.

# Schema Generation

Schema generation is the process of scanning a table's columns, types, and relationships to build the metadata that agents use to write accurate queries.

## When it runs

* **Automatically** when a new connection is created.
* **On demand** via the Regenerate button (per-table or bulk).
* **After remapping** when new tables are discovered.

## Incremental context refresh

Alongside raw schema, Supaboard writes an AI-generated description of each table. Refreshing that context is **incremental**: only tables that don't already have a description are processed.

Adding one table to a 400-table database no longer means regenerating descriptions for the other 399 — which is the difference between a refresh that takes seconds and one that takes many minutes.

## What gets discovered

Beyond ordinary tables, Supaboard discovers **views, materialized views, foreign tables, and partitioned tables**. Materialized views in particular are introspected properly, so a dashboard built on a pre-aggregated matview reports real columns rather than an empty schema.

For PostgreSQL, the default `postgres` database is included in discovery alongside your own databases.

## Schema statuses

| Status         | Meaning                                                                               |
| -------------- | ------------------------------------------------------------------------------------- |
| **Generated**  | Column metadata is complete and up to date                                            |
| **Missing**    | Schema hasn't been generated yet — agent queries against this table may be inaccurate |
| **Generating** | Schema is currently being built (polls every 20 seconds)                              |

> Tables with missing schema are flagged in the Tables tab and in any Agent that includes them. Always resolve missing schemas before using a connection in production.

# Database Context (Documentation)

Beyond raw schema, Supaboard lets you document what your data *means* at two levels: the whole database and individual tables. This context is read by agents to improve answer accuracy.

## Database-level summary

Written in the **Summary** tab. A high-level overview of the database's purpose and contents.

## Table-level context

For each table in the **Tables** tab, you can fill in four fields:

| Field           | What to write                                                     |
| --------------- | ----------------------------------------------------------------- |
| **Summary**     | What this table stores and how it relates to other tables         |
| **Granularity** | What each row represents — e.g. *"One row per invoice line item"* |
| **Gotchas**     | Data quality issues, quirks, or caveats agents should be aware of |
| **Usecases**    | Common questions this table is useful for answering               |

> Context written here is shared with any Agent that includes this data source. You do not need to re-enter it per agent — it flows through automatically.

# Column Values and Filter Suggestions

When someone builds a dashboard filter or picks a value in the query builder, Supaboard fetches the distinct values for that column.

| Behaviour             | Detail                                                                                                                                         |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Search and paging** | Values are searched and paged at the database level for connectors that support it, so a column with a million distinct values is still usable |
| **True totals**       | You see the real count of matching distinct values, not just how many are on the current page                                                  |
| **Cascading filters** | Suggestions narrow to rows matching the dashboard filters already applied — pick a country and the city list shrinks to that country           |

> Cascading suggestions only apply to filters whose table matches the column being searched, and only on connectors that push the search down into SQL. On connectors that fall back to in-memory filtering, cascading filters are **ignored** and you see the unfiltered value list. If a suggestion list looks wider than expected, that fallback is the likely reason.

## Promoting a column to an enum

A low-cardinality column can be marked as an enum so filters render as a picker rather than a free-text box. Supaboard checks the column first and refuses if it has **more than 1000 distinct values** — an enum with more than that is not a usable picker.

# Connection Statuses

| Status           | Indicator     | Meaning                                                             |
| ---------------- | ------------- | ------------------------------------------------------------------- |
| **Active**       | Green dot     | Connected and ready to query                                        |
| **Pending**      | Spinner       | Connected; schema generation or sync in progress                    |
| **Failed**       | Red indicator | Was connected but is now unreachable — check credentials or network |
| **Disconnected** | Grey          | No tables have been loaded yet                                      |

A failed connection will cause widgets and agents that depend on it to return errors. Open the connection's Info tab to see the specific error message.

> **PostgreSQL read replicas.** Reads against a hot standby are occasionally cancelled by the replica applying WAL — a transient conflict, not a real failure. Supaboard detects these and retries automatically, so replica-backed dashboards don't fail spuriously under replication load. Genuine errors are not retried.

# Egress IP Whitelist

If your database is behind a firewall, you need to allow inbound connections from Supaboard's egress IPs.

Navigate to any connector form and look for the **Whitelist IPs** section. The current list of Supaboard egress IP addresses is shown there — copy them and add them to your database's firewall allow-list before attempting a connection.

# Permissions

| Action                        | Minimum role                  |
| ----------------------------- | ----------------------------- |
| View available data sources   | Viewer (with resource access) |
| Browse tables                 | Viewer (with resource access) |
| Create a connection           | Admin                         |
| Edit connection name          | Admin                         |
| Delete a connection           | Admin · Owner                 |
| Manage team access            | Owner                         |
| Regenerate schema             | Admin                         |
| Remap tables                  | Admin                         |
| Edit database / table context | Admin                         |
| Test a connection             | Admin                         |

Resource-level restrictions (set per connection) are enforced on top of workspace roles — a Viewer who has been blocked from a specific data source cannot query it regardless of other permissions.