Skip to main content
Query Exporter uses SQLAlchemy to connect to various database engines. This guide covers supported databases, driver installation, and database-specific configuration.

​
Supported Databases

Query Exporter supports the following database engines:
  • PostgreSQL (postgresql://)
  • MySQL (mysql://)
  • Oracle (oracle+oracledb://)
  • Microsoft SQL Server (mssql+pymssql://)
  • SQLite (sqlite://)
  • IBM DB2 (db2://)
  • ClickHouse (clickhouse+native://)
  • Teradata (teradatasql://)

​
Driver Installation

SQLAlchemy doesn’t include database drivers by default. You need to install the appropriate driver for your database engine.

​
Install via pip

Install drivers using SQLAlchemy extras: 
pip install SQLAlchemy[postgresql] SQLAlchemy[mysql]

​
Common Database Drivers

For the most common databases, install these packages: 
# PostgreSQL
pip install psycopg2-binary

# MySQL
pip install mysqlclient

# Oracle
pip install oracledb

# Microsoft SQL Server
pip install pymssql

​
Using Docker

The official Docker image includes drivers for:
  • PostgreSQL
  • MySQL
  • SQLite
  • Microsoft SQL Server
  • IBM DB2 (x86_64 only)
  • Oracle
  • ClickHouse
  • Teradata

​
Database Connection DSN

The Data Source Name (DSN) defines how Query Exporter connects to your database. You can specify it as a string or as a configuration object.

​
String Format

databases:
  mydb:
    dsn: dialect[+driver]://[username:password][@host:port]/database[?option=value&...]
Important: When using the string format, username, password, and options must be URL-encoded.

​
Object Format

The object format handles URL encoding automatically: 
databases:
  mydb:
    dsn:
      dialect: postgresql
      user: myuser
      password: my+password  # No need to URL-encode
      host: dbserver
      port: 5432
      database: mydb
      options:
        sslmode: require

​
Database-Specific Configuration

​
PostgreSQL

Basic connection: 
databases:
  postgres_db:
    dsn: postgresql://username:password@localhost:5432/dbname
With SSL: 
databases:
  postgres_db:
    dsn: postgresql://username:password@localhost:5432/dbname?sslmode=require
Using environment variable: 
databases:
  postgres_db:
    dsn: !env PG_DATABASE_DSN

​
MySQL

Basic connection: 
databases:
  mysql_db:
    dsn: mysql://username:password@localhost:3306/dbname
With charset: 
databases:
  mysql_db:
    dsn: mysql://username:password@localhost:3306/dbname?charset=utf8mb4

​
Microsoft SQL Server

Basic connection: 
databases:
  mssql_db:
    dsn: mssql+pymssql://username:password@localhost:1433/dbname
With MARS (Multiple Active Result Sets): When defining multiple queries on the same connection with MSSQL, enable MARS for correct query result reporting: 
databases:
  mssql_db:
    dsn: mssql+pymssql://username:password@localhost:1433/dbname?MARS_Connection=yes
MARS must be enabled if you run multiple queries on a single MSSQL connection to ensure results are reported correctly.

​
Oracle

Basic connection with TNS-style DSN: 
databases:
  oracle_db:
    dsn: oracle+oracledb://username:password@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=myservice)))
Using environment variable: 
databases:
  oracle_db:
    dsn: !env ORACLE_DATABASE_DSN

​
SQLite

In-memory database: 
databases:
  sqlite_db:
    dsn: sqlite://
File-based database: 
databases:
  sqlite_db:
    dsn: sqlite:///path/to/database.db
Absolute path (4 slashes): 
databases:
  sqlite_db:
    dsn: sqlite:////absolute/path/to/database.db
With connection parameters: 
databases:
  sqlite_db:
    dsn: sqlite:///db.sqlite
    connect-sql:
      - PRAGMA application_id = 123
      - PRAGMA auto_vacuum = 1

​
IBM DB2

Basic connection: 
databases:
  db2_db:
    dsn: db2://username:password@hostname:50000/dbname
DB2 support is only available on x86_64 architecture in Docker images.

​
ClickHouse

Basic connection: 
databases:
  clickhouse_db:
    dsn: clickhouse+native://username:password@localhost:9000/default

​
Teradata

Basic connection: 
databases:
  teradata_db:
    dsn: teradatasql://username:password@hostname/database

​
Connection Pooling

Configure connection pooling to optimize database connections: 
databases:
  mydb:
    dsn: postgresql://user:pass@host/db
    connection-pool:
      size: 5           # Number of connections to maintain (default: 1)
      max-overflow: 10  # Additional connections allowed (default: 0)

​
Connection Initialization

Run SQL statements immediately after connecting: 
databases:
  mydb:
    dsn: sqlite:///db.sqlite
    connect-sql:
      - SET SESSION sql_mode = 'TRADITIONAL'
      - SET time_zone = '+00:00'

​
Database Labels

Tag metrics with database-specific labels: 
databases:
  db1:
    dsn: sqlite://
    labels:
      region: us-east
      environment: production
  db2:
    dsn: sqlite://
    labels:
      region: us-west
      environment: production
When using labels, all databases must define the same set of label keys.

​
Testing Your Connection

Use the --check-only flag to validate your configuration without running the exporter: 
query-exporter --config config.yaml --check-only
This will verify:
  • Configuration file syntax
  • Database DSN format
  • Connection credentials
  • SQL query syntax

​
Further Reading

Build docs developers (and LLMs) love

Get started for freeTalk to us