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

# External Databases

> Connect your existing PostgreSQL, MySQL, and Amazon Redshift databases to use their data in Vybe apps

You can connect your existing databases to Vybe and use their data across your apps. This lets you build internal tools on top of production data without moving or duplicating it.

***

## Supported databases

| Database            | Authentication                              | SSH Tunnel | Read-only Mode |
| ------------------- | ------------------------------------------- | ---------- | -------------- |
| **PostgreSQL**      | Connection string or individual credentials | Yes        | Yes            |
| **MySQL**           | Connection string or individual credentials | Yes        | Yes            |
| **Amazon Redshift** | AWS IAM role assumption                     | No         | No             |

***

## Connecting a database

<Steps>
  <Step title="Open the Integrations page">
    Navigate to **Integrations** in the left sidebar and scroll to the **Databases** section.
  </Step>

  <Step title="Select your database type">
    Click **Connect Database** and choose **PostgreSQL**, **MySQL**, or **Amazon Redshift**.
  </Step>

  <Step title="Enter connection details">
    For PostgreSQL and MySQL, provide either a connection string or individual credentials (host, port, database name, username, password). For Amazon Redshift, provide your cluster details and IAM role ARN. Redshift uses AWS IAM role assumption for secure, credential-free access.
  </Step>

  <Step title="Configure connection options">
    Optionally enable **read-only mode** to prevent accidental writes, or **SSH tunnel** to route the connection through an SSH tunnel for databases behind a firewall.
  </Step>

  <Step title="Test and save">
    Vybe validates the connection before saving. If the connection fails, check your credentials, firewall rules, and SSH configuration.
  </Step>
</Steps>

<Warning>
  Enable read-only mode for production databases to prevent accidental data modification. All workspace members can query connected databases, so read-only mode provides an important safety net.
</Warning>

***

## Read-only mode

When read-only mode is enabled, Vybe enforces read-only transactions on every query to the database. This means:

* `SELECT` queries work normally
* `INSERT`, `UPDATE`, `DELETE`, and DDL statements are blocked
* The AI cannot modify your data, even if you ask it to

This is the recommended setting for production databases. You get full read access for dashboards, reports, and data exploration without any risk of accidental writes.

***

## SSH tunnel connections

For databases behind a firewall or in a private network, Vybe supports SSH tunnel connections.

<Steps>
  <Step title="Create an SSH key">
    On the **Integrations** page, scroll to the **SSH Keys** section and click **Create SSH Key**. Vybe generates a public/private key pair.
  </Step>

  <Step title="Add the public key to your server">
    Copy the public key and add it to the `~/.ssh/authorized_keys` file on your SSH bastion host or jump server.
  </Step>

  <Step title="Connect the database with SSH">
    When connecting a database, enable the **SSH tunnel** option and provide the SSH host, port, username, and the SSH key you created.
  </Step>

  <Step title="Save and verify">
    Vybe connects to your SSH server first, then tunnels the database connection through it. The test step verifies both the SSH connection and the database connection.
  </Step>
</Steps>

<Tip>
  SSH keys can be reused across multiple database connections. Create one key for your bastion host and use it for all databases accessible from that server.
</Tip>

***

## Organization-wide access

Connected databases are available to all members of your organization. Once you connect a database, any team member can:

* Query it from the AI chat in any app
* Use it as a data source when building apps
* Reference it in saved data queries

There is no per-app database configuration — connected databases are shared at the organization level.

***

## Using external databases

Once connected, you can interact with external databases in two ways:

### Through the AI chat

Ask the AI to query your external database directly during a conversation:

> Show me the top 10 customers by revenue from our analytics database.

> How many orders were placed last month in the production database?

The AI identifies which connected database to query, writes the SQL, executes it, and displays the results inline.

### From app code

The AI generates server-side code that queries your external databases using Vybe's helper functions. Each database type has its own helper with parameterized query support.

```typescript theme={null}
import { queryExternalDatabasePostgres } from '@/server-lib/external-db-postgres';

const customers = await queryExternalDatabasePostgres(
  'My Analytics DB',
  'SELECT name, revenue FROM customers ORDER BY revenue DESC LIMIT 10',
  []
);
```

***

## Redshift specifics

Amazon Redshift connections work differently from PostgreSQL and MySQL:

* **Authentication**: Uses AWS IAM role assumption instead of username/password credentials. You provide the IAM role ARN that Vybe assumes to access your cluster.
* **No SSH tunnel**: Redshift connections do not support SSH tunneling. Ensure your Redshift cluster is accessible from Vybe's IP range.
* **Asynchronous queries**: Redshift queries are executed asynchronously. The helper function returns a result object with a status field that you should check before accessing the data.

```typescript theme={null}
const result = await queryExternalDatabaseRedshift(
  'My Redshift Cluster',
  'SELECT * FROM sales WHERE region = :region',
  { region: 'us-east' }
);

if (result.status === 'FINISHED') {
  // Access result.records
}
```

***

## Troubleshooting

<Accordion title="Connection timed out">
  Check that your database is accessible from external networks. If it is behind a firewall, use an SSH tunnel connection. Verify that the host, port, and credentials are correct.
</Accordion>

<Accordion title="SSH tunnel failed">
  Confirm that the public key is added to your server's `authorized_keys` file. Verify the SSH host, port, and username. Ensure the SSH server allows tunneling (check `AllowTcpForwarding` in your SSH config).
</Accordion>

<Accordion title="Permission denied on queries">
  Your database user may not have access to the tables you are querying. Check the user's permissions and grant `SELECT` access to the relevant schemas and tables.
</Accordion>