pgwatch

https://pgwat.ch/v5.x/
Admin
pgwatch is a scalable and flexible PostgreSQL-specific monitoring solution that offers comprehensive...
Tokens:39,848
Snippets:635
Trust Score:5.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install PL/Python and psutil helpers

Source: https://pgwat.ch/v5.x/tutorial/preparing_databases.html

Install necessary system packages and apply initialization scripts for OS-level metrics.

```bash
# first install the Python bindings for Postgres
apt install postgresql-plpython3-XY
# yum install postgresqlXY-plpython3

pgwatch metric print-init cpu_load | psql -d mydb

# psutil helpers are only needed when full set of common OS metrics is wanted
apt install python3-psutil
pgwatch metric print-init psutil_cpu psutil_mem psutil_disk psutil_disk_io_total | psql -d mydb
```

--------------------------------

### Start pgwatch Metrics Collection Agent

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html?q=

Starts the pgwatch agent with specified source and sink configurations. Use --log-level=debug for detailed logging during setup.

```bash
pgwatch \
    --sources=postgresql://pgwatch:xyz@localhost:5432/pgwatch \
    --sink=postgresql://pgwatch:xyz@localhost:5432/pgwatch_metrics \
    --log-level=debug
```

--------------------------------

### Example Resolved Connection Strings

Source: https://pgwat.ch/v5.x/reference/cli_env.html

This output shows example resolved connection strings for different monitoring targets discovered from a source configuration.

```text
pg-stage1_postgres=postgresql://pgwatch:pgwatch@localhost:5432/postgres
pg-stage1_pagila=postgresql://pgwatch:pgwatch@localhost:5432/pagila
pg-stage1_test=postgresql://pgwatch:pgwatch@localhost:5432/test
pg-stage1_timetable=postgresql://pgwatch:pgwatch@localhost:5432/timetable
pg-stage1_test602=postgresql://pgwatch:pgwatch@localhost:5432/test602
```

--------------------------------

### Example: Initialize CPU Load Metric

Source: https://pgwat.ch/v5.x/tutorial/preparing_databases.html?q=

This example shows the output of `pgwatch metric print-init cpu_load`, including creating the PL/Python extension and helper function. Ensure you have the necessary privileges to execute these commands.

```sql
--  cpu_load
BEGIN;
CREATE EXTENSION IF NOT EXISTS plpython3u;
CREATE OR REPLACE FUNCTION get_load_average(OUT load_1min float, OUT load_5min float, OUT load_15min float) AS
$$
  from os import getloadavg
  la = getloadavg()
  return [la[0], la[1], la[2]]
$$ LANGUAGE plpython3u VOLATILE;
GRANT EXECUTE ON FUNCTION get_load_average() TO pgwatch;
COMMENT ON FUNCTION get_load_average() is 'created for pgwatch';
COMMIT;
```

--------------------------------

### Install pgwatch on Debian/Ubuntu

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

Installs pgwatch using apt after adding the official PostgreSQL Apt Repository.

```bash
sudo apt update && sudo apt install pgwatch
```

--------------------------------

### Install pgwatch with Helm

Source: https://pgwat.ch/v5.x/concept/kubernetes.html

Navigate to the Kubernetes directory and install pgwatch using Helm, specifying a values file. Ensure you have Helm installed and configured for your Kubernetes cluster.

```bash
cd openshift_k8s
helm install -f chart-values.yml pgwatch ./helm-chart
```

--------------------------------

### Start pgwatch Agent

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

Commands to start the pgwatch metrics collection agent directly or via systemd.

```bash
pgwatch \
    --sources=postgresql://pgwatch:xyz@localhost:5432/pgwatch \
    --sink=postgresql://pgwatch:xyz@localhost:5432/pgwatch_metrics \
    --log-level=debug
```

```bash
useradd -m -s /bin/bash pgwatch # default SystemD templates run under the pgwatch user
sudo systemctl start pgwatch
sudo systemctl status pgwatch
```

--------------------------------

### Install pgwatch using .deb package

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

Installs pgwatch by downloading and unpacking a .deb package. Ensure to replace the version number with the latest available.

```bash
# find out the latest package link and replace below, using v4.0 here
wget https://github.com/cybertec-postgresql/pgwatch/releases/download/v4.0.0/pgwatch_Linux_x86_64.deb
sudo dpkg -i pgwatch_Linux_x86_64.deb
```

--------------------------------

### Start pgwatch with Configuration Database

Source: https://pgwat.ch/v5.x/howto/config_db_bootstrap.html

Configure pgwatch to use the initialized database for sources and sinks.

```bash
$ pgwatch --sources=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch --sink=postgresql://pgwatch@10.0.0.42/measurements
...
[INFO] [metrics:75] [presets:17] [sources:2] sources and metrics refreshed
...
```

--------------------------------

### Initialize psutil Helpers

Source: https://pgwat.ch/v5.x/tutorial/preparing_databases.html?q=

Install the `psutil` Python library and then use `pgwatch metric print-init` to generate and apply initialization SQL for OS metrics like CPU and memory usage.

```bash
apt install python3-psutil
pgwatch metric print-init psutil_cpu psutil_mem psutil_disk psutil_disk_io_total | psql -d mydb
```

--------------------------------

### Print Init SQL for Metrics or Presets

Source: https://pgwat.ch/v5.x/reference/cli_env.html?q=

Get and print the initialization SQL for specified metrics or presets. This command helps in understanding the SQL structure required for metric collection.

```bash
# Print init SQL for a specific metric
pgwatch metric print-init bgwriter cpu_load
```

```bash
# Print init SQL for a specific preset
pgwatch metric print-init exhaustive
```

--------------------------------

### Install Grafana

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

Commands to add the Grafana repository and install the package on Debian-based systems.

```bash
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list
sudo apt-get update && sudo apt-get install grafana

# review / change config settings and security, etc
sudo vi /etc/grafana/grafana.ini
```

--------------------------------

### Start and Enable Grafana Server

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

Commands to reload the systemd daemon, start the Grafana server, and check its status. Ensure these services are running for Grafana to function.

```bash
sudo systemctl daemon-reload
sudo systemctl start grafana-server
sudo systemctl status grafana-server
```

--------------------------------

### Run pgwatch binary

Source: https://pgwat.ch/v5.x/tutorial/upgrading.html

Attempt to start the pgwatch binary to check for schema compatibility.

```bash
pgwatch --sources=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch --sink=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch_metrics
```

--------------------------------

### Configure Grafana Database Settings

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html?q=

Example configuration for the [database] section in /etc/grafana/grafana.ini to connect to the pgwatch_grafana database.

```ini
[database]
type = postgres
host = my-postgres-db:5432
name = pgwatch_grafana
user = pgwatch_grafana
password = xyz
```

--------------------------------

### GET /preset

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

List all available metric presets.

```APIDOC
## GET /preset

### Description
Get all available metric presets.

### Method
GET

### Endpoint
/preset

### Response
#### Success Response (200)
- **presets** (array) - JSON array of preset objects.
```

--------------------------------

### Initialize pgwatch Sink

Source: https://pgwat.ch/v5.x/howto/metrics_db_bootstrap.html?q=

Start pgwatch with the sink configuration to automatically initialize the database schema.

```bash
$ pgwatch --sources=/etc/sources.yaml --sink=postgresql://pgwatch@10.0.0.42/measurements
[INFO] [sink:postgresql://pgwatch@10.0.0.42/measurements] Initialising measurements database...
[INFO] [sink:postgresql://pgwatch@10.0.0.42/measurements] Measurements sink activated
...
```

--------------------------------

### YAML Configuration with Environment Variables

Source: https://pgwat.ch/v5.x/concept/installation_options.html

Example of a YAML configuration file for pgwatch_v5_x, demonstrating the use of environment variables for sensitive information like connection strings. Ensure environment variables are properly set before deployment.

```yaml
- name: ...
  conn_str: $MY_VERY_SECRET_CONN_STR
  ...

```

--------------------------------

### GET /source

Source: https://pgwat.ch/v5.x/reference/rest.html

Retrieves a list of all monitoring sources.

```APIDOC
## GET /source

### Description
Get all monitoring sources.

### Method
GET

### Endpoint
/source

### Response
#### Success Response (200)
- **sources** (array) - JSON array of source objects
```

--------------------------------

### Define Monitoring Sources in YAML

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html?q=

Example structure for a YAML configuration file defining monitored database sources and their associated metrics.

```yaml
- name: test1       # An arbitrary unique name for the monitored source
  kind: postgres    # One of the:
                      # - postgres
                      # - postgres-continuous-discovery
                      # - pgbouncer
                      # - pgpool
                      # - patroni
                      # - patroni-continuous-discovery
                      # - patroni-namespace-discover
                      # Defaults to postgres if not specified
  conn_str: postgresql://pgwatch:xyz@somehost/mydb
  preset_metrics: exhaustive # from list of presets defined in "metrics.yaml" or in the config DB
  custom_metrics:    # map of metrics and intervals, if both preset_metrics and custom_metrics are specified, custom wins
        backends: 300
        archiver: 120
  preset_metrics_standby: # optional preset configuration for standby state, same as preset_metrics
  custom_metrics_standby: # optional custom metrics for standby state, same as custom_metrics
  include_pattern: # regex to filter databases to actually monitor for the "continuous" modes
  exclude_pattern:
  is_enabled: true
  group: default # just for logical grouping of DB hosts or for "sharding", i.e. splitting the workload between many gatherer daemons
  custom_tags:      # option to add arbitrary tags for every stored data row,
        aws_instance_id: i-0af01c0123456789a       # for example to fetch data from some other source onto a same Grafana graph
...
```

--------------------------------

### GET /source

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Retrieves a list of all monitoring sources.

```APIDOC
## GET /source

### Description
Get all monitoring sources.

### Method
GET

### Endpoint
/source

### Response
- **sources** (array) - JSON array of source objects
```

--------------------------------

### Configure pgwatch with Configuration Database

Source: https://pgwat.ch/v5.x/howto/config_db_bootstrap.html?q=

Start pgwatch with the configuration database specified for sources and sink. The program will automatically refresh sources and metrics definitions.

```bash
$ pgwatch --sources=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch --sink=postgresql://pgwatch@10.0.0.42/measurements
... [INFO] [metrics:75] [presets:17] [sources:2] sources and metrics refreshed
...
```

--------------------------------

### Run Basic pgwatch-demo Docker Container

Source: https://pgwat.ch/v5.x/tutorial/docker_installation.html?q=

Starts a pgwatch-demo container in detached mode, with automatic restart. Exposes Grafana (3000) and Web UI (8080) ports.

```bash
docker run -d --restart=unless-stopped -p 3000:3000 -p 8080:8080 \
--name pgwatch-demo cybertecpostgresql/pgwatch-demo:X.Y.Z
```

--------------------------------

### Manage pgwatch Service with SystemD

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html?q=

Commands to manage the pgwatch service using SystemD, including starting and checking its status. Assumes the 'pgwatch' user has been created.

```bash
useradd -m -s /bin/bash pgwatch # default SystemD templates run under the pgwatch user
sudo systemctl start pgwatch
sudo systemctl status pgwatch
```

--------------------------------

### Install pg_stat_statements Dependencies

Source: https://pgwat.ch/v5.x/tutorial/preparing_databases.html?q=

Commands to install the contrib package required for pg_stat_statements on different Linux distributions.

```bash
yum install -y postgresqlXY-contrib
```

```bash
apt install postgresql-contrib
```

--------------------------------

### Print Initialization SQL for a Metric

Source: https://pgwat.ch/v5.x/tutorial/preparing_databases.html?q=

Use this command to view the SQL statements required to initialize a specific metric or preset. This is useful for understanding dependencies and preparing for manual execution.

```bash
pgwatch metric print-init <metric or preset name> ...
```

--------------------------------

### Inspect metric initialization scripts

Source: https://pgwat.ch/v5.x/tutorial/preparing_databases.html

Use this command to view the initialization SQL for specific metrics or presets.

```bash
pgwatch metric print-init <metric or preset name> ...
```

```bash
$ pgwatch metric print-init cpu_load
--  cpu_load
BEGIN;
CREATE EXTENSION IF NOT EXISTS plpython3u;
CREATE OR REPLACE FUNCTION get_load_average(OUT load_1min float, OUT load_5min float, OUT load_15min float) AS
$$
  from os import getloadavg
  la = getloadavg()
  return [la[0], la[1], la[2]]
$$ LANGUAGE plpython3u VOLATILE;
GRANT EXECUTE ON FUNCTION get_load_average() TO pgwatch;
COMMENT ON FUNCTION get_load_average() is 'created for pgwatch';
COMMIT;
```

--------------------------------

### Install PL/Python Extension (RHEL/CentOS)

Source: https://pgwat.ch/v5.x/tutorial/preparing_databases.html?q=

Install the PL/Python 3 extension for PostgreSQL on RHEL-based systems. Replace 'XY' with your PostgreSQL version.

```bash
yum install postgresqlXY-plpython3
```

--------------------------------

### Install PL/Python Extension (Debian/Ubuntu)

Source: https://pgwat.ch/v5.x/tutorial/preparing_databases.html?q=

Install the PL/Python 3 extension for PostgreSQL on Debian-based systems. Replace 'XY' with your PostgreSQL version.

```bash
apt install postgresql-plpython3-XY
```

--------------------------------

### Apply initialization scripts to a database

Source: https://pgwat.ch/v5.x/tutorial/preparing_databases.html

Pipe the output of the print-init command into psql to execute the initialization scripts on a target database.

```bash
export PGUSER=superuser
pgwatch metric print-init cpu_load psutil_mem psutil_disk | psql -d mydb
```

--------------------------------

### Install Grafana Heatmap Plugin

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

Command to install the 'savantly-heatmap-panel' Grafana plugin. This plugin is required for specific dashboards, such as the 'Biggest relations treemap'.

```bash
grafana-cli plugins install savantly-heatmap-panel
```

--------------------------------

### Configure SystemD service

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html?q=

Sample SystemD unit file configuration for pgwatch auto-start.

```ini
[Unit]
Description=pgwatch
After=network-online.target
```

--------------------------------

### Initialize pgwatch v3 configuration database

Source: https://pgwat.ch/v5.x/howto/migrate_v2_to_v3.html

Use the pgwatch CLI with the 'config init' command to create the necessary v3 tables and indexes in the pgwatch database. Ensure you provide the correct connection string.

```bash
pgwatch --sources=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch config init
```

--------------------------------

### Run pgwatch-demo with Docker Volumes

Source: https://pgwat.ch/v5.x/tutorial/docker_installation.html?q=

Launches the pgwatch-demo container with persistent volumes for data and configuration, exposing Grafana, Postgres, and Web UI ports.

```bash
docker run -d --restart=unless-stopped --name pgwatch \
    -p 3000:3000 -p 127.0.0.1:5432:5432 -p 192.168.1.XYZ:8080:8080 \
    -v pg:/var/lib/postgresql/data -v grafana:/var/lib/grafana -v pgwatch:/pgwatch/persistent-config \
    cybertecpostgresql/pgwatch-demo:X.Y.Z
```

--------------------------------

### Manage metrics

Source: https://pgwat.ch/v5.x/reference/cli_env.html?q=

Commands to list, print initialization SQL, or print metric SQL definitions.

```APIDOC
## pgwatch metric <print-init | print-sql | list>

### Description
Manages metric definitions, including exporting to YAML, printing initialization SQL, or printing specific metric SQL queries.

### Parameters
#### Options
- **-m, --metrics** (string) - Required - Metrics configuration
- **-v, --version** (string) - Optional - PostgreSQL version for print-sql command
```

--------------------------------

### Verify Database Tables

Source: https://pgwat.ch/v5.x/howto/config_db_bootstrap.html

Connect to the configuration database and list the pgwatch schema tables.

```bash
$ psql postgresql://pgwatch:pgwatchadmin@localhost/pgwatch
psql (17.2)

pgwatch=# \dt pgwatch.*
           List of relations
 Schema  |   Name    | Type  |  Owner
---------+-----------+-------+---------
 pgwatch | metric    | table | pgwatch
 pgwatch | migration | table | pgwatch
 pgwatch | preset    | table | pgwatch
 pgwatch | source    | table | pgwatch
(4 rows)
```

--------------------------------

### GET /liveness

Source: https://pgwat.ch/v5.x/reference/rest.html

Checks if the service is running.

```APIDOC
## GET /liveness

### Description
Check if the service is running (no authentication required).

### Method
GET

### Endpoint
/liveness

### Response
#### Success Response (200)
- **status** (string) - Returns "ok" if service is alive
```

--------------------------------

### GET /liveness

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Checks if the service is running.

```APIDOC
## GET /liveness

### Description
Check if the service is running (no authentication required).

### Method
GET

### Endpoint
/liveness

### Response
- **status** (string) - Status of the service (e.g., "ok")
```

--------------------------------

### List All Presets

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Retrieve all available metric presets.

```bash
$ curl -H "Token: $TOKEN" -X GET http://localhost:8080/preset
```

--------------------------------

### GET /metric

Source: https://pgwat.ch/v5.x/reference/rest.html

Retrieves all available metrics definitions.

```APIDOC
## GET /metric

### Description
Get all available metrics definitions.

### Method
GET

### Endpoint
/metric

### Response
#### Success Response (200)
- **metrics** (array) - JSON array of metric objects
```

--------------------------------

### Create Preset

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Add a new preset or multiple presets by providing key-value pairs.

```bash
$ curl -X POST http://localhost:8080/preset \
  -H "Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_preset": {
      "Description": "Custom monitoring preset",
      "Metrics": {
        "db_stats": 60,
        "table_stats": 300,
        "custom_metric": 120
      }
    }
  }'
```

--------------------------------

### GET /metric

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Retrieves all available metric definitions.

```APIDOC
## GET /metric

### Description
Get all available metrics definitions.

### Method
GET

### Endpoint
/metric

### Response
- **metrics** (array) - JSON array of metric objects
```

--------------------------------

### SystemD auto-start service for pgwatch

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

A sample SystemD service unit file to configure pgwatch for automatic startup.

```systemd
[Unit]
Description=pgwatch
After=network-online.target

```

--------------------------------

### GET /preset/{name}

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Retrieve a specific preset by name.

```APIDOC
## GET /preset/{name}

### Description
Retrieve a specific preset by name.

### Method
GET

### Endpoint
/preset/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the preset to retrieve.

### Response
#### Success Response (200)
- **preset_definition** (object) - JSON object with preset definition.
```

--------------------------------

### GET /metric/{name}

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Retrieve a specific metric definition by name.

```APIDOC
## GET /metric/{name}

### Description
Retrieve a specific metric definition by name.

### Method
GET

### Endpoint
/metric/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the metric to retrieve.

### Response
#### Success Response (200)
- **metric_definition** (object) - JSON object with metric definition.
```

--------------------------------

### Get Specific Preset

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Retrieve a specific preset definition by name.

```bash
$ curl -H "Token: $TOKEN" -X GET http://localhost:8080/preset/custom_preset
```

--------------------------------

### Initialize Configuration Schema

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

Manually initialize the pgwatch configuration schema in the database.

```bash
pgwatch --sources=postgresql://pgwatch:xyz@localhost/pgwatch config init
```

--------------------------------

### Get Specific Metric

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Retrieve a specific metric definition by its name.

```bash
$ curl -H "Token: $TOKEN" -X GET http://localhost:8080/metric/custom_metric
```

--------------------------------

### Create Database and Role via psql

Source: https://pgwat.ch/v5.x/howto/metrics_db_bootstrap.html?q=

Use psql to create a dedicated role and database for storing metrics.

```sql
$ psql -U postgres -h 10.0.0.42 -p 5432 -d postgres
psql (17.2)

postgres=# CREATE ROLE pgwatch WITH LOGIN PASSWORD 'pgwatchadmin';
CREATE ROLE

postgres=# CREATE DATABASE measurements OWNER pgwatch;
CREATE DATABASE
```

--------------------------------

### GET /source/{name}

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Retrieves details for a specific monitoring source.

```APIDOC
## GET /source/{name}

### Description
Retrieve a specific source by name.

### Method
GET

### Endpoint
/source/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the source
```

--------------------------------

### Compile pgwatch from source

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

Steps to compile pgwatch from source, including cloning the repository, building the web UI, generating Go code from protobuf files, and compiling the main daemon.

```bash
# Clone the Repo
git clone https://github.com/cybertec-postgresql/pgwatch.git

# Build the webui
cd pgwatch/internal/webui
yarn install --network-timeout 100000 && yarn build

# generate the Go code from protobuf files
cd ../../ && go generate ./api/pb

# Compile pgwatch
go build ./cmd/pgwatch/
```

--------------------------------

### Manage configurations

Source: https://pgwat.ch/v5.x/reference/cli_env.html?q=

Commands to initialize or upgrade the configuration and sink databases.

```APIDOC
## pgwatch config <init | upgrade>

### Description
Initializes or upgrades the configuration and/or sink database with required tables and functions.

### Parameters
#### Options
- **-s, --sources** (string) - Optional - PostgreSQL-based source database
- **-m, --metrics** (string) - Optional - Metrics configuration
- **--sink** (string) - Optional - Sink database
```

--------------------------------

### Define Request Body Formats

Source: https://pgwat.ch/v5.x/reference/rest.html?q=

Examples of JSON structures used for creating or updating resources.

```json
{
  "Name": "my-postgres",
  "Kind": "postgres",
  "ConnStr": "postgresql://...",
  "IsEnabled": true
}
```

```json
{
  "resource_name": {
    "field1": "value1",
    "field2": "value2"
  }
}
```

```json
{
  "field1": "updated_value1",
  "field2": "updated_value2"
}
```

--------------------------------

### Bootstrap Configuration Database

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

Commands to create the pgwatch configuration database and user.

```bash
psql -c "create user pgwatch password 'xyz'"
psql -c "create database pgwatch owner pgwatch"
```

--------------------------------

### List all available presets

Source: https://pgwat.ch/v5.x/reference/rest.html

Retrieves a list of all configured metric presets. This endpoint is useful for discovering available presets.

```bash
$ curl -H "Token: $TOKEN" -X GET http://localhost:8080/preset

```

--------------------------------

### Retrieve Specific Monitoring Source

Source: https://pgwat.ch/v5.x/reference/rest.html

Get the details of a single monitoring source by its name. Authentication is required.

```shell
$ curl -H "Token: $TOKEN" -X GET http://localhost:8080/source/my-postgres

```

--------------------------------

### Retrieve a specific preset

Source: https://pgwat.ch/v5.x/reference/rest.html

Fetches a single preset definition by its name. Use this to get the details of a specific preset.

```bash
$ curl -H "Token: $TOKEN" -X GET http://localhost:8080/preset/custom_preset

```

--------------------------------

### Verify Database Schemas

Source: https://pgwat.ch/v5.x/howto/metrics_db_bootstrap.html?q=

Connect to the measurements database and list schemas to verify pgwatch initialization.

```sql
$ psql -U pgwatch -h 10.0.0.42 -p 5432 -d measurements
psql (17.2)

measurements=> \dn
     List of schemas
     Name      |  Owner
---------------+---------
 admin         | pgwatch
 subpartitions | pgwatch
(3 rows)
```

--------------------------------

### Get Latest pgwatch Release Version

Source: https://pgwat.ch/v5.x/tutorial/docker_installation.html?q=

Use this command to fetch the latest release tag of the pgwatch project from GitHub.

```bash
curl -so- https://api.github.com/repos/cybertec-postgresql/pgwatch/releases/latest | jq .tag_name | grep -oE '[0-9\.]+'
```

--------------------------------

### List All Metrics and Presets

Source: https://pgwat.ch/v5.x/reference/cli_env.html?q=

Export all built-in metrics and presets in YAML format. This is useful for creating custom metrics.yaml files, inspecting definitions, or copying specific metrics.

```bash
# Export all metrics and presets
pgwatch metric list > custom-metrics.yaml
```

--------------------------------

### Initialize custom metrics

Source: https://pgwat.ch/v5.x/tutorial/preparing_databases.html

Specify a custom metrics configuration file when printing initialization scripts.

```bash
pgwatch --metrics=/path/to/your/metrics.yaml metric print-init ...
```

--------------------------------

### Initialize or Upgrade pgwatch Configuration

Source: https://pgwat.ch/v5.x/reference/cli_env.html?q=

Use this command to initialize or upgrade the configuration and/or sink database. Requires specifying at least one of -s, --sources, -m, --metrics, or --sink options. The 'init' subcommand works with PostgreSQL-based sources, metrics, and sinks, while 'upgrade' is for applying pending migrations and does not support file or folder-based configurations.

```bash
pgwatch [OPTIONS] config <init | upgrade>
```

--------------------------------

### Resolve and List Source Connection Strings

Source: https://pgwat.ch/v5.x/reference/cli_env.html?q=

Connect to configured sources and return the resolved connection strings for discovered monitoring targets. This is useful for understanding the exact connection details for each target.

```bash
pgwatch --sources=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch source resolve
```

--------------------------------

### Configure Grafana Database Connection

Source: https://pgwat.ch/v5.x/tutorial/custom_installation.html

Example configuration for the `grafana.ini` file to connect Grafana to a PostgreSQL database. Specify the database type, host, name, user, and password.

```ini
[database]
type = postgres
host = my-postgres-db:5432
name = pgwatch_grafana
user = pgwatch_grafana
password = xyz

```

--------------------------------

### Initialize Configuration Schema

Source: https://pgwat.ch/v5.x/howto/config_db_bootstrap.html

Manually initialize the pgwatch schema using the config init command.

```bash
pgwatch --sources=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch config init
```

```bash
pgwatch --metrics=postgresql://pgwatch:pgwatchadmin@localhost/pgwatch config init
```

```bash
pgwatch --sink=postgresql://pgwatch:pgwatchadmin@localhost/measurements config init
```
Tokens:
Raw