Skip to main content
The databases section defines database connections that queries can execute against. Each database is configured with a unique name as the key.

​
Database Structure

​
databases
object
required
Dictionary of database configurations, keyed by database name
databases:
  db1:
    dsn: postgresql://user:pass@localhost/mydb
  db2:
    dsn:
      dialect: mysql
      host: db.example.com
      database: mydb

​
Database Fields

​
dsn
string | object
required
Database connection string or structured DSN configuration.Can be specified as:
  • A connection string (e.g., postgresql://user:pass@host:5432/database)
  • A structured DSNDetails object (see below)
  • An environment variable reference using !env (e.g., !env DATABASE_DSN)
The DSN is validated using SQLAlchemy’s URL parser to ensure it’s properly formatted.
# Simple string format
dsn: postgresql://user:password@localhost:5432/mydb

# Environment variable
dsn: !env DATABASE_DSN

​
DSNDetails Structure

When using the structured format, the following fields are available:
​
dialect
string
required
The database dialect/driver (e.g., postgresql, mysql, sqlite, oracle)
dsn:
  dialect: postgresql
​
user
string
Database username for authentication
dsn:
  dialect: postgresql
  user: myuser
​
password
string
Database password for authentication
dsn:
  dialect: postgresql
  user: myuser
  password: mypassword
​
host
string
Database server hostname or IP address
dsn:
  dialect: postgresql
  host: db.example.com
​
port
integer
Database server port numberConstraints:
  • Must be between 1 and 65535 (inclusive)
dsn:
  dialect: postgresql
  host: db.example.com
  port: 5432
​
database
string
Database name to connect to
dsn:
  dialect: postgresql
  database: mydb
​
options
object
default:"{}"
Additional connection options passed as query parameters to the database driver. Values can be strings or lists of strings.
dsn:
  dialect: postgresql
  database: mydb
  options:
    sslmode: require
    connect_timeout: "10"

​
Connection Pool Configuration

​
connection-pool
object
default:"{size: 1, max_overflow: 0}"
Connection pool configuration for the database.If not specified, defaults to a pool size of 1 with no overflow.
databases:
  mydb:
    dsn: postgresql://localhost/mydb
    connection-pool:
      size: 5
      max-overflow: 10
​
connection-pool.size
integer
default:"1"
The size of the connection pool to maintain.Constraints:
  • Must be between 1 and 100 (inclusive)
Default: 1
connection-pool:
  size: 5
​
connection-pool.max-overflow
integer
default:"0"
The maximum number of connections that can be created beyond the pool size.When the pool is exhausted, this many additional connections can be created. Once these additional connections are returned to the pool, they are closed.Constraints:
  • Must be between 0 and 100 (inclusive)
Default: 0
connection-pool:
  size: 5
  max-overflow: 10

​
Additional Fields

​
connect-sql
array
List of SQL statements to execute when a database connection is established.Useful for setting session-level configuration or temporary tables.Constraints:
  • If specified, must contain at least 1 statement
databases:
  mydb:
    dsn: postgresql://localhost/mydb
    connect-sql:
      - SET application_name TO 'query_exporter'
      - SET statement_timeout TO 30000
​
labels
object
Static labels to attach to all metrics from queries running on this database.Label names must match the pattern ^[a-zA-Z_][a-zA-Z0-9_]*$ (start with letter or underscore, followed by letters, numbers, or underscores).Constraints:
  • If specified, must contain at least 1 label
databases:
  mydb:
    dsn: postgresql://localhost/mydb
    labels:
      environment: production
      region: us-west-2

​
Complete Example

databases:
  # Simple configuration
  simple_db:
    dsn: postgresql://user:pass@localhost/mydb

  # Structured DSN with connection pool
  main_db:
    dsn:
      dialect: postgresql
      user: app_user
      password: secret
      host: db.example.com
      port: 5432
      database: production
      options:
        sslmode: require
    connection-pool:
      size: 10
      max-overflow: 20
    connect-sql:
      - SET application_name TO 'query_exporter'
    labels:
      environment: production
      cluster: main

  # Environment variable DSN
  env_db:
    dsn: !env DATABASE_DSN
    labels:
      source: external

​
Validation Rules

  • The DSN is validated using SQLAlchemy’s URL parser
  • Invalid DSN formats will raise a ValueError: Invalid DSN format
  • Port must be in the valid range 1-65535
  • Connection pool size must be between 1-100
  • Connection pool max-overflow must be between 0-100
  • Label names must follow Prometheus naming conventions
  • If connect-sql is specified, it must contain at least one statement
  • If labels is specified, it must contain at least one label

Build docs developers (and LLMs) love

Get started for freeTalk to us