> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.

# PostgreSQL

> PostgreSQL connection and workload metrics.

The PostgreSQL integration requires CXDOT Collector 1.4.0 or greater.

[PostgreSQL](https://www.postgresql.org/) is an open source object-relational database
system. Use the PostgreSQL integration with the Chronosphere XDOT Collector to collect
connection and workload metrics from PostgreSQL servers running in your environment.

The PostgreSQL integration supports PostgreSQL 16 or greater.

## Supported telemetry types

The PostgreSQL integration supports these telemetry types:

| Type    | Supported |
| ------- | --------- |
| Logs    | No        |
| Metrics | Yes       |
| Traces  | No        |
| Events  | No        |

## Prerequisites

The PostgreSQL integration has the following prerequisites:

* Create a PostgreSQL role that can authenticate with a password and connect to the
  `postgres` database and every non-template database on each target.
* Grant the monitoring role `SELECT` access to `pg_stat_database`. To collect
  `ANALYZE` progress for operations run by other roles, also grant the monitoring
  role `pg_monitor`. This predefined role can read privileged server information,
  so grant it only when you need these progress metrics.
* Make each PostgreSQL endpoint reachable from the collector.

## Configure

To configure the PostgreSQL integration, follow these steps:

1. For discovered PostgreSQL targets, provide the endpoint and credentials through
   autodiscovery annotations.

   For more information, see
   [autodiscovery](https://docs.chronosphere.io/ingest/cxdot-collector/autodiscovery).

2. Optional: Configure static targets, and provide the password through your
   deployment's secret management. For example, the following Helm values reference
   the `POSTGRES_PASSWORD` environment variable:

   ```yaml theme={null}
   config:
     integrations:
       postgres:
         instances:
           - endpoint: postgres.example.com:5432
         username: cxdot
         password: "${env:POSTGRES_PASSWORD}"
   ```

### Validate

To validate the PostgreSQL integration, follow these steps:

1. In Live Telemetry Analyzer, filter for `cxdot.integration.name=postgres`. Confirm
   that the PostgreSQL metric names appear.

2. In Metrics Explorer, run the following query while clients are connected to the
   PostgreSQL servers:

   ```text theme={null}
   sum by ("server.address", "server.port") ({"postgresql.backends"})
   ```

   Confirm that the query returns the expected time series for each target.

For more information about diagnosing a failing integration, see
[Troubleshooting](https://docs.chronosphere.io/ingest/cxdot-collector/troubleshooting).

## Configuration reference

Configure one PostgreSQL integration instance with the following settings. In Helm values, place
these settings under `config.integrations.postgres`. In a Collector configuration file, place
them under `cxdot.integrations.postgres`.

### Optional settings

* **`enabled`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to enable this PostgreSQL integration instance. If true, the Collector collects
  PostgreSQL metrics. If false, the Collector doesn't run this integration instance.

* **`username`**
  Type: `string`. Optional. Default: `postgres`.
  PostgreSQL user for connections to every statically configured instance.

* **`password`**
  Type: `string`. Optional.
  PostgreSQL password for connections to every statically configured instance. The Collector
  requires it to start collecting from `instances` entries, and masks the value in diagnostic
  output, logs, and errors.

* **`collection_interval`**
  Type: `duration`. Optional. Default: `10s`.
  How often the integration collects metrics from each PostgreSQL instance.

* **`timeout`**
  Type: `duration`. Optional. Default: `10s`.
  Maximum time allowed to collect metrics from a PostgreSQL instance during one interval. A
  value of `0s` disables the timeout.

* **`instances`**
  Type: `array of object`. Optional.
  PostgreSQL instances to monitor. Each `endpoint` uses `host:port` format, such as
  `postgres.default.svc:5432`. When this list contains an instance, the integration monitors
  only the listed instances and disables discovery through annotations for this integration
  instance. When the list is empty, the integration monitors targets supplied through PostgreSQL
  annotations. Each discovered target uses the credentials and TLS settings in its annotation.

* **`instances[].endpoint`**
  Type: `string`. Required.
  Network address of the PostgreSQL instance in `host:port` format.

* **`tls`**
  Type: `object`. Optional.
  Transport Layer Security (TLS) settings for connections to statically configured instances. By
  default, the integration uses TLS and verifies the server certificate. Set
  `insecure_skip_verify` to `true` to use TLS without verifying the certificate. Set `insecure`
  to `true` to connect without TLS. Targets discovered through annotations use the TLS settings
  in their annotations instead.

* **`tls.insecure`**
  Type: `boolean`. Optional.
  In gRPC and HTTP when set to true, this is used to disable the client transport security. See
  [https://godoc.org/google.golang.org/grpc#WithInsecure](https://godoc.org/google.golang.org/grpc#WithInsecure)
  for gRPC. Please refer to
  [https://godoc.org/crypto/tls#Config](https://godoc.org/crypto/tls#Config) for more
  information. (optional, default false)

* **`tls.insecure_skip_verify`**
  Type: `boolean`. Optional.
  InsecureSkipVerify will enable TLS but not verify the certificate.


## Related topics

- [SQL DB Input source plugin](/ingest/pipeline/plugins/source-plugins/sqldb.md)
- [Datadog Logs destination plugin](/ingest/pipeline/plugins/destination-plugins/datadog.md)
- [Host](/ingest/xcor/integrations/collector/host.md)