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.

To connect TextQL with your Firebolt account, you will need to gather the following connection details:
  • Account name
  • Database and engine
  • Service account credentials (client ID and secret)

​
Creating the Connector in TextQL

Navigate to the TextQL Connectors Page and click Create New Connector. Select Firebolt from the available connectors to open the configuration form. The form requires the following information:
  • Connector Name: A descriptive name to identify this Firebolt connection in TextQL.
  • Account: Your Firebolt account name (the URL slug shown in the Firebolt console, e.g., account-1). Lowercase, kebab-case — this is the system name, not the display name.
  • Engine: Name of the engine to run queries on (e.g., my_engine). Leave blank to use the account’s default engine.
  • Database: The database the connector should query (e.g., my_database).
  • Schemas: Optional comma-separated list of schemas to scope table discovery (e.g., public, analytics). If left blank, the public schema is used.

​
Authentication

Firebolt uses service accounts with OAuth client-credentials. TextQL authenticates as a service account user — you’ll need to create one (or reuse an existing one) and supply its client ID and secret.

​
Generating Service Account Credentials

  1. Log in to the Firebolt console as an account admin.
  2. Open Configure → Service accounts and click Create service account.
  3. Give it a name, copy the Service account ID and Service account secret that are shown.
The service account secret is shown only once. Copy and save it immediately after creation. If you lose it, you must rotate the secret or create a new service account.
  1. Open Configure → Users, create or pick an existing user, and set its Associated service account to the one you just created. Without this association the connector will fail with “provided account name does not exist in this organization or is not authorized”.
  2. Grant the user’s role the privileges TextQL needs: 
GRANT USAGE ON DATABASE "<database>" TO ROLE "<role>";
GRANT USAGE ON SCHEMA "<database>"."<schema>" TO ROLE "<role>";
GRANT SELECT ON ALL TABLES IN SCHEMA "<database>"."<schema>" TO ROLE "<role>";

-- Future tables created in this schema will be visible too:
ALTER DEFAULT PRIVILEGES IN SCHEMA "<database>"."<schema>"
  GRANT SELECT ON TABLES TO "<role>";
The built-in public role does not have access to user-created databases by default — using a purpose-built role (or account_admin for testing) is the simplest path.

​
Engines

A Firebolt engine is a compute resource attached to one database. When choosing an engine name for the connector form:
  • The engine must be attached to the database in the Database field. If they don’t match, the connection will succeed but information_schema.tables will return only metadata views — no user tables will be visible.
  • The engine must be started (or set to auto-start) before TextQL can query it. Stopped engines return connection errors.
  • Different engines on the same account can have different sizes/configurations. Pick one sized appropriately for analytical queries.

​
Schemas

Firebolt databases use schemas to namespace tables (e.g., public.players). When you specify schemas like public, analytics, TextQL discovers all tables and views in those schemas. If you leave the Schemas field blank, TextQL defaults to the public schema.

​
Testing the Connection

After entering your credentials, click Create to establish the connection. TextQL will validate your credentials, run a test query, and create the connector. If the connection fails:
  • “account name does not exist in this organization or is not authorized” — the account name is misspelled, the service account isn’t linked to a user, or the user lacks access to the account.
  • No tables visible after connecting — the engine isn’t attached to the target database, or the service account’s role doesn’t have USAGE/SELECT privileges on the schema.
Having trouble connecting? See the Network Configuration Guide for firewall and IP whitelisting setup. The Firebolt SDK uses HTTPS over port 443 to id.app.firebolt.io (OAuth) and api.firebolt.io (queries) — ensure your firewall allows outbound HTTPS to both.

​
Next Steps

Once connected, you can use TextQL to query your Firebolt data. The connector supports querying any schema accessible to your service account’s role. For optimal performance and security:
  • Use a dedicated service account and role for TextQL — don’t reuse human user credentials
  • Grant only the privileges the connector needs (USAGE + SELECT); avoid account_admin in production
  • Specify schemas to limit table discovery scope
  • Keep the connector’s engine attached to the database it queries