Skip to main content
To connect TextQL with Amazon Athena, you will need to set up appropriate AWS credentials and S3 access. Athena requires the following IAM permissions:
  • athena:StartQueryExecution
  • athena:GetQueryExecution
  • athena:GetQueryResults
  • s3:GetObject and s3:ListBucket for data locations
  • s3:PutObject for query results bucket
  • glue:GetTable and glue:GetPartitions (if using AWS Glue)

​
Creating the Connector in TextQL

Navigate to the TextQL Connectors Page and click Create New Connector. Select Amazon Athena from the available connectors to open the configuration form.
New Connector

Click Create Connector.

Click AWS Athena

Select AWS Athena.

The form requires the following information:
  • Connector Name: A descriptive name to identify this specific Athena connection in TextQL.
  • AWS Region: The AWS region where your Athena workgroup and data reside.
  • Database: The database/schema name in your catalog.
  • Catalog: (Optional) The AWS Glue Data Catalog name. Leave blank to use the default catalog for your account.
  • Workgroup: The Athena workgroup to use for queries. If left blank, defaults to primary.
  • S3 Output Location: S3 bucket path where Athena query results will be stored.
AWS Athena Connector Form

AWS Athena Connector Form.

​
Restrict queries to the configured database

Database normally sets the query default and table discovery scope. It does not reduce the AWS credentials’ permissions. Enable Restrict queries to this database to make TextQL enforce the configured catalog and database for direct table references. A database is required. This setting allows read queries only, and cannot be combined with SQL write operations. Existing connectors default to having this setting off. TextQL checks joins, subqueries, and CTEs before executing SQL and qualifies table references against the configured database. References to other catalogs or databases are rejected. Commands such as SHOW and DESCRIBE, table functions, user-defined functions, and unsupported SQL are rejected. If validation is unavailable, the query does not run. Query results and schema metadata are fetched without reusing cached results while this restriction is enabled. The restriction applies to every table and view in the configured database. An allowed view can expose data from another database. This is a TextQL query restriction and does not replace IAM or Lake Formation access controls. Scope the connector’s AWS credentials to the same database as well.

​
Authentication Methods

TextQL supports two AWS authentication methods for Athena: Access Key & Secret Provide static AWS credentials directly:
  • Access Key ID: Your AWS access key ID
  • Secret Access Key: Your AWS secret access key
  • Session Token: (Optional) A temporary session token, required when using short-lived credentials such as those vended by AWS STS.
IAM Role Assume an IAM role via STS. Both fields are required together:
  • IAM Role ARN: The ARN of the role to assume (e.g. arn:aws:iam::123456789012:role/MyRole)
  • Session Name: A name for the assumed role session

​
S3 Data Formats

Athena supports querying various data formats stored in S3:
  • Parquet: Recommended for analytics (columnar, compressed)
  • ORC: Optimized row columnar format
  • JSON: Semi-structured data
  • CSV: Comma-separated values
  • Avro: Schema evolution support

​
Testing the Connection

After entering your credentials, click Create to establish the connection. TextQL will validate your AWS permissions and create the connector. If the connection fails, verify your IAM permissions and S3 bucket access.
Having trouble connecting? See the Network Configuration Guide for firewall and IP whitelisting setup.