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

# PostgreSQL Connector

> Connect TextQL to your PostgreSQL database

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/f2xv9SFH8fg" title="How to Connect PostgreSQL to TextQL | AI Data Analysis Tutorial" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

## Overview

This guide walks you through connecting TextQL to your PostgreSQL database. You'll need connection credentials from your PostgreSQL account to complete the setup.

## Prerequisites

To connect TextQL with your PostgreSQL database, you will need:

* **Host URL** and **Port** (default: 5432)
* **Username** and **Password**
* **Database** name (default: postgres)
* **Schemas** (optional, if you want to specify specific schemas)

If your database is behind a private network and only accessible through a bastion host, you will also need SSH tunnel credentials. See [Connecting via SSH Tunnel](#connecting-via-ssh-tunnel) below.

## Finding Your Connection Details

### Connection String Format

Most PostgreSQL providers display the connection string in this format:

```
postgresql://username:password@host:port/database
```

### Example Connection String Breakdown

```
postgresql://username:pass123@db.example.com:5432/mydb
                ↑       ↑            ↑        ↑    ↑
           username   password     host     port  database
```

From this connection string, you can extract:

* **Host URL**: `db.example.com`
* **Port**: `5432`
* **Username**: `username`
* **Password**: `pass123`
* **Database**: `mydb`

## Creating the Connector in TextQL

### Step 1: Navigate to Connectors Page

1. Go to the [TextQL Connectors Page](https://app.textql.com/connectors)
2. Click **New Connector**

### Step 2: Select PostgreSQL

Select **Postgres** from the available connectors to open the configuration form.

### Step 3: Enter Connection Details

The form requires the following information:

| Field              | Description                                    | Example                  |
| ------------------ | ---------------------------------------------- | ------------------------ |
| **Connector Name** | A descriptive name to identify this connection | `My PostgreSQL Database` |
| **Host URL**       | The endpoint URL of your PostgreSQL database   | `db.example.com`         |
| **Port**           | The port number for your connection            | `5432`                   |
| **Username**       | Your PostgreSQL username                       | `postgres`               |
| **Password**       | Your database password                         | `••••••••`               |
| **Database**       | The name of the database to connect to         | `postgres`               |
| **Schemas**        | (Optional) Specific schemas to include         | `public, analytics`      |

### Step 4: Test and Create

1. Click **Test Connection** to verify your credentials and network access
2. Once the test succeeds, click **Create Connector** to save the connection

## Connecting via SSH Tunnel

If your PostgreSQL database is in a private subnet and not directly reachable from the internet, you can connect through an SSH tunnel (also called a bastion host or jump server). TextQL will open an encrypted SSH connection to your bastion host and forward database traffic through it.

### When to Use an SSH Tunnel

* Your database is in a private VPC with no public endpoint
* Your security policy requires all external access to go through a bastion host
* You cannot or prefer not to whitelist TextQL's IP addresses directly on the database

### SSH Tunnel Prerequisites

In addition to your standard database credentials, you will need:

| Field                   | Description                                               | Example                               |
| ----------------------- | --------------------------------------------------------- | ------------------------------------- |
| **SSH Host**            | The hostname or IP of your bastion server                 | `bastion.example.com`                 |
| **SSH Port**            | The SSH port on the bastion (default: 22)                 | `22`                                  |
| **SSH Username**        | The OS-level user on the bastion                          | `ec2-user`                            |
| **SSH Private Key**     | A PEM-formatted private key authorized on the bastion     | `-----BEGIN OPENSSH PRIVATE KEY-----` |
| **SSH Host Public Key** | (Optional) The bastion's public host key for verification | `ssh-ed25519 AAAA...`                 |

### Setting Up the SSH Tunnel

1. In the PostgreSQL connector form, check **Connect via SSH tunnel (bastion host)**
2. The SSH configuration fields will appear below the standard connection fields
3. Enter your bastion host, port, username, and private key
4. For **Host URL** and **Port** in the main connection fields, enter the database's **private** address (the address reachable from the bastion host, not from the public internet)

<Tip>
  The **SSH Host Public Key** field is optional but recommended. Providing it allows TextQL to verify the bastion host's identity and prevents man-in-the-middle attacks. You can find this value on the bastion server at `/etc/ssh/ssh_host_ed25519_key.pub` (or the equivalent for your key type).
</Tip>

<Warning>
  Your SSH private key is stored encrypted and is never exposed in the UI after saving. If you need to rotate the key, edit the connector and provide the new key.
</Warning>

### How It Works

When TextQL connects to your database through an SSH tunnel:

1. TextQL establishes an encrypted SSH connection to your bastion host
2. A secure tunnel is created from TextQL through the bastion to your database's private address
3. All database queries are forwarded through this tunnel
4. The tunnel is torn down after the session ends

```
TextQL  ──SSH──▶  Bastion Host  ──TCP──▶  PostgreSQL (private subnet)
```

### SSH Tunnel Troubleshooting

**"Failed to establish SSH tunnel"**

* Verify the bastion host is reachable from the internet on the specified SSH port
* Confirm the SSH username and private key are correct
* Ensure the private key is in PEM format (starts with `-----BEGIN`)
* Check that the bastion's security group allows inbound SSH from TextQL's IPs (`44.229.62.69` and `54.69.138.147`)

**"Connection test failed" (after tunnel succeeds)**

* The SSH tunnel connected, but the database is not reachable from the bastion. Verify:
  * The database host and port are correct (use the **private** address)
  * The bastion host has network access to the database
  * Database security groups allow inbound connections from the bastion

**"Host key verification failed"**

* The SSH Host Public Key you provided does not match the bastion server's actual host key. Retrieve the correct key from the bastion and update the connector.

## Troubleshooting

### Connection Fails

**Verify the following:**

* Connection credentials are correct
* Host URL and port are accurate
* Database name is spelled correctly
* PostgreSQL server is running and accessible

<Note>
  Having trouble connecting? See the [Network Configuration Guide](/core/datasources/databases/network-configuration) for firewall and IP whitelisting setup.
</Note>

### Authentication Errors

**Check:**

* Username and password are correct
* User has appropriate permissions
* Password doesn't contain special characters that need escaping

### Timeout Errors

**Possible causes:**

* Firewall blocking connection
* Incorrect host URL or port
* Database server not responding
* Network connectivity issues

## What's Next

Once your PostgreSQL connector is set up, you can:

* Ask Ana natural language questions about your data
* Generate SQL queries and visualizations
* Create reports and dashboards
* Share insights with your team