> For the complete documentation index, see [llms.txt](https://docs.datasentinel.io/manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datasentinel.io/manual/guides/readme/onboard-your-first-cluster.md).

# Onboard Your First PostgreSQL Cluster

<div data-with-frame="true"><figure><img src="/files/itJMOugpvqRWr9Zvdzsx" alt="Onboard your first PostgreSQL cluster"><figcaption></figcaption></figure></div>

This guide walks you from a freshly installed Datasentinel platform to your **first monitored PostgreSQL cluster**, end to end. By the end you will have:

1. The required PostgreSQL extension installed (and the optional ones you want).
2. A dedicated read-only **monitoring user**.
3. Network access opened from Datasentinel to your instance.
4. The instance **registered** in Datasentinel, either through a local agent or agentlessly.
5. A clean **tagging scheme** that will scale to dozens of clusters.

{% hint style="info" %}
You only need to do this once per cluster. Tagging it well from day one pays off later for filtering dashboards, [**consolidating workloads**](/manual/features/tips-and-hints/consolidated-view.md), and scoping [**role-based access**](/manual/guides/readme/manage-users-and-role-based-access.md).
{% endhint %}

## Prerequisites

Before you begin, make sure you have:

<table><thead><tr><th width="220">Requirement</th><th>Detail</th></tr></thead><tbody><tr><td><strong>PostgreSQL version</strong></td><td>10 or later (older versions require a superuser monitoring account).</td></tr><tr><td><strong>Superuser access</strong></td><td>Needed only for the one-time setup (install extension, create user, edit <code>postgresql.conf</code> / <code>pg_hba.conf</code>).</td></tr><tr><td><strong>Network path</strong></td><td>The Datasentinel platform (agentless) or a local Datasentinel agent must reach the PostgreSQL port.</td></tr><tr><td><strong>Datasentinel platform</strong></td><td>Installed and reachable. See <a href="/spaces/lcWi6G1jtNuyGT9C0pkc/pages/NWHE4JQgbY6GLYsMK4qx"><strong>Installation › Platform</strong></a>.</td></tr></tbody></table>

***

## Step 1: Install the required extension

Datasentinel depends on [**pg\_stat\_statements**](/manual/getting-started/postgresql-clusters/extensions/pg_stat_statements.md) to collect per-query execution statistics. This is the **only mandatory** extension. Three more are optional and unlock additional features.

{% stepper %}
{% step %}

### Preload the extension

Edit `postgresql.conf` and add `pg_stat_statements` to `shared_preload_libraries`, plus the recommended settings:

```apache
shared_preload_libraries = 'pg_stat_statements'

# Track all statements
pg_stat_statements.track = all

# Optional, not necessary for Datasentinel to save pg_stat_statements
pg_stat_statements.save = false

# Reduce the default 5000 to e.g. 2000. Datasentinel collects metrics at regular intervals
pg_stat_statements.max = 2000

# Since PostgreSQL 14
compute_query_id = on

# Log I/O timing
track_io_timing = on
```

A PostgreSQL **restart** is required for `shared_preload_libraries` to take effect.
{% endstep %}

{% step %}

### Create the extension

Connect to the internal `postgres` database as superuser and run:

```sql
CREATE EXTENSION pg_stat_statements;
```

Verify it is loaded:

```sql
SELECT current_database(), extname
FROM pg_extension
WHERE extname = 'pg_stat_statements';
```

{% endstep %}

{% step %}

### Install the optional extensions

These add capabilities that you will likely want later. Install them now to avoid a second maintenance window.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>pg_store_plans</strong></td><td>Captures and exposes <a href="/spaces/lcWi6G1jtNuyGT9C0pkc/pages/hvLaUKkzQChHIPmEqR7K"><strong>execution plans</strong></a> for every tracked query.</td><td><a href="/spaces/lcWi6G1jtNuyGT9C0pkc/pages/i5gbmUwG8l9T0udkODbo">/spaces/lcWi6G1jtNuyGT9C0pkc/pages/i5gbmUwG8l9T0udkODbo</a></td></tr><tr><td><strong>system_stats</strong></td><td>Reports CPU, memory and disk metrics from the database host (useful when the agentless model can't reach the OS).</td><td><a href="/spaces/lcWi6G1jtNuyGT9C0pkc/pages/ucW3vLylxbehbTpefoYg">/spaces/lcWi6G1jtNuyGT9C0pkc/pages/ucW3vLylxbehbTpefoYg</a></td></tr><tr><td><strong>pg_buffercache</strong></td><td>Required by <a href="/spaces/lcWi6G1jtNuyGT9C0pkc/pages/6m2QWxqCtnDKY67DLi9v"><strong>Live360</strong></a> to surface the Disk &#x26; Cache Usage view.</td><td><a href="/spaces/lcWi6G1jtNuyGT9C0pkc/pages/bA1oQY0HMBohHS46KOsk">/spaces/lcWi6G1jtNuyGT9C0pkc/pages/bA1oQY0HMBohHS46KOsk</a></td></tr></tbody></table>
{% endstep %}
{% endstepper %}

***

## Step 2: Create the monitoring user

Datasentinel uses a dedicated, **read-only** PostgreSQL user. It never writes data. Access is restricted to the system catalogs needed to retrieve metrics.

{% tabs %}
{% tab title="PostgreSQL >= 10" %}

```sql
CREATE USER datasentinel PASSWORD 'myPassword';
GRANT pg_monitor, pg_read_all_settings, pg_read_all_stats TO datasentinel;
```

If you want to **terminate sessions** from the Datasentinel UI (Live360), also grant:

```sql
GRANT pg_signal_backend TO datasentinel;
```

{% endtab %}

{% tab title="PostgreSQL < 10" %}
The user must have the `SUPERUSER` role on older versions, which is the only way to read the required statistics.

```sql
CREATE USER datasentinel PASSWORD 'myPassword';
ALTER USER datasentinel WITH SUPERUSER;
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The default PostgreSQL `search_path` is `"$user", public`. If you have changed it at the instance level, make sure the `datasentinel` user can still see the `public` schema:

```sql
ALTER USER datasentinel SET search_path TO "$user", public;
```

{% endhint %}

***

## Step 3: Open the network path

Edit `pg_hba.conf` so the monitoring user can authenticate from the Datasentinel platform (agentless) or the host running the local agent:

```
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             datasentinel    <datasentinel_ip>/32    md5
```

{% hint style="info" %}
The user must be able to connect to **all** databases on the instance. That is how Datasentinel discovers per-database activity.
{% endhint %}

Reload the configuration:

```sql
SELECT pg_reload_conf();
```

***

## Step 4: Register the instance

You have two ways to connect Datasentinel to your cluster. They are functionally equivalent: pick the one that fits your environment. Unsure? See the [**Architecture comparison**](/manual/getting-started/architecture.md).

{% tabs %}
{% tab title="Agent-based" %}
Install a local Datasentinel **agent** on (or near) the PostgreSQL host. The agent connects to the database, collects metrics, and pushes them to the platform.

1. Install the agent. See [**Installation › Agent**](/manual/getting-started/installation/agent.md).
2. Describe the connection in a JSON file:

   ```bash
   cat > myInstance.json <<EOF
   {
     "host": "host_name",
     "port": 5432,
     "user": "datasentinel",
     "password": "myPassword",
     "tags": "application=sales,environment=production,datacenter=eu-west"
   }
   EOF
   ```
3. Register it through the [**Agent CLI**](/manual/implementation/agent-usage/cli.md):

   ```bash
   datasentinel add connection sales-prod -f myInstance.json
   ```

{% hint style="info" %}
An example script `connection_example.sh` is shipped in the `datasentinel` subdirectory.
{% endhint %}
{% endtab %}

{% tab title="Agentless" %}
With the agentless model, the Datasentinel platform connects **directly** to the PostgreSQL instance, with no software to install on the database host. See [**Agentless monitoring**](/manual/features/other-features/agentless-monitoring.md).

You can declare the connection from the UI or via the [**Platform API**](/manual/guides/readme/automate-with-the-api.md):

```bash
curl -sk \
  --header "user-token: $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -X POST https://$DATASENTINEL_HOST/ds-api/pool/pg-instances/sales-prod \
  -d '{
        "host": "51.158.70.115",
        "port": 5432,
        "user": "datasentinel",
        "password": "myPassword",
        "tags": "application=sales,environment=production,datacenter=eu-west"
      }'
```

{% hint style="info" %}
Need an SSL connection? Drop the certificates in `/datasentinel/ssl/` on the platform, prefix the connection name with `ssl_`, and follow the naming convention described in [**Monitoring User › SSL connection**](/manual/getting-started/postgresql-clusters/monitoring-user.md).
{% endhint %}
{% endtab %}
{% endtabs %}

Within a minute of registration, the instance shows up on the Datasentinel **Home** dashboard and the first metrics begin to flow.

***

## Step 5: Tag for the long run

The `tags` field you set in Step 4 is more than a label: it is the **single source of truth** for filtering dashboards, [**consolidating workloads**](/manual/features/tips-and-hints/consolidated-view.md) across primaries and replicas, and scoping [**role-based access**](/manual/guides/readme/manage-users-and-role-based-access.md). Pick a strategy on day one and apply it consistently.

A pragmatic baseline that scales:

<table><thead><tr><th width="180">Tag key</th><th>Example values</th><th>Why</th></tr></thead><tbody><tr><td><strong>application</strong></td><td><code>sales</code>, <code>inventory</code>, <code>billing</code></td><td>Group instances by the product or service they serve. Drives most dashboards and RBAC.</td></tr><tr><td><strong>environment</strong></td><td><code>production</code>, <code>staging</code>, <code>development</code></td><td>Separate critical workloads, restrict developer access to non-prod, drive alert severity.</td></tr><tr><td><strong>cluster</strong></td><td><code>orders</code>, <code>analytics</code></td><td>Required to <a href="/pages/f0m9FJY4KZgtCtJYermh"><strong>consolidate the workload across HA primaries and replicas</strong></a>.</td></tr><tr><td><strong>datacenter</strong></td><td><code>eu-west</code>, <code>us-east</code>, <code>on-prem-fr</code></td><td>Geo or provider context for incident triage.</td></tr><tr><td><strong>owner</strong></td><td><code>team-payments</code></td><td>So the responsible team is one click away from any dashboard.</td></tr></tbody></table>

{% hint style="info" %}
Datasentinel adds a set of [**automatic tags**](/manual/features/tips-and-hints/tags.md) (server, PostgreSQL version, database, wait events…). Your custom tags complement them. Keep keys short, lowercase and consistent.
{% endhint %}

***

## Step 6: Verify and explore

Open Datasentinel and confirm the new instance is collecting data:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Home</strong></td><td>Your cluster should appear in the global list with its tags applied as filters.</td><td><a href="/spaces/lcWi6G1jtNuyGT9C0pkc/pages/YMhzhoCU4kIcBRXXmohx">/spaces/lcWi6G1jtNuyGT9C0pkc/pages/YMhzhoCU4kIcBRXXmohx</a></td></tr><tr><td><strong>Session History</strong></td><td>Within a minute, the Active Session History chart starts populating: confirmation that the agent or platform is sampling.</td><td><a href="/spaces/lcWi6G1jtNuyGT9C0pkc/pages/yUGnw5CyiREJgqkA9ALe">/spaces/lcWi6G1jtNuyGT9C0pkc/pages/yUGnw5CyiREJgqkA9ALe</a></td></tr><tr><td><strong>Top Queries</strong></td><td>After a few minutes of activity, per-query stats from <code>pg_stat_statements</code> appear here.</td><td><a href="/spaces/lcWi6G1jtNuyGT9C0pkc/pages/0z3m1C0QshZ1dCVZ6tw7">/spaces/lcWi6G1jtNuyGT9C0pkc/pages/0z3m1C0QshZ1dCVZ6tw7</a></td></tr><tr><td><strong>Live360</strong></td><td>Open it to confirm your monitoring user has the right grants (Disk &#x26; Cache requires <code>pg_buffercache</code>).</td><td><a href="/spaces/lcWi6G1jtNuyGT9C0pkc/pages/6m2QWxqCtnDKY67DLi9v">/spaces/lcWi6G1jtNuyGT9C0pkc/pages/6m2QWxqCtnDKY67DLi9v</a></td></tr></tbody></table>

***

## Where to go next

Now that your first cluster is monitored, build on it:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-users" style="color:$primary;">:users:</i></h4></td><td><strong>Manage Users and Role-Based Access</strong>: give the right people access to the right instances, based on the tags you just set.</td><td><a href="/pages/M5MUBWa2Y2eRROXypHwm">/pages/M5MUBWa2Y2eRROXypHwm</a></td></tr><tr><td><h4><i class="fa-layer-plus" style="color:$primary;">:layer-plus:</i></h4></td><td><strong>Monitor High-Availability Clusters</strong>: add the primary and its replicas, then consolidate the workload at the cluster level.</td><td><a href="/pages/f0m9FJY4KZgtCtJYermh">/pages/f0m9FJY4KZgtCtJYermh</a></td></tr><tr><td><h4><i class="fa-cloud" style="color:$primary;">:cloud:</i></h4></td><td><strong>Monitor Cloud-Managed Instances</strong>: onboard RDS, Azure, Cloud SQL and other managed services agentlessly.</td><td><a href="/pages/aGpRhzYSyd7klXa01uYC">/pages/aGpRhzYSyd7klXa01uYC</a></td></tr><tr><td><h4><i class="fa-code" style="color:$primary;">:code:</i></h4></td><td><strong>Automate with the API</strong>: register the next clusters, users and roles from a script instead of the UI.</td><td><a href="/pages/lk2kg8QxwAUbloVoBKDz">/pages/lk2kg8QxwAUbloVoBKDz</a></td></tr></tbody></table>

## Conclusion

In six short steps you have moved a PostgreSQL instance from invisible to fully observable: the right extension is loaded, a read-only monitoring user is in place, the network path is open, the connection is registered, and your tagging scheme is ready to carry the rest of your fleet. The same recipe (extensions, user, network, register, tag, verify) applies to every cluster you add next.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.datasentinel.io/manual/guides/readme/onboard-your-first-cluster.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.