---
title: Install & configure NRDOT for PostgreSQL monitoring with Self-hosted
source: https://docs.newrelic.com/docs/opentelemetry/db360/postgresql/hosted
---

Set up PostgreSQL monitoring using the NRDOT Collector on self-hosted environments including physical servers, virtual machines, and standalone installations.

## Prerequisites [#prerequisites]

Before you install, make sure you have:

-   PostgreSQL 14 or later
-   A New Relic [license key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#ingest-license-key).
-   Administrative access to your PostgreSQL instance.
-   Network connectivity between the host where you install the NRDOT Collector and your PostgreSQL database.
-   Network connectivity to [New Relic OTLP endpoints documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/)

For supported PostgreSQL versions, required grants, and recommended server parameters, see [Compatibility and prerequisites](https://docs.newrelic.com/docs/opentelemetry/db360/postgresql/compatibility).

## Set up NRDOT Collector [#setup]

Install the NRDOT Collector on your system:

**For AMD64 architecture**

-   For Debian/Ubuntu system, run:

    ```bash
    NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_amd64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb
    ```
-   For RHEL/CentOS/OEL system, run:

    ```bash
    NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_x86_64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm
    ```

**For ARM64 architecture**

-   For Debian/Ubuntu system, run:

    ```bash
    NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_arm64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb
    ```

-   For RHEL/CentOS/OEL system, run:

    ```bash
    NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_aarch64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm
    ```

## Configure database user and grants [#database-user]

Create a monitoring user with the necessary privileges for your PostgreSQL instance.

**To create the monitoring user and grants:**

1.  Connect to your PostgreSQL instance as a superuser or another user with required permissions:

    ```shell
    sudo -u postgres psql --dbname=postgres --port=5432
    ```

2.  Create the monitoring user:

    ```sql
    CREATE USER <YOUR_DB_USERNAME> WITH LOGIN PASSWORD '<YOUR_DB_PASSWORD>';
    ```

3.  Grant the monitoring user role membership as needed:

-   If you're on PostgreSQL 15 and above, assign role to inherit privileges:

    ```sql
    ALTER ROLE <YOUR_DB_USERNAME> INHERIT;
    ```

    > #### 💡 TIP
    >
    > If you're on PostgreSQL 14, the monitoring user inherits privileges by default, so you can skip this step.

-   Create the following schema and grants in every database you want to monitor:

    ```sql
    CREATE SCHEMA IF NOT EXISTS otel;
    GRANT USAGE ON SCHEMA otel TO <YOUR_DB_USERNAME>;
    GRANT USAGE ON SCHEMA public TO <YOUR_DB_USERNAME>;
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO <YOUR_DB_USERNAME>;
    GRANT pg_monitor TO <YOUR_DB_USERNAME>;
    CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
    ```

-   (Optional) To collect vector metrics, create the `pgvector` extension in each database:

    ```sql
    CREATE EXTENSION IF NOT EXISTS vector;
    ```

    The `l1`, `hamming`, and `jaccard` distance functions require `pgvector` version `0.7.0` or above.

-   (Optional) To verify the connection and grants, run:

    ```shell
    psql --username=<YOUR_DB_USERNAME> --host=localhost --port=5432 --dbname=<YOUR_DATABASE_NAME> --command '\conninfo'
    psql --username=<YOUR_DB_USERNAME> --host=localhost --port=5432 --dbname=<YOUR_DATABASE_NAME> \
      -c "SELECT * FROM pg_stat_database LIMIT 1;" && echo "pg_stat_database OK"
    psql --username=<YOUR_DB_USERNAME> --host=localhost --port=5432 --dbname=<YOUR_DATABASE_NAME> \
      -c "SELECT * FROM pg_stat_activity LIMIT 1;" && echo "pg_stat_activity OK"
    psql --username=<YOUR_DB_USERNAME> --host=localhost --port=5432 --dbname=<YOUR_DATABASE_NAME> \
      -c "SELECT * FROM pg_stat_statements LIMIT 1;" && echo "pg_stat_statements OK"
    ```

    If each command completes without an error, the monitoring user, host, and port are all correct.

## Configure NRDOT Collector [#configure-collector]

Configure the NRDOT Collector with your PostgreSQL-specific settings.

This configuration focuses on essential PostgreSQL monitoring with the `nrpostgresql` receiver only.

> #### 💡 FULL CONFIGURATION
>
> This baseline configuration captures essential metrics. To see the complete metric catalog, refer to the [configuration reference](https://docs.newrelic.com/docs/opentelemetry/db360/postgresql/config-reference/#hosted-full).

1.  Create a configuration file named as `postgresql-config.yaml`:

    ```bash
      sudo nano /etc/nrdot-collector/postgresql-config.yaml
    ```

2.  Add the following configuration to the `postgresql-config.yaml` file you created in the previous step.

### Configuration parameters

The following table describes the key configuration parameters for the `nrpostgresql` receiver:

| Parameter                       | Description                                                                                                                                                                                                      |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<YOUR_DB_HOST>`                | Enter your PostgreSQL Database hostname.                                                                                                                                                                         |
| `<YOUR_DB_PORT>`                | Enter your PostgreSQL Database port.                                                                                                                                                                             |
| `<YOUR_DB_USERNAME>`            | Enter your database username.                                                                                                                                                                                    |
| `<YOUR_DB_PASSWORD>`            | Enter your database password.                                                                                                                                                                                    |
| `<YOUR_DATABASE_NAME>`          | Enter the name of the database you want to monitor.                                                                                                                                                              |
| `databases`                     | List of databases to collect statistics for. Default: `[]` (all non-template databases). Applies to metrics only. Query samples and top queries ignore this list and are filtered solely by `exclude_databases`. |
| `exclude_databases`             | Databases excluded from statistics, query samples, and top queries. Default: `[]`. Use this for internal databases that your monitoring user can't reach.                                                        |
| `<YOUR_NEWRELIC_OTLP_ENDPOINT>` | Enter the New Relic OTLP endpoint. For more information, see [New Relic OTLP endpoints](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/).                                        |
| `<YOUR_NEWRELIC_LICENSE_KEY>`   | Enter your New Relic [license key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#ingest-license-key).                                                                                       |
| `collection_interval`           | Enter the interval between metric scrapes. Default: `15s`.                                                                                                                                                       |

> #### 💡 TIP
>
> You can also:
>
> -   [Configure multiple receivers](https://docs.newrelic.com/docs/opentelemetry/db360/postgresql/multi-receiver): To monitor multiple PostgreSQL instances from one collector.
> -   [Link your PostgreSQL database with APM](https://docs.newrelic.com/docs/opentelemetry/db360/capabilities/db-apm): To correlate your application performance with database operations. This allows you to see exactly which applications are generating specific database workloads.
> -   [Query plans for write statements](https://docs.newrelic.com/docs/opentelemetry/db360/postgresql/optional#query): To collect query plans for locking or write statements without granting write access to the monitoring user.
> -   [Set up secret management](https://docs.newrelic.com/docs/opentelemetry/db360/capabilities/db-apm/#secret-management): To securely manage sensitive information, such as database credentials. This helps to enhance the security of your monitoring setup by avoiding hardcoding sensitive data in configuration files.

## Validate NRDOT Collector configuration [#validate]

1.  Update the config path to point to your new `postgresql-config.yaml` file:

    ```bash
      sudo sed -i 's|OTELCOL_OPTIONS="--config=/etc/nrdot-collector/config.yaml"|OTELCOL_OPTIONS="--config=/etc/nrdot-collector/postgresql-config.yaml"|' /etc/nrdot-collector/nrdot-collector.conf
    ```

2.  Validate the NRDOT Collector configuration to ensure it's correctly formatted and will work properly:

    ```bash
      sudo /usr/bin/nrdot-collector validate --config=/etc/nrdot-collector/postgresql-config.yaml
    ```

## Restart NRDOT Collector [#restart-collector]

After configuring the collector, restart the NRDOT Collector service to apply the changes:

```bash
sudo systemctl restart nrdot-collector
```

To verify that the collector is running properly, check the service status:

```bash
sudo systemctl status nrdot-collector
```

> #### 💡 TIP
>
> Always restart the NRDOT Collector after making configuration changes to ensure the new settings take effect.

## Find and use your data [#find-use-data]

Query samples and top queries arrive as log events (`event.name = 'db.server.query_sample'` / `'db.server.top_query'`, `db.system.name = 'postgresql'`). Metrics arrive under the `postgresql.*` namespace.

To find your PostgreSQL database entity in New Relic:

1.  Go to **<https://one.newrelic.com> > All Capabilities > Databases**.
2.  From the **Entity type** dropdown, select **PostgreSQL instance**, then click **Apply**.
3.  Select your PostgreSQL database from the list of entities.

## Related documentation [#related]

[Link your PostgreSQL database with APM](https://docs.newrelic.com/docs/opentelemetry/db360/capabilities/db-apm)

Learn how to correlate your application performance with database operations.

[Troubleshooting guide](https://docs.newrelic.com/docs/opentelemetry/db360/postgresql/troubleshooting)

Learn how to troubleshoot common issues with PostgreSQL monitoring.

[Metrics reference](https://docs.newrelic.com/docs/opentelemetry/db360/postgresql/metrics-reference)

Learn about the available metrics collected by the NRDOT Collector.