Skip to main content
The databases section defines database connections. Each database is identified by a key name that you reference in queries.

​
Basic Configuration

databases:
  mydb:
    dsn: postgresql://user:password@localhost:5432/dbname

​
Configuration Options

​
dsn
string | object
required
Database connection details. Can be provided as a DSN string or as a structured object.See DSN Format below for details.
​
connection-pool
object
Configuration for the database connection pool.
​
connect-sql
array[string]
Optional list of SQL queries to run immediately after database connection. This can be used to set up connection-wise parameters and configurations.
connect-sql:
  - SET timezone = 'UTC'
  - SET statement_timeout = 30000
​
labels
object
Optional mapping of label names and values to tag metrics collected from each database. When labels are used, all databases must define the same set of labels.Label names must match the pattern ^[a-zA-Z_][a-zA-Z0-9_]*$.

​
DSN Format

The DSN (Data Source Name) defines how to connect to your database. It can be specified in two ways:

​
String Format

A connection URL string following the SQLAlchemy format: 
dialect[+driver]://[username:password][@host:port]/database[?option=value&...]
Examples: 
databases:
  postgres:
    dsn: postgresql://user:pass@localhost:5432/mydb
  
  mysql:
    dsn: mysql+pymysql://user:pass@localhost:3306/mydb
  
  mssql:
    dsn: mssql+pymssql://user:pass@localhost:1433/mydb
  
  oracle:
    dsn: oracle+oracledb://user:pass@localhost:1521/mydb
  
  sqlite:
    dsn: sqlite:///path/to/database.db
In the string form, username, password, and options need to be URL-encoded. Special characters like @, :, /, etc. must be percent-encoded.

​
Object Format

A structured object with separate fields: 
databases:
  mydb:
    dsn:
      dialect: postgresql+psycopg2
      user: myuser
      password: my@password  # No URL encoding needed
      host: localhost
      port: 5432
      database: mydb
      options:
        connect_timeout: 10
        application_name: query-exporter
​
dsn.dialect
string
required
The database dialect and optional driver in the format dialect[+driver].Examples: postgresql, postgresql+psycopg2, mysql+pymysql, sqlite
​
dsn.user
string
Database username.
​
dsn.password
string
Database password. Automatically URL-encoded when using object format.
​
dsn.host
string
Database host address.
​
dsn.port
integer
Database port number. Must be between 1 and 65535.
​
dsn.database
string
Database name.
​
dsn.options
object
Additional database-specific connection options as key-value pairs.
The object format automatically handles URL encoding, making it easier to use passwords and options with special characters.

​
Database Dialects

Query Exporter uses SQLAlchemy and supports multiple database engines:
  • PostgreSQL: postgresql:// or postgresql+psycopg2://
  • MySQL: mysql:// or mysql+pymysql://
  • SQLite: sqlite:// (in-memory) or sqlite:///path/to/db
  • Microsoft SQL Server: mssql+pymssql://
  • Oracle: oracle+oracledb://
  • IBM DB2: db2://
  • ClickHouse: clickhouse+native://
  • Teradata: teradatasql://
Additional Python packages may be required for specific database drivers. See the SQLAlchemy documentation for details.

​
Connection Pool

The connection pool manages database connections efficiently: 
databases:
  mydb:
    dsn: postgresql://user:pass@localhost/db
    connection-pool:
      size: 5
      max-overflow: 10
With this configuration:
  • Up to 5 connections are maintained open
  • Up to 10 additional temporary connections can be created during high load
  • Total maximum connections: 15
The default connection pool has size: 1 and max-overflow: 0, meaning only one connection is used.

​
Database Labels

Use labels to differentiate metrics from different database instances: 
databases:
  db-us-east:
    dsn: postgresql://user:[email protected]/db
    labels:
      region: us-east
      environment: production
  
  db-us-west:
    dsn: postgresql://user:[email protected]/db
    labels:
      region: us-west
      environment: production
When using labels, all databases must define the exact same set of label names. The values can differ, but the label keys must match across all databases.

​
Using Environment Variables

It’s common to store sensitive connection details in environment variables: 
databases:
  production:
    dsn: !env DATABASE_DSN
Or with the object format: 
databases:
  production:
    dsn:
      dialect: postgresql
      user: !env DB_USER
      password: !env DB_PASSWORD
      host: !env DB_HOST
      port: !env DB_PORT
      database: !env DB_NAME

​
Complete Example

databases:
  # Simple SQLite for testing
  local:
    dsn: sqlite://
  
  # PostgreSQL with connection pool
  postgres_prod:
    dsn: postgresql://user:[email protected]:5432/mydb
    connection-pool:
      size: 10
      max-overflow: 20
    connect-sql:
      - SET statement_timeout = 30000
      - SET lock_timeout = 10000
    labels:
      environment: production
      region: us-east-1
  
  # MySQL with environment variables
  mysql_prod:
    dsn: !env MYSQL_DSN
    connection-pool:
      size: 5
      max-overflow: 10
    labels:
      environment: production
      region: us-west-1
  
  # Oracle with object format
  oracle_prod:
    dsn:
      dialect: oracle+oracledb
      user: !env ORACLE_USER
      password: !env ORACLE_PASSWORD
      host: oracle.example.com
      port: 1521
      database: ORCL
      options:
        encoding: UTF-8
    labels:
      environment: production
      region: eu-west-1

Build docs developers (and LLMs) love

Get started for freeTalk to us