[+] improve development experience with docker compose (#927)

pashagolub · web-flow · commit d38d666c4bf7 · 2025-09-02T09:56:00.000+02:00
* [+] improve development experience with docker compose - add "demo_pgbouncer" and "demo_pgpool" test monitored sources - add "debug" preset with all built-in - fix "pgpool" and "pgbouncer" compose service - fix "postgres-standby" service init * [*] remove `pgbouncer` and `pgpool` metrics from debug preset * [-] fix `buffercache_by_db`, `buffercache_by_type` metrics, closes #928 * [-] fix `pgstattuple` dependent metrics, closes #929 * [-] fix pgpool dashboard layout
diff --git a/README.md b/README.md
@@ -50,6 +50,8 @@ For the fastest development and deployment experience the Docker compose files a
     docker compose -f ./docker/docker-compose.yml build
 
     docker compose -f ./docker/docker-compose.yml up --detach
+
+    docker/compose.add-test-db.sh
     ```
 
 These commands will build and start services listed in the compose file:
@@ -70,22 +72,7 @@ These commands will build and start services listed in the compose file:
 After start, you could open the [monitoring dashboard](http://localhost:3000/) and start
 looking at metrics.
 
-To add a test database under monitoring, you can use [built-in WebUI](http://localhost:8080/). Or simply
-execute from command line:
-
-```shell
-docker/compose.add-test-db.sh
-```
-
-```console
-CREATE EXTENSION
-CREATE EXTENSION
-CREATE FUNCTION
-GRANT
-GRANT
-GRANT
-INSERT 0 1
-```
+To add a test database under monitoring, you can use [built-in WebUI](http://localhost:8080/).
 
 ## Produce Workload
 
diff --git a/docker/compose.add-test-db.sh b/docker/compose.add-test-db.sh
@@ -5,13 +5,19 @@ cd "$(dirname "${BASH_SOURCE[0]}")"
 export MSYS_NO_PATHCONV=1
 
 # We want to pipe the output of the `pgwatch metric print-init` command to the `psql` command
-docker compose exec -T pgwatch /pgwatch/pgwatch metric print-init full | \
+docker compose exec -T pgwatch /pgwatch/pgwatch metric print-init debug | \
 docker compose exec -T -i postgres psql -d pgwatch -v ON_ERROR_STOP=1
 
-docker compose exec -T postgres psql -d pgwatch -v ON_ERROR_STOP=1 -c \
-"INSERT INTO pgwatch.source (name, preset_config, connstr) VALUES 
-    ('demo', 'full', 'postgresql://pgwatch:pgwatchadmin@postgres/pgwatch'), 
-    ('demo_standby', 'full', 'postgresql://pgwatch:pgwatchadmin@postgres-standby/pgwatch')"
-
-
+docker compose exec -T pgwatch /pgwatch/pgwatch metric print-init full | \
+docker compose exec -T -i postgres psql -d pgwatch_metrics -v ON_ERROR_STOP=1
 
+docker compose exec -T postgres psql -d pgwatch -v ON_ERROR_STOP=1 -c \
+"TRUNCATE pgwatch.source CASCADE;
+INSERT INTO pgwatch.source 
+    (name,              dbtype,         preset_config,  connstr) 
+VALUES 
+    ('demo',            'postgres',     'debug',        'postgresql://pgwatch:pgwatchadmin@postgres/pgwatch'),
+    ('demo_metrics',    'postgres',     'full',         'postgresql://pgwatch:pgwatchadmin@postgres/pgwatch_metrics'), 
+    ('demo_standby',    'postgres',     'full',         'postgresql://pgwatch:pgwatchadmin@postgres-standby/pgwatch'),
+    ('demo_pgbouncer',  'pgbouncer',    'pgbouncer',    'postgresql://pgwatch:pgwatchadmin@pgbouncer/pgbouncer'),
+    ('demo_pgpool',     'pgpool',       'pgpool',       'postgresql://pgwatch:pgwatchadmin@pgpool/pgwatch');"
diff --git a/docker/compose.pgbouncer.yml b/docker/compose.pgbouncer.yml
@@ -3,10 +3,16 @@ services:
     image: bitnami/pgbouncer:latest
     container_name: pgbouncer
     ports:
-      - "6432:6432"
+      - "6432:5432"
     environment:
       POSTGRESQL_HOST: postgres
+      POSTGRESQL_PORT: 5432
+      POSTGRESQL_USERNAME: pgwatch
+      POSTGRESQL_PASSWORD: pgwatchadmin
+      POSTGRESQL_DATABASE: pgwatch
       PGBOUNCER_AUTH_TYPE: trust
+      PGBOUNCER_POOL_MODE: session
+      PGBOUNCER_PORT: 5432
     depends_on:
       postgres:
         condition: service_healthy
diff --git a/docker/compose.pgpool.yml b/docker/compose.pgpool.yml
@@ -9,10 +9,10 @@ services:
       PGPOOL_SR_CHECK_USER: postgres
       PGPOOL_SR_CHECK_PASSWORD: standbypass
       PGPOOL_ENABLE_LDAP: no
-      PGPOOL_POSTGRES_USERNAME: postgres
-      PGPOOL_POSTGRES_PASSWORD: adminpassword
-      PGPOOL_ADMIN_USERNAME: admin
-      PGPOOL_ADMIN_PASSWORD: adminpassword
+      PGPOOL_POSTGRES_USERNAME: pgwatch
+      PGPOOL_POSTGRES_PASSWORD: pgwatchadmin
+      PGPOOL_ADMIN_USERNAME: pgwatch
+      PGPOOL_ADMIN_PASSWORD: pgwatchadmin
     depends_on:
       postgres:
         condition: service_healthy
diff --git a/docker/compose.postgres.yml b/docker/compose.postgres.yml
@@ -41,11 +41,36 @@ services:
     depends_on:
       postgres:
         condition: service_healthy
-    command: >
-      bash -c "psql -h postgres -c \"SELECT * FROM pg_create_physical_replication_slot('standby_slot')\" ||
-        rm -rf /var/lib/postgresql/data/* &&
-        pg_basebackup -h postgres --pgdata=/var/lib/postgresql/data --wal-method=stream --progress --write-recovery-conf --slot=standby_slot &&
-        chmod 0700 /var/lib/postgresql/data &&
-        postgres -cshared_preload_libraries=pg_stat_statements -cpg_stat_statements.track=all -ctrack_io_timing=on -ctrack_functions=pl"
+    command: |
+      bash -c "
+        echo 'Setting up standby server...'
+        export PGDATA=/var/lib/postgresql/standby
+        
+        # Check if data directory already exists and is initialized
+        if [ -f /var/lib/postgresql/standby/PG_VERSION ]; then
+          echo 'Data directory already exists and is initialized, starting PostgreSQL...'
+        else
+          echo 'Initializing new standby server...'
+          
+          # Create replication slot if it doesn't exist
+          psql -h postgres -U postgres -c \"SELECT * FROM pg_create_physical_replication_slot('standby_slot');\" 2>/dev/null || true
+          
+          # Create custom data directory with correct permissions
+          mkdir -p /var/lib/postgresql/standby
+          chmod 0700 /var/lib/postgresql/standby
+          
+          # Remove any existing files to ensure clean backup
+          rm -rf /var/lib/postgresql/standby/* || true
+          
+          # Create base backup directly to our custom directory
+          pg_basebackup -h postgres -U postgres -D /var/lib/postgresql/standby -Xs -P -R -S standby_slot
+          
+          # Ensure correct permissions after backup
+          chmod 0700 /var/lib/postgresql/standby
+        fi
+        
+        # Start PostgreSQL with custom data directory
+        exec postgres -D /var/lib/postgresql/standby -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=all -c track_io_timing=on -c track_functions=pl
+      "
     links:
       - postgres
diff --git a/grafana/postgres/v12/pgpool-stats.json b/grafana/postgres/v12/pgpool-stats.json
@@ -18,7 +18,7 @@
   "editable": true,
   "fiscalYearStartMonth": 0,
   "graphTooltip": 0,
-  "id": 33,
+  "id": 10,
   "links": [],
   "panels": [
     {
@@ -44,7 +44,8 @@
             "mode": "absolute",
             "steps": [
               {
-                "color": "green"
+                "color": "green",
+                "value": 0
               },
               {
                 "color": "red",
@@ -79,7 +80,8 @@
                   "mode": "absolute",
                   "steps": [
                     {
-                      "color": "rgba(245, 54, 54, 0.9)"
+                      "color": "rgba(245, 54, 54, 0.9)",
+                      "value": 0
                     },
                     {
                       "color": "rgba(237, 129, 40, 0.89)",
@@ -130,7 +132,7 @@
         },
         "showHeader": true
       },
-      "pluginVersion": "12.0.0",
+      "pluginVersion": "12.1.0",
       "targets": [
         {
           "datasource": {
@@ -223,7 +225,8 @@
             "mode": "absolute",
             "steps": [
               {
-                "color": "green"
+                "color": "green",
+                "value": 0
               },
               {
                 "color": "red",
@@ -257,7 +260,7 @@
           "sort": "desc"
         }
       },
-      "pluginVersion": "12.0.0",
+      "pluginVersion": "12.1.0",
       "targets": [
         {
           "datasource": {
@@ -299,8 +302,8 @@
         "overrides": []
       },
       "gridPos": {
-        "h": 6,
-        "w": 24,
+        "h": 4,
+        "w": 10,
         "x": 0,
         "y": 19
       },
@@ -314,7 +317,7 @@
         "content": "### Brought to you by\n\n[![Cybertec – The PostgreSQL Database Company](https://www.cybertec-postgresql.com/wp-content/uploads/2025/02/cybertec-logo-white-blue.svg)](https://www.cybertec-postgresql.com/en/)\n",
         "mode": "markdown"
       },
-      "pluginVersion": "12.0.0",
+      "pluginVersion": "12.1.0",
       "title": "",
       "transparent": true,
       "type": "text"
diff --git a/internal/metrics/metrics.yaml b/internal/metrics/metrics.yaml
@@ -294,6 +294,8 @@ metrics:
             Retrieves buffer cache statistics grouped by database, providing insights into the size of buffers used by each database.
             It calculates the total size of buffers in bytes for each database.
             This metric helps administrators monitor buffer usage across different databases in the PostgreSQL instance.
+        init_sql: |-
+            create extension if not exists pg_buffercache;
         sqls:
             11: |-
                 select /* pgwatch_generated */
@@ -316,6 +318,8 @@ metrics:
             by different relation kinds. It calculates the total size of buffers in bytes for each relation kind
             (e.g., Table, Index, Toast, Materialized view). This metric helps administrators monitor buffer usage across
             different relation types in the PostgreSQL instance.
+        init_sql: |-
+            create extension if not exists pg_buffercache;            
         sqls:
             11: |-
                 select /* pgwatch_generated */
@@ -3222,6 +3226,8 @@ metrics:
         description: >
             This metric collects approximate table bloat statistics using the `pgstattuple_approx` function.
             It provides insights into the amount of free space and dead tuples in tables, which can help in identifying bloat issues.
+        init_sql: |-
+            create extension if not exists pgstattuple;
         sqls:
             11: |-
                 select /* pgwatch_generated */
@@ -3247,6 +3253,8 @@ metrics:
         description: >
             This metric provides a summary of approximate table bloat statistics, including the total bloat size and percentage for the current database.
             It aggregates data from multiple tables to give an overview of bloat across the database.
+        init_sql: |-
+            create extension if not exists pgstattuple;
         sqls:
             11: |-
                 /* accessing pgstattuple_approx directly requires superuser or pg_stat_scan_tables/pg_monitor builtin roles or
@@ -3284,6 +3292,8 @@ metrics:
         description: >
             This metric provides a summary of approximate table bloat statistics, including the total bloat size and percentage for the current database.
             It aggregates data from multiple tables to give an overview of bloat across the database.
+        init_sql: |-
+            create extension if not exists pgstattuple;
         sqls:
             11: |
                 WITH q_bloat AS (
@@ -4912,3 +4922,82 @@ presets:
             table_io_stats: 600
             table_stats: 300
             wal: 60
+    debug:
+        description: all available metrics with 30 second intervals for debugging and development
+        metrics:
+            archiver: 30
+            archiver_pending_count: 30
+            backends: 30
+            backup_age_pgbackrest: 30
+            backup_age_walg: 30
+            bgwriter: 30
+            blocking_locks: 30
+            buffercache_by_db: 30
+            buffercache_by_type: 30
+            change_events: 30
+            checkpointer: 30
+            configuration_hashes: 30
+            cpu_load: 30
+            database_conflicts: 30
+            datfrozenxid: 30
+            db_size: 30
+            db_size_approx: 30
+            db_stats: 30
+            db_stats_aurora: 30
+            index_hashes: 30
+            index_stats: 30
+            instance_up: 30
+            invalid_indexes: 30
+            kpi: 30
+            locks: 30
+            locks_mode: 30
+            logical_subscriptions: 30
+            postgres_role: 30
+            privilege_changes: 30
+            psutil_cpu: 30
+            psutil_disk: 30
+            psutil_disk_io_total: 30
+            psutil_mem: 30
+            reco_add_index: 30
+            reco_default_public_schema: 30
+            reco_disabled_triggers: 30
+            reco_drop_index: 30
+            reco_nested_views: 30
+            reco_partial_index_candidates: 30
+            reco_sprocs_wo_search_path: 30
+            reco_superusers: 30
+            replication: 30
+            replication_slot_stats: 30
+            replication_slots: 30
+            sequence_health: 30
+            server_log_event_counts: 30
+            settings: 30
+            smart_health_per_disk: 30
+            sproc_hashes: 30
+            sproc_stats: 30
+            stat_activity: 30
+            stat_io: 30
+            stat_ssl: 30
+            stat_statements: 30
+            stat_statements_calls: 30
+            stat_statements_no_query_text: 30
+            subscription_stats: 30
+            table_bloat_approx_stattuple: 30
+            table_bloat_approx_summary: 30
+            table_bloat_approx_summary_sql: 30
+            table_hashes: 30
+            table_io_stats: 30
+            table_stats: 30
+            table_stats_approx: 30
+            unused_indexes: 30
+            vmstat: 30
+            wait_events: 30
+            wal: 30
+            wal_receiver: 30
+            wal_size: 30
+            wal_stats: 30
+            # pgbouncer and pgpool metrics need separate source settings
+            # pgbouncer_clients: 30
+            # pgbouncer_stats: 30
+            # pgpool_processes: 30
+            # pgpool_stats: 30
