0.15.0

Release 0.15.0

Release Date: 2026-06-02

AI-native PostgreSQL observability - monitoring, health checks, and root cause analysis for engineers and AI agents.

---

⚠️ Breaking change: bundled PostgreSQL 15 → 17 — upgrade requires a data migration

0.15.0 upgrades the stack's bundled PostgreSQL from 15 to 17 (sink-postgres, and on the demo target-db / target-standby). PostgreSQL's on-disk format is not compatible across major versions, so the new images refuse to start on a PostgreSQL 15 data directory — an in-place upgrade will not come up until you migrate the data. Your data is not deleted (the guard refuses to touch it), and your externally-monitored databases are unaffected.

Before bringing the stack up, follow the PostgreSQL 15 → 17 migration guide: either dump/restore sink-postgres to preserve historical measurements, or reset it to start fresh on PostgreSQL 17 (live monitoring continues; only past measurements are lost). On the demo, re-clone target-standby via pg_basebackup rather than migrating the replica. Keep the PostgreSQL 15 volume as a backup until you have verified PostgreSQL 17.

---

Highlights

PostgresAI 0.15 is a monitoring-depth and production-hardening release. It expands the full monitoring stack with new PostgreSQL and infrastructure signals, makes Grafana dashboards more useful for root cause analysis, improves CLI workflows for checkups, reports, issues, and MCP, and adds the release/security/quality guardrails needed for safer production operation.

This release includes 74 merged changes since 0.14.0. The biggest improvements are:

• New monitoring coverage for xmin horizon, WAL growth, PostgreSQL 16+ pg_stat_io, per-relation top-N metrics, lock-wait session PIDs, and bloat checks.
• A redesigned Autovacuum and xmin horizon dashboard plus a new I/O Statistics dashboard.
• Better CLI workflows for reports, monitoring target registration, attachments on issues/comments, checkup output, upgrades, and Docker Compose compatibility.
• Stronger self-hosted monitoring security and reliability: VictoriaMetrics basic auth, encrypted-at-rest infrastructure checks, pinned Docker image tags, restart policies, resource limits, idempotent config seeding, and safer prerelease publishing.
• A much stronger quality system: PostgreSQL 13-18 checkup coverage, reporter coverage improvements, compliance vectors, SAST remediation, CodeQL, Dependabot, gitleaks, and release-readiness checks.

Summary

This release includes 74 merged changes since 0.14.0, led by deeper monitoring coverage, stronger Grafana RCA dashboards, safer monitoring-stack upgrades, and release/security hardening.

Upgrade Notes

• Node.js 18+ is required. Older Node versions now fail early with a clear error instead of breaking later (!201).
• Monitoring stack upgrades can require new .env keys, especially VM_AUTH_USERNAME and VM_AUTH_PASSWORD for VictoriaMetrics basic auth. postgresai mon local-install -y, postgresai mon update, and postgresai mon update-config migrate .env additively and preserve existing values.
• Newer stack versions can also require a matching docker-compose.yml (the 0.15 VictoriaMetrics basic auth wiring lives on the sink-prometheus service). On non-git installs (npx / npm install -g), postgresai mon local-install -y, postgresai mon update, and postgresai mon update-config now refresh the bundled docker-compose.yml to the new stack version, backing up the old file as docker-compose.yml.bak-<oldtag>-<hash> (the pristine original is preserved across repeated runs, and the fetched compose is validated as a real stack file before it replaces yours). This closes the prior gap where npx upgrades kept a stale 0.14 compose and sink-prometheus crashed with a missing VM_AUTH_USERNAME env var (!283). Git checkouts already get this via git pull, so the refresh is skipped for them.
• If you run Docker Compose manually instead of through the CLI, add VM_AUTH_USERNAME=vmauth and a non-empty VM_AUTH_PASSWORD before upgrading to 0.15, or run postgresai mon update-config once to have the CLI fill them in and refresh the compose for you.
• To rotate VictoriaMetrics credentials, run VM_AUTH_PASSWORD="$(openssl rand -base64 18)" ./scripts/rotate-vm-auth.sh from the monitoring directory.
• Prerelease npm tags no longer move latest. Stable 0.15.0 should be the version that updates latest.
• Helm users: the chart defaults have been prepared for PostgresAI 0.15; review updated chart values before upgrading (!280).

New Features

• Monitoring metrics: added xmin horizon monitoring for vacuum and wraparound risk analysis (!242).
• Monitoring metrics: added pg_wal directory size monitoring (!243).
• Monitoring metrics: added PostgreSQL 16+ pg_stat_io support for I/O monitoring (!168).
• Checkup: added F004 and F005 bloat estimation checks (!180).
• Metrics quality: expanded pgwatch top-N and $other$ bucket coverage across per-relation metrics (!262, !267).
• Lock analysis: lock-wait metrics now include session PIDs, making blocker investigation more direct (!278).
• Grafana: redesigned Dashboard 7 around Autovacuum and xmin horizon root cause analysis (!254, !257).
• Grafana: added Dashboard 14 for I/O Statistics (!168).
• Grafana: Desert Bloom is now the default theme (!221).
• CLI: added a reports command group (!211).
• CLI: added --project support to mon local-install and monitoring instance registration (!210).
• CLI and MCP: added first-class image/file attachments for issues and comments (!249, !215).
• CLI: improved release-notes generation with MR grouping and links (!195).
• Monitoring telemetry: added telemetry reporter for monitoring instances (!251).
• Monitoring retention: VictoriaMetrics and query-id retention are now parameterized by plan via VM_RETENTION_PERIOD and QUERYID_RETENTION_HOURS (!259).
• Compose: added per-service CPU/memory controls and VictoriaMetrics query/search flags (!252).

Fixes and Hardening

Release blockers fixed after rc.5:

• Dashboard 2 drill-down links now emit a clean var-db_name value (!274).
• Dashboard 1 and Dashboard 7 release blockers were fixed: duplicate panel IDs, pg_wal status visibility, Vacuum timeline scoping, Dashboard 7 variable scoping, xmin-horizon monitoring-user noise, and dashboard parity regressions (!277).
• Grafana RC6 demo QA pass: Dashboard 3 query text, Dashboard 6 title fix, ASH legend de-duplication, default time range, and the Grafana version banner (!281).
• Lock-wait session PID labels were fixed (!278).
• postgresai mon targets add now applies target config after adding the target (!279).
• CLI upgrade path: mon update and mon update-config now migrate .env safely for new required keys (!270).
• CLI upgrade path: non-git npx upgrades now refresh the bundled docker-compose.yml to the new stack version (wiring newly-required VM_AUTH_* config onto sink-prometheus), backing up the old file as docker-compose.yml.bak-<oldtag>-<hash> and validating the fetched compose before it replaces the working one. This fixes the GA blocker where npx upgrades kept a stale 0.14 compose and sink-prometheus crashed on a missing VM_AUTH_USERNAME env var (!283).
• Monitoring reliability: Prometheus sink cache is preserved across scrapes (!266).
• Monitoring reliability: config seeding is now idempotent via a version marker, preserving operator edits across restarts (!250).
• Monitoring reliability: pgwatch extension parsing, pg_stat_file permission handling, missing PromQL utility packaging, and startup DB permission checks were hardened (!219, [!244](h...

postgresai 0.14.0

AI-native PostgreSQL observability — monitoring, health checks, and root cause analysis for engineers and AI agents.

Highlights

0.14 brings direct PostgreSQL health checks via postgresai checkup, Claude Code plugin (/pgai), first-class Supabase support, and MCP tools for AI-assisted database management. The CLI was migrated to Bun for faster performance. Grafana dashboards now display query texts in Top-N charts (Dashboard 2), version/build timestamps, and new index analysis panels showing size, reads/hits in bytes. This release also delivers dozens of fixes and improvements.

---

Summary

This release includes 72 changes.

🚀 New Features and optimizations

• dashboard: add query texts to TopN charts and table with smart truncation (!162)
• CLI: add markdown output and improve checkup UX (!188)
• CLI: embed checkup dictionary from API at build time (!179)
• add unprepare-db command and pg_stat_statements to prepare-db (!177)
• add databaseUrl to prepare-db --supabase JSON output (!175)
• add MCP tools for action items (!172)
• CLI: add Supabase mode and JSON output for prepare-db command (!173)
• H001: add decision tree recommendations for invalid indexes (!166)
• monitoring: Display version and build timestamp in Grafana Self-monitoring dashboard (!146)
• MCP: add create_issue tool for issue creation via MCP (!127)
• dashboards: unify panel titles and units across Grafana dashboards (!131)
• reporter: add index_definition to H001 invalid indexes report (!134)
• CLI: add express checkup command with direct PostgreSQL health checks + fix H004 and A003 (!115)
• Add new single-index panels for size, reads/hits (bytes), add 50 and 100 options for Top-N of table and index analysis (!110)
• prepare-db: add helper functions for generic plan collection, with optional HypoPG index; wrap each prepare-db step in begin/commit block; introduce "postgres_ai" schema (!117)
• Add JSON schemas for checkup report outputs + tests (!98)
• CLI: implement postgresai init to create DB role and grant permissions (!100)
• Add Postgres version to report data (!96)
• reporter: add database exclusion support (!95)
• Support Amazon Managed Prometheus (!167)
• adjust table&index dashboards: panel widths and bloat ordering (!143)
• Hourly monitoring reports improvements + new K008 check (!124)
• Daily JSON reports with hourly snapshots of pgss and ASH data (!97)
• ignore estimated bloat for relations < 1 MiB (!106)
• Embed index_pilot component (!102)

Fixes and optimizations

• support pg_stat_statements in extensions schema (Supabase) (!190)
• CLI: recognize --no-upload option, decouple --json from upload (!183)
• CLI: append Supabase project ref to pooler username (!176)
• use postgres_ai schema for pg_statistic + add --provider flag for Supabase (!174)
• deps: update gunicorn and requests to address security vulnerabilities (!159)
• CLI: use CLI version instead of stale .env tag (!153)
• pgai: resolve postgresai/cli export instead of package.json (!151)
• grafana: enable stacking for top-N index panels (!150)
• CLI: macOS compatibility, cleanup, and image tag handling (!147)
• CLI: mon clean now properly removes containers and volumes (!144)
• CLI: pass Grafana password directly to Docker during local-install (!140)
• docker: macOS compatibility for monitoring containers (!138)
• CLI: resolve --api-key option being ignored in mon local-install (!137)
• prepare-db: add SQL injection protection to explain_generic (!121)
• CLI: resolve SQL directory at runtime for bundled CLI (!133)
• CLI: pass api_url to UI for OAuth to ensure same backend is used (!129)
• clean up HTTP error messages for CLI commands (!123)
• replace Bun.serve with Node.js http module in auth-server (!122)
• Get true lock_timeout and statement_timeout (!105)
• CLI sslmode=prefer behavior, CI publish improvements, and schema fixes (!108)
• Add resource limits and rename self-monitoring components (!178)
• Reduce pgwatch log verbosity to error level (!185)

Refactoring

• migrate CLI from Node.js to Bun (!118)
• move auth-related commands under auth group (!119)
• improve CLI commands and authentication flow (!113)
• Restructure README with SaaS-first onboarding flow (!192)
• modernize README with AI-native positioning, demos, and Claude Code plugin /pgai (!187)

Contributors

Thank you to all who contributed to this release!

• Thomas Cave
• Dmitry Fomin
• Denis Morozov
• Dementii Priadko
• Nikolay Samokhvalov
• Bogdan Tsechoev

Ideas and proposed changes are accepted on both GitLab and GitHub:

• GitHub: https://github.com/postgres-ai/postgresai
• GitLab: https://gitlab.com/postgres-ai/postgresai

Getting Started

• SaaS (recommended): sign up at console.postgres.ai and connect your database in minutes.
• Self-hosted: install the CLI with npm install -g postgresai and run postgresai checkup <connection-string> for instant health checks, or postgresai mon local-install --demo for the full monitoring stack.

0.13

postgres_ai monitoring v0.13 - release notes

What's new

Kubernetes support (Helm charts)

Complete Kubernetes deployment support via Helm charts, including: (!72)

• Full monitoring stack deployment (PGWatch, VictoriaMetrics, Grafana)
• CronJob-based reporter for automated health checks
• Configurable ingress with TLS support
• Persistent storage via StatefulSets
• Helm chart: postgres-ai-monitoring-0.13.tgz

New dashboard: "13. Lock contention"

New metric and dedicated dashboard for detailed lock contention analysis: (!82, !84, !86)

• Blocked and blocking process identification
• Lock modes and types visualization
• Affected tables and queries
• Wait duration and transaction time tracking
• "Database: All" filter option

OAuth support for Grafana

Added OAuth authentication support for Grafana with configurable providers, enabling SSO integration; allows authentication using PostgresAI account (limited to members of specific organization that owns monitoring instance) (!79)

Issue generation API

New issue_generation flag in report file API for automated issue creation workflows. (!69)

Dashboard improvements

• Dashboard 2 (Aggregated Query Analysis): Added 'per second' to titles and proper XXX/s units; added "Database: All" filter option (!88, !87)
• Dashboard 3 (Single Query Analysis): Show detailed wait events in Active Session History panel (!76)
• Dashboard 4 (Wait Sampling): Added "DB name: All" filter, now default selection (!78)
• Dashboard 12 (SLRU): Renamed title to '12. SLRU cache stats' for consistency (!89)

Performance improvements

• Reduced VictoriaMetrics load: Metrics now filter queries by current_database() to reduce cardinality and improve query performance (!80)

Fixes

• Reporter queries: Fixed and improved metric queries for better data reliability (!73)
• Database discovery: Made DB discovery source-agnostic for better compatibility (!70)
• H004 report: Now includes index_definition field (consistent with H002) (!71)

Code quality

• Added pgwatch_generated comment to all SQL queries for traceability (!75)
• Added checkTitle field to all report JSONs for better organization (!74)
• Comprehensive test suite for Postgres reporter (!77, !81)

0.12

Release Date: November 10, 2025
GitLab Issue: #48

Overview

Version 0.12.0 adds SLRU monitoring, multixact member space exhaustion detection, enhanced dashboard usability, and improved automated reporting for production Postgres databases.

New features

SLRU monitoring dashboard (!65)

New dedicated dashboard for monitoring Simple Least Recently Used (SLRU) caches through pg_stat_slru metrics. Provides visibility into CLOG, subtransaction cache, multixact offset and member cache performance. SLRU contention can cause severe performance degradation that is difficult to diagnose without proper monitoring.

MultiXact member space exhaustion (!66)

Added early warning metric for multixact member space exhaustion by monitoring pg_multixact/members directory size. Provides advance notice before emergency autovacuum triggers. Documentation updated with required permissions for RDS/Aurora and self-managed instances.

High-level troubleshooting metrics (!67)

Redesigned Dashboard 1 to use high-level system metrics instead of granular pg_stat_statements aggregations. Provides faster dashboard load times (2-3x improvement), more intuitive top-down troubleshooting workflow, and better alignment with Four Golden Signals methodology.

Enhanced unused indexes report (!64)

• Index definitions included for one-command UNDO operations
• Improved statistics age calculation using database uptime when stats_reset is NULL
• Enhanced metadata for safer index cleanup decisions

Other minor improvements

• Active Session History (Dashboard 4) legibility improvements
• Aggregated table statistics table on Dashboard 8
• Got rid of hard-coded inner passwords for sink-postgres

Bug fixes

• Corrected grant statements in documentation
• Multi-value tooltips on Dashboard 1 enable time-synchronized analysis across all metrics

Linked merge requests

• !68 — Dashboard improvements (shared tooltips, ASH)
• !67 — High-level metrics on Dashboard 1
• !66 — Multixact folder size monitoring
• !65 — SLRU metrics and dashboard
• !64 — Unused indexes report improvements

References

• GitLab Issue: https://gitlab.com/postgres-ai/postgres_ai/-/issues/48
• Repository: https://github.com/postgres-ai/postgres_ai / https://gitlab.com/postgres-ai/postgres_ai
• Live Demo: https://demo.postgres.ai

0.11

Major changes

Victoria Metrics integration (bbe4c8d)

Replaced standard Prometheus with Victoria Metrics for time-series data storage, delivering substantial performance and efficiency improvements:

• Better compression: Reduced storage footprint for long-term metric retention (from 2 GiB/day to >0.4 GiB/day/instance)
• Lower memory usage: More efficient resource utilization for large-scale deployments
• Enhanced performance: Faster query execution for dashboard rendering and analysis
• Full compatibility: Maintains complete Prometheus query language compatibility
• Increased capacity: Supports higher cardinality metrics without performance degradation

The migration is seamless with no changes required to existing Grafana dashboards or queries.

Optimized query analysis

• Improved pg_stat_statements metric collection for more accurate and useful query performance data:

  • Query-level aggregation: Metrics now aggregate by queryid across all users and databases
  • Simplified analysis: Removed per-user ranking in favor of database-wide query patterns
  • Consistent metrics: Unified view of query performance regardless of executing user
  • Better trending: More reliable historical data for query performance analysis

• Added stats_reset metric which allows to check the last time statistics were reset

New metrics (6a76444)

Added StatIO metric for indexes

Made retention period 2 weeks instead of 8 days (72c65cd)

Bug Fixes

• Fixed bug of redundant/unused indexes metrics by adding a clause of granting pg_index to monitoring user (e59fbbd)
• Fixed incorrect display of blk_write_time on the 1st dashboard (b958fa0, 444343e)
• Fixed a bug of not filtering top_k for aggregated table stats (6a76444)
• statement_timeout_seconds is now set to 15 seconds for all metrics (6a76444)