postgresai 0.18.0-dev.7 → 0.18.0-dev.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -196,10 +196,7 @@ pgai mon deploy 'postgresql://postgres:<password>@<host>:5432/postgres'
196
196
  ```
197
197
 
198
198
  It signs you in if needed, creates the `postgres_ai_mon` role (with an admin URL; otherwise it
199
- prints the SQL), provisions monitoring in PostgresAI Cloud, runs the express checkup (the checks
200
- of `pgai checkup`, as `postgres_ai_mon`) while the box starts and prints its findings (in JSON:
201
- `checkup`; skipped where PostgresAI keeps the role's password: no `checkup` key, no first report),
202
- waits, and prints two links: the project's Health Matrix in the console
199
+ prints the SQL), provisions monitoring in PostgresAI Cloud, waits, and prints two links: the project's Health Matrix in the console
203
200
  (`<console>/<org>/projects/<project>/health`, the next step) and Grafana, which signs you in
204
201
  with your PostgresAI account (`https://<box>/login/generic_oauth?redirectTo=%2F`). Safe to re-run; a `--clickhouse-key` given on a
205
202
  re-run is checked, and a rejected one is `action_required`. For ClickHouse Managed Postgres add `--clickhouse-key <key-id>:<key-secret>`
@@ -208,6 +205,29 @@ machine instead. When stdout is not a terminal the result is JSON with `status`,
208
205
  `dashboard_url` and `next`. Then: `pgai mon instances list`, `pgai mon instances watch <id-or-name>`, `pgai mon instances delete <id-or-name>`,
209
206
  and `pgai mon instances set <id-or-name> --vcpus <n>` to add or change the database server's vCPUs later (an org admin; AAS starts within a minute).
210
207
 
208
+ To use a direct PostgreSQL connection, explicitly select `--provider generic`:
209
+
210
+ ```bash
211
+ pgai mon deploy "$DATABASE_URL" --provider generic --org <alias> --json --no-wait
212
+ ```
213
+
214
+ This is the existing `--provider self-managed` path under a clearer name; both spellings work,
215
+ and the result's `provider` remains `self-managed` for compatibility. It works with any reachable
216
+ PostgreSQL endpoint where the supplied user can create the monitoring role and grant privileges.
217
+ Use a direct endpoint, not a pooler.
218
+
219
+ The endpoint must be reachable from this machine, which prepares the database, and from
220
+ PostgresAI. Before provisioning, PostgresAI tests the connection from its platform, whose
221
+ address is not published, so the port must accept connections from the internet at that point.
222
+ After provisioning, the monitoring server connects from its own IP address, shown on its page in
223
+ the Console (Monitoring, then the instance). A database that must stay behind an IP allowlist
224
+ needs AWS PrivateLink (RDS) or self-hosted monitoring (`--self-hosted`).
225
+
226
+ Without `--provider`, RDS and Supabase hostnames still go to their console integration.
227
+ `generic` does not configure AWS PrivateLink, open a firewall, or remove TLS, permission, or
228
+ payment checks. A private endpoint needs a network path, or monitoring hosted in that network
229
+ (`--self-hosted`).
230
+
211
231
  `pgai mon deploy` and `pgai dblab deploy` share their options and results: the database URL as the
212
232
  argument (or `--db-url`), `--name` (default: from the database), `--location` (a Hetzner location;
213
233
  default: any with capacity), `--wait <minutes>` / `--no-wait`, `--yes` (never prompt), `--json`, the
@@ -229,10 +249,11 @@ terminal, or with `--json`, it only points to `pgai mon deploy`.
229
249
 
230
250
  | Option | |
231
251
  |---|---|
232
- | `--provider <provider>` | `clickhouse`, `rds`, `supabase` or `self-managed`; default: detected from the host |
252
+ | `--provider <provider>` | `generic` (direct PostgreSQL; `self-managed` remains an alias), `clickhouse`, `rds` or `supabase`; default: detected from the host |
233
253
  | `--clickhouse-key <key-id>:<key-secret>` | ClickHouse Cloud API key, for CPU, memory and disk |
234
254
  | `--self-hosted` | run the stack on this machine (`mon local-install`) instead of PostgresAI Cloud |
235
- | `--reset-password` | `postgres_ai_mon` exists and its password is lost: set a new one (see below) |
255
+ | `--reset-password` | the monitoring role exists and its password is lost: set a new one (see below) |
256
+ | `--monitoring-user <name>` | the monitoring role to create or use (default `postgres_ai_mon`; at most 63 bytes; MCP: `monitoring_user`). A custom role always carries its own password: PostgresAI keeps only `postgres_ai_mon`'s, so creating or resetting a custom role needs `PGAI_MON_PASSWORD` (an agent passes the role's URL). A name with `'`, `$`, `%`, backslash or a control character is refused, and so is a role that is a superuser or has `CREATEDB`, `CREATEROLE`, `REPLICATION` or `BYPASSRLS`, is a member of a role other than `pg_monitor`, `pg_read_all_stats`, `pg_read_all_settings` and `pg_stat_scan_tables` (directly or through other roles, also through `pg_monitor` itself), owns objects, has grants in another database of the server, or has grants in the database beyond `CONNECT`, `USAGE` on schemas other than `pg_toast`, `SELECT` outside `pg_catalog` and `pg_toast`, and the grants pgai makes, or holds any grant `WITH GRANT OPTION` or a membership `WITH ADMIN OPTION`. So a custom role used for databases on one server is refused for the second one. `SELECT` on application tables and views is allowed, including a view over `pg_authid`: what a role may read through views is the owner's choice. Ignored for a host handed to the Console |
236
257
  | `--db-url <url>` | the database URL, instead of the argument |
237
258
  | `--name <name>` | the instance's name (default: `host[:port]/database`); ignored, with a note, for a database already monitored |
238
259
  | `--location <location>` | Hetzner location `fsn1`, `nbg1` or `hel1` (default: any with capacity) |
@@ -254,8 +275,8 @@ and asks you to re-run with `--yes` to accept it.
254
275
  | `PGSSLMODE` | the `sslmode` for a URL without one (`sslmode` in the URL wins, as in libpq) |
255
276
  | `CLICKHOUSE_KEY_ID` + `CLICKHOUSE_KEY_SECRET` | instead of `--clickhouse-key`; read for ClickHouse hosts only |
256
277
 
257
- `postgres_ai_mon` is one role for the whole server, so `mon deploy` never changes the password of an
258
- existing one. If the role exists and you do not have its password (a deployment after
278
+ The monitoring role (`postgres_ai_mon`, or `--monitoring-user`) is one role for the whole server, so
279
+ `mon deploy` never changes the password of an existing one. If the role exists and you do not have its password (a deployment after
259
280
  `pgai mon instances delete`, say), `pgai mon deploy <admin-url> --reset-password` sets a new one
260
281
  (`PGAI_MON_PASSWORD`, else generated). It is refused while another database on the same server (the same host name, in this
261
282
  organization) is monitored with the role, while a box's server is not known (it was created before
@@ -264,7 +285,7 @@ already monitored. After the price is accepted, the run takes the platform's loc
264
285
  name and port, in this organization) until the box is requested. A second `--reset-password` for
265
286
  the same server exits 3 meanwhile. A run that stopped, or whose box request got no answer, frees the
266
287
  server 15 minutes after it took the lock. A platform without the lock answers "set
267
- `PGAI_MON_PASSWORD`" instead. Anything else that logs in as `postgres_ai_mon` (another organization,
288
+ `PGAI_MON_PASSWORD`" instead. Anything else that logs in as the role (another organization,
268
289
  another host name for the same server, a deploy without `--reset-password` running at the same
269
290
  time) needs the new password.
270
291
 
@@ -272,8 +293,7 @@ Another database on a server PostgresAI already monitors for the organization ne
272
293
  `sslmode=require` or `verify-*` in the URL, the role keeps its password, the box's URL carries
273
294
  none, and PostgresAI fills in the one it kept from the first `mon deploy` (only over TLS, each query
274
295
  parameter once, and only while a box on that server is not deleted, being deleted, or failed to
275
- delete). The express checkup is skipped then: it runs only as `postgres_ai_mon`, never as the
276
- admin. The full checkup follows on the box. On a server without TLS the kept password cannot be
296
+ delete). On a server without TLS the kept password cannot be
277
297
  used: set `PGAI_MON_PASSWORD`, or turn TLS on; if nobody has the password, delete the server's
278
298
  other instances, then `--reset-password` with `PGAI_MON_PASSWORD` set to a new one, and deploy
279
299
  them again with it (`mon deploy` names them).
@@ -383,6 +403,7 @@ pgai reports list --org-id 5225 # by numeric id — same on every org-scope
383
403
  PGAI_ORG=acme pgai checkup ... # for scripts and agents
384
404
 
385
405
  pgai orgs # which organizations can this token reach?
406
+ pgai orgs create --name "My team" --alias my-team --json # global user token required
386
407
  ```
387
408
 
388
409
  `--org` always means an alias and `--org-id` always means a numeric id.
@@ -404,8 +425,9 @@ PGPASSWORD=<password> pgai dblab deploy 'postgresql://<user>@<host>:5432/<db>' -
404
425
  ```
405
426
 
406
427
  The same options as `pgai mon deploy` (`--db-url`, `--name`, `--location`, `--wait`, `--no-wait`, `--yes`, `--json`),
407
- plus `--size S|M|L` (default `S`), `--disk <GiB>` (default 50) and `--ssh-key` (required: one of the organization's
408
- SSH keys, for reaching the server and its clones). `--name` defaults to the database's name; `--wait` to 120 minutes.
428
+ plus `--size S|M|L` (default `S`), `--disk <GiB>` (default 50), `--ssh-key` (required: one of the organization's
429
+ SSH keys, for reaching the server and its clones) and `--provider generic|rds|supabase` (default: detected; `self-managed`
430
+ remains an alias of `generic`). `--name` defaults to the database's name; `--wait` to 120 minutes.
409
431
  It shows the estimated monthly cost before asking; with no payment method it stops with the billing page (exit 3).
410
432
  `pgai dblab instances list | watch (status) | delete` take an id or a name.
411
433
 
@@ -555,7 +577,7 @@ Tools exposed:
555
577
  - `update_issue_comment`: update an existing comment (args: `{ comment_id, org_id, content?, attachments?, debug? }`).
556
578
  - `upload_file`: upload a local file and return the storage URL plus a ready-to-paste markdown link (args: `{ path, org_id, debug? }`).
557
579
  - `download_file`: download a file from storage (args: `{ url, org_id, output_path?, debug? }`).
558
- - `deploy_monitoring`: `pgai mon deploy` as a tool (args: `{ database_url, org_id, provider?, clickhouse_key?, yes?, coupon?, debug? }`). Returns the same JSON (`status`: `ready`, `in_progress`, `deleting`, `deleted`, `inactive`, `action_required` or `failed`; `health_url`; `dashboard_url`; `next`). For a billed box, the tool first returns the price with `action_required`; an explicit call with `yes: true` accepts it. `coupon` supplies a promotion code. It does not wait for the monitoring box: call it again to see the status. `database_url` must carry its password, and only the query parameters `sslmode`, `channel_binding`, `application_name` (and `password`); `PGAI_MON_PASSWORD`, `PGPASSWORD` and `CLICKHOUSE_KEY_ID` + `CLICKHOUSE_KEY_SECRET` of the server process are not used, a TLS failure is not retried in plaintext, and `--self-hosted` is CLI-only. For another database on a server PostgresAI already monitors for the organization, an admin `database_url` with `sslmode=require` (or `verify-*`) is enough: PostgresAI fills in the password of `postgres_ai_mon` it keeps.
580
+ - `deploy_monitoring`: `pgai mon deploy` as a tool (args: `{ database_url, org_id, provider?, clickhouse_key?, yes?, coupon?, monitoring_user?, debug? }`). Returns the same JSON (`status`: `ready`, `in_progress`, `deleting`, `deleted`, `inactive`, `action_required` or `failed`; `health_url`; `dashboard_url`; `next`). For a billed box, the tool first returns the price with `action_required`; an explicit call with `yes: true` accepts it. `coupon` supplies a promotion code. It does not wait for the monitoring box: call it again to see the status. `database_url` must carry its password, and only the query parameters `sslmode`, `channel_binding`, `application_name` (and `password`); `PGAI_MON_PASSWORD`, `PGPASSWORD` and `CLICKHOUSE_KEY_ID` + `CLICKHOUSE_KEY_SECRET` of the server process are not used, a TLS failure is not retried in plaintext, and `--self-hosted` is CLI-only. For another database on a server PostgresAI already monitors for the organization, an admin `database_url` with `sslmode=require` (or `verify-*`) is enough: PostgresAI fills in the password of `postgres_ai_mon` it keeps.
559
581
 
560
582
  #### `attachments` parameter (issue/comment tools)
561
583
 
@@ -688,6 +710,22 @@ postgresai show-key # Show stored key (masked)
688
710
  postgresai remove-key # Remove stored key
689
711
  ```
690
712
 
713
+ ### Create an organization
714
+
715
+ ```bash
716
+ pgai auth login # choose "All my organizations (global token)"
717
+ pgai orgs create --name "My team" --alias my-team --json
718
+ ```
719
+
720
+ - Choose the name explicitly. An agent should ask the user to approve its proposed name first.
721
+ - At login, choose "All my organizations (global token)". A token for one organization cannot create organizations.
722
+ - This works before you belong to any organization. The consent page then offers only the global token.
723
+ - Alternatively, create a global token at https://console.postgres.ai/profile/global-tokens, then run `pgai auth --set-key <token>` or set `PGAI_API_KEY`.
724
+ - Organization and instance tokens cannot create organizations. The CLI refuses them before sending anything.
725
+ - The alias is normalized like the Console does it: lowercase, and spaces and reserved characters become `-`. Omit `--alias` to derive it from the name. It must be ASCII because `--org` sends it as a header.
726
+ - You become the owner and an Admin member. No organization selection is sent, and your saved configuration does not change. Use the returned alias with `--org` afterwards.
727
+ - Requires the Platform change https://gitlab.com/postgres-ai/platform-all/-/merge_requests/1157 to be deployed.
728
+
691
729
  ## Configuration
692
730
 
693
731
  The CLI stores configuration in `~/.config/postgresai/config.json` including: