Skip to main content

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.

​
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 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
  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:
FieldDescriptionExample
Connector NameA descriptive name to identify this connectionMy PostgreSQL Database
Host URLThe endpoint URL of your PostgreSQL databasedb.example.com
PortThe port number for your connection5432
UsernameYour PostgreSQL usernamepostgres
PasswordYour database password••••••••
DatabaseThe name of the database to connect topostgres
Schemas(Optional) Specific schemas to includepublic, 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:
FieldDescriptionExample
SSH HostThe hostname or IP of your bastion serverbastion.example.com
SSH PortThe SSH port on the bastion (default: 22)22
SSH UsernameThe OS-level user on the bastionec2-user
SSH Private KeyA PEM-formatted private key authorized on the bastion-----BEGIN OPENSSH PRIVATE KEY-----
SSH Host Public Key(Optional) The bastion’s public host key for verificationssh-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)
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).
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.

​
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
Having trouble connecting? See the Network Configuration Guide for firewall and IP whitelisting setup.

​
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