postgresai 0.17.0-rc.1 → 0.17.0-rc.3

package/README.md

@@ -250,7 +250,7 @@ postgresai mon health [--wait <sec>]  # Check monitoring services health
 
 When `--instance-id <uuid>` (or `PGAI_INSTANCE_ID`) is set, `local-install` forwards the id to the platform, which **adopts** the already-provisioned monitoring instance instead of self-registering a duplicate under an auto-created `postgres-ai-monitoring` project. The CLI then persists the adopted instance's real project to `.pgwatch-config`, so checkup reports upload alongside the rest of that instance's health data. Adoption is awaited (with one automatic retry); if it fails, the CLI warns and reports fall back to the default project until you re-run `local-install`. Without the flag, the legacy self-registration path is byte-for-byte unchanged.
 
-`local-install` writes `.env` in the monitoring directory. It preserves existing `REPLICATOR_PASSWORD` and `VM_AUTH_*` values or generates new random ones when missing; `VM_AUTH_USERNAME` defaults to `vmauth` when absent. The replication password is used by the demo PostgreSQL standby replication user, and the VM auth credentials are required before Docker Compose can provision Grafana datasources. If you run `docker compose` directly or maintain `.env` yourself, set both VM auth values before upgrading. For rotation, run `VM_AUTH_PASSWORD="$(openssl rand -base64 18)" ./scripts/rotate-vm-auth.sh` from the monitoring directory so `.env`, `sink-prometheus`, and `grafana` update together.
+`local-install` writes `.env` in the monitoring directory. It preserves existing `REPLICATOR_PASSWORD`, `VM_AUTH_*` and the VictoriaMetrics admin-endpoint keys (`VM_DELETE_AUTH_KEY`, `VM_SNAPSHOT_AUTH_KEY`, `VM_FORCE_MERGE_AUTH_KEY`, `VM_PPROF_AUTH_KEY`, added in 0.17) or generates new random ones when missing. The admin keys live on the `sink-prometheus` command line, so `mon update` and `mon update-config` also recreate that container to apply them; `mon restart` (`docker compose restart`) does not; `VM_AUTH_USERNAME` defaults to `vmauth` when absent. The replication password is used by the demo PostgreSQL standby replication user, and the VM auth credentials are required before Docker Compose can provision Grafana datasources. If you run `docker compose` directly or maintain `.env` yourself, set both VM auth values before upgrading. For rotation, run `VM_AUTH_PASSWORD="$(openssl rand -base64 18)" ./scripts/rotate-vm-auth.sh` from the monitoring directory so `.env`, `sink-prometheus`, and `grafana` update together.
 
 #### Monitoring target databases (`mon targets` subgroup)
 ```bash
@@ -271,6 +271,35 @@ postgresai mon check                          # System readiness check
 postgresai mon shell <service>                # Open shell to monitoring service
 ```
 
+### PromQL queries (`promql`)
+
+Ask a monitoring instance a PromQL question through the platform. The platform
+never connects to the instance: it queues the query as a job, the instance picks
+it up on its next poll, runs it against its own metric store, and posts the
+answer back.
+
+```bash
+# instant query
+pgai promql 'up' --instance <instance-uuid>
+
+# range query
+pgai promql 'sum(rate(pgwatch_db_stats_xact_commit[5m]))' \
+  --instance <instance-uuid> \
+  --range --start 2026-09-21T00:00:00Z --end 2026-09-21T01:00:00Z --step 60
+
+# on the box itself, --instance is read from .pgwatch-config
+pgai promql 'up'
+```
+
+`--at <time>` evaluates an instant query at a given moment (ignored with
+`--range`). `--json` prints every point instead of the first and last per series.
+The wait is sized from the instance's poll pacing; `--timeout` overrides it. A
+result too large for the byte budget is trimmed and flagged `truncated`.
+
+Requires platform-all !809
+(https://gitlab.com/postgres-ai/platform-all/-/merge_requests/809); until it is
+deployed the command returns a PGRST202 404.
+
 ### MCP server (`mcp` group)
 
 ```bash
@@ -299,10 +328,10 @@ required** — the server will not assume an organization. Call `orgs_list` (or
 run `pgai orgs`) to discover the available ids.
 
 Tools exposed:
-- `list_issues`: returns the same JSON as `postgresai issues list` (args: `{ org_id, status?, hidden_only?, limit?, offset?, debug? }`).
+- `list_issues`: returns the same JSON as `postgresai issues list` (args: `{ org_id, status?, hidden_only?, limit?, offset?, debug? }`). Unlike the CLI, omitting `status` returns open and closed issues; pass `status: "open"` to match the CLI default.
 - `view_issue`: view a single issue with its comments (args: `{ issue_id, org_id, debug? }`).
-- `create_issue`: create a new issue (args: `{ title, description?, org_id, attachments?, debug? }`).
-- `update_issue`: update title/description/status/labels (args: `{ issue_id, org_id, title?, description?, status?, labels?, attachments?, debug? }`).
+- `create_issue`: create a new issue (args: `{ title, description?, org_id, project_id?, labels?, attachments?, is_hidden?, debug? }`).
+- `update_issue`: update title/description/status/labels/is_hidden (args: `{ issue_id, org_id, title?, description?, status?, labels?, attachments?, is_hidden?, debug? }`).
 - `post_issue_comment`: post a comment (args: `{ issue_id, org_id, content?, parent_comment_id?, attachments?, debug? }`).
 - `update_issue_comment`: update an existing comment (args: `{ comment_id, org_id, content?, attachments?, debug? }`).
 - `upload_file`: upload a local file and return the storage URL plus a ready-to-paste markdown link (args: `{ path, org_id, debug? }`).
@@ -350,11 +379,14 @@ sensitive.
 ### Issues management (`issues` group)
 
 ```bash
-postgresai issues list                                       # List issues (shows: id, title, status, created_at; is_hidden only when set)
+postgresai issues list                                       # List OPEN issues (shows: id, title, status, created_at; is_hidden only when set)
+postgresai issues list --status closed                       # Only closed issues (--status all for both)
 postgresai issues list --hidden-only                         # Only hidden issues (PostgresAI staff)
 postgresai issues view <issueId>                             # View issue details and comments
-postgresai issues create --org-id <id> --title <t>           # Create a new issue
+postgresai issues create --org-id <id> <title>               # Create a new issue
+postgresai issues create --org-id <id> <title> --hidden      # Create a hidden issue (PostgresAI staff)
 postgresai issues update <issueId> [--title ... --status ...]# Update an existing issue
+postgresai issues update <issueId> --hidden|--no-hidden      # Hide / unhide an issue (PostgresAI staff)
 postgresai issues post-comment <issueId> <content>           # Post a comment to an issue
 postgresai issues update-comment <commentId> <content>       # Update an existing comment
 postgresai issues files upload <path>                        # Upload a file, print URL + markdown
@@ -370,7 +402,11 @@ postgresai issues files download <url> [-o <path>]           # Download a file
 Hidden issues are staff-internal. `issues list` and `issues view` mark them
 with `is_hidden: true`; the key is omitted entirely otherwise, so ordinary
 issues look exactly as they always have. `--hidden-only` lists just the hidden
-ones, filtered server-side.
+ones, filtered server-side. `issues create --hidden` creates one, and
+`issues update --hidden` / `--no-hidden` hides or unhides an existing issue
+(MCP: `is_hidden` on `create_issue` / `update_issue`). The CLI does no staff
+check of its own: the platform refuses a visibility change for a non-staff
+credential with a plain error, and the CLI prints it and exits non-zero.
 
 Staff access is granted per credential, not per person, and a credential that
 does not qualify simply sees nothing — `--hidden-only` returns an empty list