PostgreSQL Connector

​

Overview

​

Prerequisites

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

​

Finding Your Connection Details

​

Connection String Format

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

​

Example Connection String Breakdown

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

• 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

​

Step 3: Enter Connection Details

​

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

​

Authenticating with AWS Secrets Manager

​

Setting Up Secrets Manager Authentication

1. In the PostgreSQL connector form, set How should users authenticate? to AWS Secrets Manager
2. Enter the Secret ARN of the secret holding your database credentials
3. (Optional) Enter an IAM Role ARN for TextQL to assume when reading the secret, plus the External ID its trust policy requires

• RDS-style JSON with username and password keys (the format AWS RDS uses for managed secrets), or
• A plain-text password (set the username on the connector form instead)

​

Cross-Account Access with an IAM Role

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-east-1:111122223333:secret:my-db-credentials-AbCdEf"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::444455556666:role/your-textql-service-role"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "sts:ExternalId": "your-external-id" }
      }
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::444455556666:role/your-textql-service-role"
      },
      "Action": "sts:TagSession"
    }
  ]
}

​

Secrets Manager Troubleshooting

• The trust policy of the role in the IAM Role ARN field grants sts:AssumeRole but not sts:TagSession. Add a separate sts:TagSession statement as shown above.
• The trust policy grants both actions in a single statement with an sts:ExternalId condition. Split them into separate statements: the condition can never match for sts:TagSession, so the shared statement denies it.
• If the trust policy is already correct, the TextQL service role’s own IAM policy may be missing sts:TagSession for your role: for cross-account roles, both accounts must allow it. Ask your TextQL contact to verify.

• The trust policy’s Principal does not match the TextQL service role, or the External ID in the form does not match the trust policy condition.

• The role’s permissions policy does not cover the secret ARN, or the secret’s resource policy denies access. If the secret uses a customer-managed KMS key, check kms:Decrypt as well.

• The secret value is JSON but has no password key. Use RDS-style {"username": ..., "password": ...} JSON or a plain-text password.

​

Connecting via SSH Tunnel

​

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

​

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)

​

How It Works

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

• 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)

• 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

• 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

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

​

Authentication Errors

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

​

Timeout Errors

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

​

What’s Next

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