---
title: "prometheus.exporter.postgres | Grafana Alloy documentation"
description: "Learn about prometheus.exporter.postgres"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# `prometheus.exporter.postgres`

The `prometheus.exporter.postgres` component embeds the [`postgres_exporter`](https://github.com/prometheus-community/postgres_exporter) to collect metrics from a PostgreSQL database.

You can specify multiple `prometheus.exporter.postgres` components by giving them different labels.

## Usage

Alloy ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.exporter.postgres "<LABEL>" {
  data_source_names = ["<DATA_SOURCE_NAME>"]
}
```

## Arguments

You can use the following arguments with `prometheus.exporter.postgres`:

Expand table

| Name                         | Type           | Description                                                                   | Default | Required |
|------------------------------|----------------|-------------------------------------------------------------------------------|---------|----------|
| `data_source_names`          | `list(secret)` | Specifies the PostgreSQL servers to connect to.                               |         | yes      |
| `custom_queries_config_path` | `string`       | Path to YAML file containing custom queries to expose as metrics.             | `""`    | no       |
| `disable_default_metrics`    | `bool`         | When `true`, only exposes metrics supplied from `custom_queries_config_path`. | `false` | no       |
| `disable_settings_metrics`   | `bool`         | Disables collection of metrics from `pg_settings`.                            | `false` | no       |
| `enabled_collectors`         | `list(string)` | List of collectors to enable. Refer to the information below for more detail. | `[]`    | no       |

Refer to the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) for more information about the format of the connection strings in `data_source_names`.

Refer to the examples for the `custom_queries_config_path` file in the [`postgres_exporter` repository](https://github.com/prometheus-community/postgres_exporter/blob/master/queries.yaml).

> Note
> 
> Avoid configuring the exporter with environment variables. They affect *all* `prometheus.exporter.postgres` components, not just one. Refer to the [`postgres_exporter` repository](https://github.com/prometheus-community/postgres_exporter#environment-variables) for a full list of environment variables.

The `prometheus.exporter.postgres` component configures the embedded [`postgres_exporter`](https://github.com/prometheus-community/postgres_exporter) to run with a collection timeout of 10 seconds.

By default, the component enables the same set of metrics as the upstream [`postgres_exporter`](https://github.com/prometheus-community/postgres_exporter). Set `custom_queries_config_path` to expose additional metrics from a configuration file.

Set `disable_default_metrics` to `true` to expose only the metrics from `custom_queries_config_path`. That makes `custom_queries_config_path` required, and you can’t set `enabled_collectors`.

Set `enabled_collectors` to control a subset of the metrics collectors. The following collectors are available for selection:

- `buffercache_summary`
- `database`
- `database_wraparound`
- `locks`
- `long_running_transactions`
- `postmaster`
- `process_idle`
- `replication`
- `replication_slot`
- `roles`
- `stat_activity_autovacuum`
- `stat_bgwriter`
- `stat_checkpointer` - Only supported in PostgreSQL 17 and later
- `stat_database`
- `stat_progress_vacuum`
- `stat_statements`
- `stat_user_tables`
- `stat_wal_receiver`
- `statio_user_indexes`
- `statio_user_tables`
- `wal`
- `xlog_location`

The component enables the following collectors by default:

- `database`
- `locks`
- `replication`
- `replication_slot`
- `roles`
- `stat_bgwriter`
- `stat_database`
- `stat_progress_vacuum`
- `stat_user_tables`
- `statio_user_tables`
- `wal`

> Note
> 
> Due to a limitation of the upstream exporter, `enabled_collectors` applies only to the first data source when you configure multiple `data_source_names`.

The component sets the `instance` label on its exported targets to a simplified form of the data source name, `postgresql://<HOST>:<PORT>/<DATABASE>`, with any credentials removed. The component omits the port when the data source name specifies a host without a port. When the data source name omits the host, the component uses `localhost:5432`. When you configure more than one data source name, the component sets the `instance` label to the component ID.

## Blocks

You can use the following blocks with `prometheus.exporter.postgres`:

No valid configuration blocks found.

### `autodiscovery`

The `autodiscovery` block configures discovery of databases, outside of any specified in `data_source_names`.

You can use the following arguments with the `autodiscovery` block:

Expand table

| Name                 | Type           | Description                                        | Default | Required |
|----------------------|----------------|----------------------------------------------------|---------|----------|
| `database_allowlist` | `list(string)` | Scrape only these databases.                       |         | no       |
| `database_denylist`  | `list(string)` | Scrape all databases except these.                 |         | no       |
| `enabled`            | `bool`         | Whether to automatically discover other databases. | `false` | no       |

If you set `enabled` to `true` without an allowlist or a denylist, the exporter scrapes all databases.

If you don’t enable `autodiscovery`, neither `database_allowlist` nor `database_denylist` has any effect.

### `stat_statements`

The `stat_statements` block configures the selection of both the query ID and the full SQL statement. This configuration takes effect only when you enable the `stat_statements` collector.

You can use the following arguments with the `stat_statements` block:

Expand table

| Name                | Type           | Description                                         | Default | Required |
|---------------------|----------------|-----------------------------------------------------|---------|----------|
| `exclude_databases` | `list(string)` | Comma-separated list of database names to exclude.  | `[]`    | no       |
| `exclude_users`     | `list(string)` | Comma-separated list of user names to exclude.      | `[]`    | no       |
| `include_query`     | `bool`         | Enable the selection of query ID and SQL statement. | `false` | no       |
| `limit`             | `number`       | Maximum number of statements to fetch.              | `100`   | no       |
| `query_length`      | `number`       | Maximum length of the statement query text.         | `120`   | no       |

## Exported fields

The following fields are exported and can be referenced by other components.

Expand table

| Name      | Type                | Description                                               |
|-----------|---------------------|-----------------------------------------------------------|
| `targets` | `list(map(string))` | The targets that can be used to collect exporter metrics. |

For example, the `targets` can either be passed to a `discovery.relabel` component to rewrite the targets’ label sets or to a `prometheus.scrape` component that collects the exposed metrics.

The exported targets use the configured [in-memory traffic](https://grafana.com/docs/alloy/next/get-started/component_controller/#in-memory-traffic) address specified by the [run command](https://grafana.com/docs/alloy/next/reference/cli/run/).

## Component health

`prometheus.exporter.postgres` is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

## Debug information

`prometheus.exporter.postgres` doesn’t expose any component-specific debug information.

## Debug metrics

`prometheus.exporter.postgres` doesn’t expose any component-specific debug metrics.

## Examples

### Collect metrics from a PostgreSQL server

The following example uses a `prometheus.exporter.postgres` component to collect metrics from a PostgreSQL server running locally with all default settings:

Alloy ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
// Because no autodiscovery is defined, this will only scrape the <DATABASE_NAME> database, as defined
// in the DSN below.
prometheus.exporter.postgres "example" {
  data_source_names = ["postgresql://<DB_USERNAME>:<DB_PASSWORD>@localhost:5432/<DATABASE_NAME>?sslmode=disable"]
}

prometheus.scrape "default" {
  targets    = prometheus.exporter.postgres.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}
```

Replace the following:

- *`<DB_USERNAME>`* : The username for the PostgreSQL server.
- *`<DB_PASSWORD>`* : The password for the PostgreSQL server.
- *`<DATABASE_NAME>`* : The name of the database to scrape.
- *`<PROMETHEUS_REMOTE_WRITE_URL>`* : The URL of the Prometheus `remote_write` compatible server to send metrics to.
- *`<USERNAME>`* : The username to use for authentication to the `remote_write` API.
- *`<PASSWORD>`* : The password to use for authentication to the `remote_write` API.

### Collect custom metrics from an allowlisted set of databases

The following example uses a `prometheus.exporter.postgres` component to collect custom metrics from a set of specific databases, replacing default metrics with custom metrics derived from queries in `/etc/alloy/custom-postgres-metrics.yaml`:

Alloy ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.exporter.postgres "example" {
  data_source_names = ["postgresql://<DB_USERNAME>:<DB_PASSWORD>@localhost:5432/<DATABASE_NAME>?sslmode=disable"]

  // This block configures autodiscovery to check for databases outside of the <DATABASE_NAME> db
  // specified in the DSN above. The database_allowlist field limits autodiscovery to the
  // 'frontend_app' and 'backend_app' databases. The component also scrapes <DATABASE_NAME>.
  autodiscovery {
    enabled            = true
    database_allowlist = ["frontend_app", "backend_app"]
  }

  disable_default_metrics    = true
  custom_queries_config_path = "/etc/alloy/custom-postgres-metrics.yaml"
}

prometheus.scrape "default" {
  targets    = prometheus.exporter.postgres.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}
```

Replace the following:

- *`<DB_USERNAME>`* : The username for the PostgreSQL server.
- *`<DB_PASSWORD>`* : The password for the PostgreSQL server.
- *`<DATABASE_NAME>`* : The name of the database to scrape.
- *`<PROMETHEUS_REMOTE_WRITE_URL>`* : The URL of the Prometheus `remote_write` compatible server to send metrics to.
- *`<USERNAME>`* : The username to use for authentication to the `remote_write` API.
- *`<PASSWORD>`* : The password to use for authentication to the `remote_write` API.

### Collect metrics from all databases except for a denylisted database

This example uses a `prometheus.exporter.postgres` component to collect custom metrics from all databases except for the `secrets` database.

Alloy ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.exporter.postgres "example" {
  data_source_names = ["postgresql://<DB_USERNAME>:<DB_PASSWORD>@localhost:5432/<DATABASE_NAME>?sslmode=disable"]

  // The database_denylist field will filter out those databases from the list of databases to scrape,
  // meaning that all databases *except* these will be scraped.
  //
  // In this example it will scrape all databases except for the one named 'secrets'.
  autodiscovery {
    enabled           = true
    database_denylist = ["secrets"]
  }
}

prometheus.scrape "default" {
  targets    = prometheus.exporter.postgres.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}
```

Replace the following:

- *`<DB_USERNAME>`* : The username for the PostgreSQL server.
- *`<DB_PASSWORD>`* : The password for the PostgreSQL server.
- *`<DATABASE_NAME>`* : The name of the database to scrape.
- *`<PROMETHEUS_REMOTE_WRITE_URL>`* : The URL of the Prometheus `remote_write` compatible server to send metrics to.
- *`<USERNAME>`* : The username to use for authentication to the `remote_write` API.
- *`<PASSWORD>`* : The password to use for authentication to the `remote_write` API.

### Escape special characters in a connection string

If your password contains special characters such as `@`, `:`, or `/`, wrap it with `encoding.url_encode`.

Alloy ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.exporter.postgres "example" {
  data_source_names = [
    "postgresql://<DB_USERNAME>:" + encoding.url_encode("p@ss/w:ord!") + "@localhost:5432/<DATABASE_NAME>?sslmode=disable",
  ]
}
```

This keeps the connection string valid.

Replace the following:

- *`<DB_USERNAME>`* : The username for the PostgreSQL server.
- *`<DATABASE_NAME>`* : The name of the database to scrape.

## Compatible components

`prometheus.exporter.postgres` has exports that can be consumed by the following components:

- Components that consume [Targets](https://grafana.com/docs/alloy/next/reference/compatibility/#targets-consumers)

> Note
> 
> Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.