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

# Connection settings

> SSL, SSH tunnels, the IP allowlist, schema sync, and other settings for databases and warehouses you connect directly

export const action_0 = "add data sources"

export const details_0 = undefined

Connection settings control how Basedash reaches a database or warehouse you connect directly: its credentials, encryption, network path, and how Basedash reads its schema.

<Info>
  Only admins can {action_0}. {details_0}
</Info>

## Overview

When you add a database or warehouse, Basedash asks for its credentials and verifies the connection before saving it. Once connected, Basedash reads the schema so the AI knows which tables and columns exist, and runs queries directly against the source each time a chart or answer needs data.

For setup steps for a specific database, see its page under **Databases** or **Warehouses**. For SaaS tools, see [SaaS connectors](/docs/data-sources/connectors/index).

## Credentials

Most SQL databases use the same fields:

| Field | Notes |
| - | - |
| Host | The hostname or IP address of the database server |
| Port | The database port, such as 5432 for PostgreSQL or 3306 for MySQL |
| Database name | The database to connect to. Oracle calls this **Service name**. |
| Username | Use a dedicated, read-only user for Basedash |
| Password | Stored encrypted with AES-256 |

For PostgreSQL, Supabase, MySQL, and PlanetScale, you can leave the database name empty and pick a database after Basedash connects.

Some sources, such as BigQuery, Snowflake, Athena, and MotherDuck, use service accounts, keys, or tokens instead. See each source's page.

You can also paste a connection string, such as `postgresql://user:password@host:5432/database`, into the command menu (<kbd>Cmd/Ctrl</kbd> <kbd>K</kbd>) to start adding a data source with the fields filled in.

## SSL

Turn on **SSL** to encrypt the connection between Basedash and your database. Most cloud databases require it. Basedash doesn't support uploading custom CA or client certificates.

## Allowlist the Basedash IP

If your database or firewall only accepts known IP addresses, allow connections from:

```
24.199.77.73
```

All queries from Basedash cloud come from this address.

## SSH tunnel

Use an SSH tunnel when your database is in a private network that isn't reachable from the internet. Basedash connects to a bastion host you control, then to the database from there.

1. Turn on **Connect using SSH**.
2. Enter the **SSH host**, **SSH port** (usually 22), and **SSH username**.
3. Choose an **Authentication method**:
   * **Private key**: paste the private key, and its passphrase if it has one.
   * **Password**: enter the SSH user's password.
4. Allow `24.199.77.73` to reach the SSH host.

When you edit a connection, saved secrets aren't shown. Enter a new value to replace one, or click **Unset** to remove it.

## Manage a data source

Open the command menu with <kbd>Cmd/Ctrl</kbd> <kbd>K</kbd> and select a data source to:

* **Rename** it.
* **Edit AI context** to describe the data source for the AI. See [AI context](/docs/features/ai-context#data-source-context).
* **Sync schema** to read new or changed tables and columns.
* **Update credentials**, for example after rotating a password.
* Set up **Row level security**. See [Row-level security](/docs/administration/row-level-security).
* Manage **Access**. See [Data source access control](/docs/administration/data-source-access-control).
* See **Associated charts** that query this data source.
* **Delete data source**.

## Schema sync

Basedash reads your schema when you add a data source and when you click **Sync schema**. After a sync, Basedash also profiles your tables, collecting approximate row counts, how recent the newest rows are, and sample values for each column, so the AI can write better queries. Profiling is limited in time and skips tables that were profiled recently, so it doesn't put heavy load on your database.

If you add tables or columns and the AI doesn't know about them yet, run **Sync schema**.

### Ignore schemas and tables

Self-hosted deployments can turn on schema ignore patterns to leave schemas or tables out of syncs, for example temporary or staging tables. See [Self-hosting](/docs/self-hosting/overview).

## Query timeouts

Queries to PostgreSQL time out after about two minutes. If a chart times out, narrow its date range, add filters, or create a [model](/docs/features/models) that pre-aggregates the data.

## Troubleshooting

When Basedash can't connect, it shows one of these errors:

| Error | What to check |
| - | - |
| Host not found | The hostname is spelled correctly and resolves publicly. Private hostnames need an [SSH tunnel](#ssh-tunnel). |
| Connection timed out | Your firewall or security group allows `24.199.77.73`, and the database accepts external connections. |
| Incorrect port | The port matches your database. Nothing is listening on the port you entered. |
| Incorrect username or password | The credentials are current. Check for copied whitespace. |
| User not found | The user exists on this database server. |
| Database does not exist | The database name is spelled correctly and the user can access it. |
| Unable to connect to database | SSL settings match what your database requires, and the database is running. |

If the connection works but tables are missing, make sure the database user has `SELECT` permission on those schemas, then run **Sync schema**.

## FAQ

<AccordionGroup>
  <Accordion title="Does Basedash need write access?">
    No. Basedash works with read-only users, and we recommend one. If the user
    can write, the AI can propose changes on some databases, but only with your
    approval. See [Accuracy and
    trust](/docs/features/accuracy-and-trust#read-only-by-default).
  </Accordion>

  <Accordion title="How often does Basedash query my database?">
    Basedash queries your database when charts load, when the AI answers a
    question, and when automations, insights, or subscriptions run. With [query
    caching](/docs/administration/organization-settings#query-caching) on, charts
    show cached results first and refresh in the background.
  </Accordion>

  <Accordion title="Can I connect a database on localhost?">
    Not from Basedash cloud. The database must be reachable from the internet,
    directly or through an SSH tunnel. For fully private networks, consider
    [self-hosting](/docs/self-hosting/overview).
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Choose how to connect" icon="database" href="/docs/data-sources/introduction">
    Compare direct connections, connectors, and Basedash Warehouse.
  </Card>

  <Card title="Data source access control" icon="lock" href="/docs/administration/data-source-access-control">
    Choose who can query each data source.
  </Card>

  <Card title="Security and compliance" icon="shield" href="/docs/administration/security">
    How Basedash protects your credentials and data.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/docs/help/troubleshooting">
    Fix common problems.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.