postgresai 0.18.0-dev.1 → 0.18.0-dev.10
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 +66 -15
- package/dist/bin/postgres-ai.js +10127 -12195
- package/dist/sql/03.permissions.sql +28 -16
- package/dist/sql/uninit/01.helpers.sql +3 -0
- package/dist/sql/uninit/02.permissions.sql +76 -20
- package/dist/sql/uninit/03.role.sql +3 -0
- package/package.json +1 -1
- package/sql/03.permissions.sql +28 -16
- package/sql/uninit/01.helpers.sql +3 -0
- package/sql/uninit/02.permissions.sql +76 -20
- package/sql/uninit/03.role.sql +3 -0
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,
|
|
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
|
|
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` |
|
|
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
|
|
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
|
|
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).
|
|
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.
|
|
@@ -400,15 +421,29 @@ required tool argument instead of falling back to a stored default.
|
|
|
400
421
|
### DBLab in PostgresAI cloud: `pgai dblab deploy`
|
|
401
422
|
|
|
402
423
|
```bash
|
|
403
|
-
PGPASSWORD=<password> pgai dblab deploy 'postgresql://<user>@<host>:5432/<db>'
|
|
424
|
+
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)
|
|
408
|
-
|
|
428
|
+
plus `--size S|M|L` (default `S`), `--disk <GiB>` (default 50), `--cloud hetzner|aws|gcp` and
|
|
429
|
+
`--provider generic|rds|supabase` (default: detected; `self-managed` remains an alias of `generic`). `--name` defaults to
|
|
430
|
+
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
|
|
|
434
|
+
The server gets no SSH keys of yours: clones are reached through an SSH tunnel as `dblab-tunnel`, a user that can only
|
|
435
|
+
forward to the clone ports. Allow your key after the deploy (organization admins; it applies within a minute):
|
|
436
|
+
|
|
437
|
+
```bash
|
|
438
|
+
pgai dblab access add <id or name> --public-key-file ~/.ssh/id_ed25519.pub # or --ssh-key <org key name or id>
|
|
439
|
+
pgai dblab access list <id or name> # the allowed keys, and the tunnel command
|
|
440
|
+
pgai dblab access remove <id or name> --ssh-key <org key name or id>
|
|
441
|
+
ssh -N -L 6000:127.0.0.1:6000 dblab-tunnel@<server ip> # then: psql "host=127.0.0.1 port=6000 ..."
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
`--ssh-key` on `pgai dblab deploy` puts organization keys on the server itself, only in an environment that allows
|
|
445
|
+
that.
|
|
446
|
+
|
|
412
447
|
### Start monitoring
|
|
413
448
|
|
|
414
449
|
Start monitoring with demo database:
|
|
@@ -555,7 +590,7 @@ Tools exposed:
|
|
|
555
590
|
- `update_issue_comment`: update an existing comment (args: `{ comment_id, org_id, content?, attachments?, debug? }`).
|
|
556
591
|
- `upload_file`: upload a local file and return the storage URL plus a ready-to-paste markdown link (args: `{ path, org_id, debug? }`).
|
|
557
592
|
- `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.
|
|
593
|
+
- `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
594
|
|
|
560
595
|
#### `attachments` parameter (issue/comment tools)
|
|
561
596
|
|
|
@@ -688,6 +723,22 @@ postgresai show-key # Show stored key (masked)
|
|
|
688
723
|
postgresai remove-key # Remove stored key
|
|
689
724
|
```
|
|
690
725
|
|
|
726
|
+
### Create an organization
|
|
727
|
+
|
|
728
|
+
```bash
|
|
729
|
+
pgai auth login # choose "All my organizations (global token)"
|
|
730
|
+
pgai orgs create --name "My team" --alias my-team --json
|
|
731
|
+
```
|
|
732
|
+
|
|
733
|
+
- Choose the name explicitly. An agent should ask the user to approve its proposed name first.
|
|
734
|
+
- At login, choose "All my organizations (global token)". A token for one organization cannot create organizations.
|
|
735
|
+
- This works before you belong to any organization. The consent page then offers only the global token.
|
|
736
|
+
- 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`.
|
|
737
|
+
- Organization and instance tokens cannot create organizations. The CLI refuses them before sending anything.
|
|
738
|
+
- 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.
|
|
739
|
+
- 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.
|
|
740
|
+
- Requires the Platform change https://gitlab.com/postgres-ai/platform-all/-/merge_requests/1157 to be deployed.
|
|
741
|
+
|
|
691
742
|
## Configuration
|
|
692
743
|
|
|
693
744
|
The CLI stores configuration in `~/.config/postgresai/config.json` including:
|