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

# PostgreSQL

> Connect an external PostgreSQL database for AI-powered read-only queries

## Overview

Connect a PostgreSQL database to Telemetron so the AI support agent can run read-only SQL queries against your data during customer conversations. This allows the agent to look up order history, account details, device records, or any other data stored in your database.

## Prerequisites

* A PostgreSQL database accessible from the internet (or via a static IP allowlist)
* A database user with read-only permissions (recommended)
* The database connection string

## Setup

<Steps>
  <Step title="Open the Integration Page">
    Go to **Settings > Integrations > PostgreSQL**.
  </Step>

  <Step title="Enter Connection String">
    Provide your PostgreSQL connection string in the following format:

    ```
    postgresql://user:password@host:5432/dbname
    ```

    SSL is enabled by default. To disable SSL, append `?sslmode=disable` to the connection string:

    ```
    postgresql://user:password@host:5432/dbname?sslmode=disable
    ```
  </Step>

  <Step title="Test and Connect">
    Click **Test Connection** to verify Telemetron can reach your database. If successful, click **Connect PostgreSQL** to finalize the integration.
  </Step>
</Steps>

## Configuration

### Security Requirements

* **Read-only user** — Create a dedicated database user with only `SELECT` privileges. Telemetron will only execute `SELECT` queries, but a restricted user provides defense in depth.
* **Network access** — The database must be accessible from Telemetron's servers. Ensure your firewall or security group allows inbound connections on the PostgreSQL port.
* **SSL** — SSL is enabled by default for encrypted connections. Only disable SSL if your database does not support it.

Example read-only user setup:

```sql theme={null}
CREATE USER telemetron_readonly WITH PASSWORD 'your-secure-password';
GRANT CONNECT ON DATABASE yourdb TO telemetron_readonly;
GRANT USAGE ON SCHEMA public TO telemetron_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO telemetron_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO telemetron_readonly;
```

### Schema Browser

After connecting, the schema browser displays all discovered tables with their columns, data types, and nullable status. Click **Refresh Schema** to update the schema if your database structure changes.

## How It Works

The AI support agent generates and executes read-only SQL queries against your connected database. During a conversation, when a customer question requires data lookup, the agent formulates a `SELECT` query, runs it against your database, and uses the results to provide an informed response. Only `SELECT` statements are executed — no data is modified.

## Troubleshooting

| Issue                             | Resolution                                                                                                                  |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Connection test fails**         | Verify the connection string format, credentials, host, and port. Ensure the database is accessible from external networks. |
| **SSL connection errors**         | If your database does not support SSL, append `?sslmode=disable` to the connection string.                                  |
| **Permission denied**             | Ensure the database user has `SELECT` privileges on the tables you want the agent to access.                                |
| **Schema not showing all tables** | The user may not have `USAGE` permission on all schemas. Grant access to additional schemas as needed.                      |
| **Slow query responses**          | Consider adding indexes to commonly queried columns. The AI agent's queries are read-only but may scan large tables.        |