postgresai 0.17.0-rc.5 → 0.18.0-beta.1
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 +289 -1
- package/dist/bin/postgres-ai.js +19231 -12259
- package/dist/sql/01.role.sql +3 -4
- package/dist/sql/02.extensions.sql +1 -1
- package/dist/sql/03.permissions.sql +139 -27
- package/dist/sql/04.optional_rds.sql +2 -1
- package/dist/sql/06.helpers.sql +42 -8
- package/dist/sql/uninit/01.helpers.sql +3 -0
- package/dist/sql/uninit/02.permissions.sql +88 -21
- package/dist/sql/uninit/03.role.sql +8 -5
- package/package.json +2 -2
- package/sql/01.role.sql +3 -4
- package/sql/02.extensions.sql +1 -1
- package/sql/03.permissions.sql +139 -27
- package/sql/04.optional_rds.sql +2 -1
- package/sql/06.helpers.sql +42 -8
- package/sql/uninit/01.helpers.sql +3 -0
- package/sql/uninit/02.permissions.sql +88 -21
- package/sql/uninit/03.role.sql +8 -5
- package/dist/sql/sql/01.role.sql +0 -16
- package/dist/sql/sql/02.extensions.sql +0 -8
- package/dist/sql/sql/03.permissions.sql +0 -86
- package/dist/sql/sql/04.optional_rds.sql +0 -6
- package/dist/sql/sql/05.optional_self_managed.sql +0 -8
- package/dist/sql/sql/06.helpers.sql +0 -317
- package/dist/sql/sql/uninit/01.helpers.sql +0 -5
- package/dist/sql/sql/uninit/02.permissions.sql +0 -30
- package/dist/sql/sql/uninit/03.role.sql +0 -27
package/README.md
CHANGED
|
@@ -76,6 +76,8 @@ Password input options (in priority order):
|
|
|
76
76
|
- `PGAI_MON_PASSWORD` environment variable
|
|
77
77
|
- if not provided: a strong password is generated automatically
|
|
78
78
|
|
|
79
|
+
Monitoring passwords must use printable ASCII characters; non-ASCII passwords are rejected until SASLprep normalization is supported. Role creation and password resets send a SCRAM-SHA-256 verifier instead of the cleartext password, including when the server uses `password_encryption=md5`. Printed SQL redacts the verifier as well. Server statement logging can still record the verifier; treat it as sensitive.
|
|
80
|
+
|
|
79
81
|
By default, the generated password is printed **only in interactive (TTY) mode**. In non-interactive mode, you must either provide the password explicitly, or opt-in to printing it:
|
|
80
82
|
- `--print-password` (dangerous in CI logs)
|
|
81
83
|
|
|
@@ -125,6 +127,52 @@ Notes:
|
|
|
125
127
|
- All standard options work with Supabase mode (`--verify`, `--print-sql`, `--skip-optional-permissions`, etc.)
|
|
126
128
|
- When using `--verify`, the tool checks if all required setup is in place
|
|
127
129
|
|
|
130
|
+
### ClickHouse Managed Postgres
|
|
131
|
+
|
|
132
|
+
Hosts ending in `.pg.clickhouse.cloud` are auto-detected; `--provider clickhouse` forces it.
|
|
133
|
+
The plan is the same superuser plan as self-managed Postgres (`--print-sql` shows it).
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
npx postgresai prepare-db 'postgres://postgres:...@xxx.pg.clickhouse.cloud:5432/postgres?channel_binding=require'
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Before any grant runs, one `-- scope:` line lists exactly what the run grants the
|
|
140
|
+
monitoring role, derived from the steps about to run (so it shrinks under `--skip-optional-permissions`
|
|
141
|
+
and is not printed on `--reset-password`, which grants nothing). With `--json` it goes to stderr.
|
|
142
|
+
|
|
143
|
+
For `prepare-db`, `channel_binding=require` in a URI or conninfo string enables SCRAM-SHA-256-PLUS when the server
|
|
144
|
+
offers it, disables the plaintext retry that `sslmode=prefer` would otherwise do, and is rejected
|
|
145
|
+
together with `sslmode=disable`. The mechanism actually negotiated is not enforced by the driver.
|
|
146
|
+
|
|
147
|
+
The collector cannot do channel binding. `mon targets add`, `mon local-install --db-url`, and
|
|
148
|
+
`pgai mon deploy` remove `channel_binding` from the saved/box URL. With `require`, they refuse
|
|
149
|
+
`sslmode=disable` or `allow`; keep `verify-full` with a warning; and upgrade `require`, `prefer`,
|
|
150
|
+
`verify-ca` or unset to `verify-full` after testing certificate and hostname verification with
|
|
151
|
+
Node's default trust store (or the CA file in `sslrootcert`). Authentication or other errors after
|
|
152
|
+
a verified TLS handshake do not block the upgrade. If verification fails, provide
|
|
153
|
+
`sslrootcert=<CA file>` with `sslmode=verify-full`, or explicitly accept the downgrade by removing
|
|
154
|
+
`channel_binding=require`. Successful upgrades print the collector warning and
|
|
155
|
+
`upgraded to sslmode=verify-full`. `channel_binding=prefer` or `disable` is removed with a note.
|
|
156
|
+
|
|
157
|
+
### ClickHouse Cloud host metrics
|
|
158
|
+
|
|
159
|
+
For a ClickHouse Managed Postgres target, `mon local-install --db-url` and `mon targets add` also set up
|
|
160
|
+
host metrics (CPU, memory, disk, I/O) from the ClickHouse Cloud Prometheus endpoint when these are set:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
export CLICKHOUSE_ORG_ID='<org-id>' CLICKHOUSE_KEY_ID='<key-id>' CLICKHOUSE_KEY_SECRET='<key-secret>'
|
|
164
|
+
npx postgresai mon local-install --db-url 'postgres://postgres_ai_mon:...@xxx.pg.clickhouse.cloud:5432/postgres?sslmode=require'
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Use an organization API key with the **Basic Service API Reader** role: it is the least privilege that
|
|
168
|
+
works (it can list Postgres services and read `/prometheus`, and cannot change anything or create keys).
|
|
169
|
+
The CLI does not need an Admin key.
|
|
170
|
+
|
|
171
|
+
The key secret is stored in plaintext in `host-metrics/clickhouse-<name>.secret` in the monitoring
|
|
172
|
+
project directory (file 0600, directory 0700), because VictoriaMetrics reads it from a file for basic
|
|
173
|
+
auth. It is never printed or logged. `mon targets remove <name>` deletes it. To rotate the key, re-run
|
|
174
|
+
`mon targets add` with the new key.
|
|
175
|
+
|
|
128
176
|
### Verify and password reset
|
|
129
177
|
|
|
130
178
|
Verify that everything is configured as expected (no changes):
|
|
@@ -141,6 +189,197 @@ npx postgresai prepare-db postgresql://admin@host:5432/dbname --reset-password -
|
|
|
141
189
|
|
|
142
190
|
## Quick start
|
|
143
191
|
|
|
192
|
+
### One command: `pgai mon deploy`
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
pgai mon deploy 'postgresql://postgres:<password>@<host>:5432/postgres'
|
|
196
|
+
```
|
|
197
|
+
|
|
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, waits, and prints two links: the project's Health Matrix in the console
|
|
200
|
+
(`<console>/<org>/projects/<project>/health`, the next step) and Grafana, which signs you in
|
|
201
|
+
with your PostgresAI account (`https://<box>/login/generic_oauth?redirectTo=%2F`). Safe to re-run; a `--clickhouse-key` given on a
|
|
202
|
+
re-run is checked, and a rejected one is `action_required`. For ClickHouse Managed Postgres add `--clickhouse-key <key-id>:<key-secret>`
|
|
203
|
+
(a Basic Service API Reader key) for CPU, memory and disk. `--self-hosted` runs the stack on this
|
|
204
|
+
machine instead. When stdout is not a terminal the result is JSON with `status`, `health_url`,
|
|
205
|
+
`dashboard_url` and `next`. Then: `pgai mon instances list`, `pgai mon instances watch <id-or-name>`, `pgai mon instances delete <id-or-name>`,
|
|
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).
|
|
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. The monitoring
|
|
220
|
+
box connects from its own static IP. When PostgresAI can't reach the database the way an IP
|
|
221
|
+
allowlist refuses (a timeout, a refused connection, no `pg_hba.conf` entry), deploy reserves the
|
|
222
|
+
box's IP before the box exists and stops at it: at a terminal it shows the IP and waits (Enter
|
|
223
|
+
continues, `s` stops); elsewhere it exits 3 with `"step":"allow_ip"` and `ip`, `cidr`, `host`,
|
|
224
|
+
`port`, `reserved_until`. Allow the IP on the database, then run `pgai mon deploy <url> --yes
|
|
225
|
+
--ip-allowed` to create the box with it. `--ip-first` asks for the IP first even when PostgresAI
|
|
226
|
+
can reach the database. A re-run never reserves a second IP; the IP is held 7 days and stays the
|
|
227
|
+
box's for its life. If the box still can't connect, it waits for up to 90 minutes, then is removed
|
|
228
|
+
and its IP kept: allow it, and run with `--ip-allowed` again. RDS can also use AWS PrivateLink,
|
|
229
|
+
and any database self-hosted monitoring (`--self-hosted`).
|
|
230
|
+
|
|
231
|
+
Without `--provider`, RDS hostnames still go to their console integration, and Supabase hostnames to the Supabase consent flow (`pgai mon deploy` for Supabase).
|
|
232
|
+
|
|
233
|
+
A Supabase project needs no URL at all: `pgai mon deploy --provider supabase` connects the Supabase organization
|
|
234
|
+
if needed and lists its projects. At a terminal you pick one; agents and scripts pass
|
|
235
|
+
`--supabase-project <name or project ID>`. Without either, with `--yes`, or not at a terminal, it stops (exit 3) with the list
|
|
236
|
+
in the JSON result (`projects`, each with `selectable` and `reason`). The vCPUs come from the project's compute size.
|
|
237
|
+
|
|
238
|
+
`generic` does not configure AWS PrivateLink, open a firewall, or remove TLS, permission, or
|
|
239
|
+
payment checks. A private endpoint needs a network path, or monitoring hosted in that network
|
|
240
|
+
(`--self-hosted`).
|
|
241
|
+
|
|
242
|
+
`pgai mon deploy` and `pgai dblab deploy` share their options and results: the database URL as the
|
|
243
|
+
argument (or `--db-url`), `--name` (default: from the database), `--cloud` and `--location` (where the box
|
|
244
|
+
runs; see the table), `--wait <minutes>` / `--no-wait`, `--yes` (never prompt), `--json`, the
|
|
245
|
+
`status` words and exit codes below, and `instances list | watch | delete`, which take an id or a name
|
|
246
|
+
(a name two instances have is refused, with their ids). `watch` is also `status`.
|
|
247
|
+
|
|
248
|
+
With JSON output (`--json`, or stdout not a terminal) stderr is the progress stream: one JSON
|
|
249
|
+
object a line, each with `event`. Besides the steps, any other text is
|
|
250
|
+
`{"event":"log","level":"error"|"warn"|"info"|"debug","message":...}`: an error (also a missing
|
|
251
|
+
argument or a bad option; an unknown option is named without its value), a warning (`warn`: a line
|
|
252
|
+
with `Warning:`, also after a `[F001] ` prefix), the `--debug` request log (`debug`), and with
|
|
253
|
+
`--self-hosted` each line of `mon local-install`
|
|
254
|
+
(`"source":"mon local-install"`; `info` from its stdout, `error` from its stderr; the Grafana and
|
|
255
|
+
VictoriaMetrics logins it prints at its end are masked: `pgai mon show-grafana-credentials` shows them).
|
|
256
|
+
|
|
257
|
+
`pgai init` is the same for a person at a terminal: it signs in, asks for the database URL (and,
|
|
258
|
+
for ClickHouse, the API key; neither is shown as typed), then runs `pgai mon deploy`. Without a
|
|
259
|
+
terminal, or with `--json`, it only points to `pgai mon deploy`.
|
|
260
|
+
|
|
261
|
+
| Option | |
|
|
262
|
+
|---|---|
|
|
263
|
+
| `--provider <provider>` | `generic` (direct PostgreSQL; `self-managed` remains an alias), `clickhouse`, `rds` or `supabase`; default: detected from the host |
|
|
264
|
+
| `--clickhouse-key <key-id>:<key-secret>` | ClickHouse Cloud API key, for CPU, memory and disk |
|
|
265
|
+
| `--self-hosted` | run the stack on this machine (`mon local-install`) instead of PostgresAI Cloud |
|
|
266
|
+
| `--reset-password` | the monitoring role exists and its password is lost: set a new one (see below) |
|
|
267
|
+
| `--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 (RDS); refused for Supabase, where PostgresAI creates `postgres_ai_mon` through the Supabase Management API |
|
|
268
|
+
| `--db-url <url>` | the database URL, instead of the argument |
|
|
269
|
+
| `--name <name>` | the instance's name (default: `host[:port]/database`); ignored, with a note, for a database already monitored |
|
|
270
|
+
| `--cloud <cloud>` | `mon deploy`: `aws` or `hetzner`; default: the database's cloud (its RDS, Aurora, EC2 or Supabase region), else AWS. `dblab deploy`: `hetzner`, `aws` or `gcp` (default `hetzner`) |
|
|
271
|
+
| `--location <location>` | a location of that cloud: an AWS region, or a Hetzner location (`fsn1`, `nbg1`, `hel1`, `ash`, `hil`). `mon deploy` default: the database's region, else us-east-1 on AWS; a location of another cloud is refused before anything is created |
|
|
272
|
+
| `--vcpus <n>` | `mon deploy` only: the database server's vCPUs. Without it there is no AAS (database load) data; at a terminal you are asked. On a database already monitored, it sets missing vCPUs (a set value is changed with `mon instances set`) |
|
|
273
|
+
| `--wait <minutes>` | how long to wait for the monitoring box; `0` does not wait (default 20) |
|
|
274
|
+
| `--no-wait` | the same as `--wait 0` |
|
|
275
|
+
| `-y, --yes` | never prompt: deploy where shown and accept the price (`mon deploy` does not start the browser sign-in; `mon instances delete` does not ask). Without it, `mon deploy` asks before creating any box, free or billed, and at a terminal lets you choose another cloud and location; not at a terminal it stops (exit 3) with the place, the price and `choices` |
|
|
276
|
+
| `--coupon <code>` | promotion code for the organization's monitoring subscription |
|
|
277
|
+
| `--json` | JSON output, also on a terminal |
|
|
278
|
+
|
|
279
|
+
Without `--yes`, a non-interactive run for a billed box returns `action_required` with the price
|
|
280
|
+
and asks you to re-run with `--yes` to accept it.
|
|
281
|
+
|
|
282
|
+
| Environment | |
|
|
283
|
+
|---|---|
|
|
284
|
+
| `PGAI_API_KEY` | the API key, instead of signing in (agents, CI) |
|
|
285
|
+
| `PGAI_MON_PASSWORD` | the password of `postgres_ai_mon`. For a new role it is set; for an existing role it is checked by logging in, and never changed. Without it a new role gets a generated password. Not needed for another database on a server PostgresAI already monitors for the organization, with `sslmode=require` or `verify-*` in the URL (see below) |
|
|
286
|
+
| `PGPASSWORD` | the password for a URL without one. With a `postgres_ai_mon` URL it is the password the monitoring box gets, once the server has checked it |
|
|
287
|
+
| `PGSSLMODE` | the `sslmode` for a URL without one (`sslmode` in the URL wins, as in libpq) |
|
|
288
|
+
| `CLICKHOUSE_KEY_ID` + `CLICKHOUSE_KEY_SECRET` | instead of `--clickhouse-key`; read for ClickHouse hosts only |
|
|
289
|
+
|
|
290
|
+
The monitoring role (`postgres_ai_mon`, or `--monitoring-user`) is one role for the whole server, so
|
|
291
|
+
`mon deploy` never changes the password of an existing one. If the role exists and you do not have its password (a deployment after
|
|
292
|
+
`pgai mon instances delete`, say), `pgai mon deploy <admin-url> --reset-password` sets a new one
|
|
293
|
+
(`PGAI_MON_PASSWORD`, else generated). It is refused while another database on the same server (the same host name, in this
|
|
294
|
+
organization) is monitored with the role, while a box's server is not known (it was created before
|
|
295
|
+
the platform kept it, under a name that does not say it), with `--self-hosted`, and for a database
|
|
296
|
+
already monitored. After the price is accepted, the run takes the platform's lock on the server (its host
|
|
297
|
+
name and port, in this organization) until the box is requested. A second `--reset-password` for
|
|
298
|
+
the same server exits 3 meanwhile. A run that stopped, or whose box request got no answer, frees the
|
|
299
|
+
server 15 minutes after it took the lock. A platform without the lock answers "set
|
|
300
|
+
`PGAI_MON_PASSWORD`" instead. Anything else that logs in as the role (another organization,
|
|
301
|
+
another host name for the same server, a deploy without `--reset-password` running at the same
|
|
302
|
+
time) needs the new password.
|
|
303
|
+
|
|
304
|
+
Another database on a server PostgresAI already monitors for the organization needs neither: with
|
|
305
|
+
`sslmode=require` or `verify-*` in the URL, the role keeps its password, the box's URL carries
|
|
306
|
+
none, and PostgresAI fills in the one it kept from the first `mon deploy` (only over TLS, each query
|
|
307
|
+
parameter once, and only while a box on that server is not deleted, being deleted, or failed to
|
|
308
|
+
delete). On a server without TLS the kept password cannot be
|
|
309
|
+
used: set `PGAI_MON_PASSWORD`, or turn TLS on; if nobody has the password, delete the server's
|
|
310
|
+
other instances, then `--reset-password` with `PGAI_MON_PASSWORD` set to a new one, and deploy
|
|
311
|
+
them again with it (`mon deploy` names them).
|
|
312
|
+
|
|
313
|
+
When preparing an existing role with a supplied password (an admin URL with `PGAI_MON_PASSWORD`,
|
|
314
|
+
or the role's own URL), `mon deploy` also tries a random password as `postgres_ai_mon` to learn
|
|
315
|
+
whether the server checks passwords for this host. Successful PostgresAI Cloud preparation makes
|
|
316
|
+
two attempts: one in the check before the price, and one in preparation. Stopping after the check
|
|
317
|
+
(for example, without accepting the price) makes one. Successful `--self-hosted` preparation
|
|
318
|
+
makes one. Creating or resetting the role with an admin URL, using the platform's stored password,
|
|
319
|
+
or returning an existing box's status makes no random-password attempts. A rejected supplied
|
|
320
|
+
password stops before the random-password probe; that rejection is itself a failed login.
|
|
321
|
+
On a server that checks passwords, each random-password attempt adds one
|
|
322
|
+
`password authentication failed for user "postgres_ai_mon"` line to the server log and counts
|
|
323
|
+
toward failed-login policies (credcheck, fail2ban). On a server that does not (`trust`), `next`
|
|
324
|
+
says that the password was not checked; a password from `PGPASSWORD` is then not used: put it
|
|
325
|
+
in the URL.
|
|
326
|
+
|
|
327
|
+
A role that is not a superuser creates `postgres_ai_mon` only if it can run the whole
|
|
328
|
+
preparation: `CREATEROLE`, `CREATE` on the database, `pg_stat_statements` already installed, and
|
|
329
|
+
on PostgreSQL 16+ `ADMIN OPTION` on `pg_monitor` and `pg_read_all_stats`. Otherwise the SQL is
|
|
330
|
+
printed and nothing is created.
|
|
331
|
+
|
|
332
|
+
The host and the port are the ones in the URL: `host` or `port` in the query string is refused.
|
|
333
|
+
Of the query string, the monitoring box gets `sslmode` and `application_name`; `channel_binding`
|
|
334
|
+
is removed using the collector rule above, before a price is quoted or anything is changed.
|
|
335
|
+
Certificate files (`sslrootcert`, `sslcert`, `sslkey`) are used for the connections from this
|
|
336
|
+
machine only; with `sslmode=verify-ca` or `verify-full` and a private CA in `sslrootcert`, `next`
|
|
337
|
+
says that the box has no copy of that CA.
|
|
338
|
+
|
|
339
|
+
A run that fails does not leave such a role behind. The ClickHouse key and the service state are
|
|
340
|
+
checked before the database is touched. If the platform refuses the launch, or a later step of the
|
|
341
|
+
preparation fails, a role that this run created with a generated password is dropped again, so the
|
|
342
|
+
same command can be run again. (After a platform error that is not a refusal, such as a 5xx or a
|
|
343
|
+
timeout, the role stays: a monitoring box may be starting with it.)
|
|
344
|
+
|
|
345
|
+
An admin URL without a database connects to `PGDATABASE`, or else to the database named like the
|
|
346
|
+
user; the name of the connected database (`<host>[:<port>]/<database>`) uses that database.
|
|
347
|
+
|
|
348
|
+
`pgai mon deploy`, `pgai mon instances watch` and `pgai mon instances list` use the same words, and so
|
|
349
|
+
do `pgai dblab deploy` and `pgai dblab instances`:
|
|
350
|
+
|
|
351
|
+
| `status` | Meaning | Exit code |
|
|
352
|
+
|---|---|---|
|
|
353
|
+
| `ready` | monitoring works; `health_url` (when the project is found) and `dashboard_url` are set | 0 |
|
|
354
|
+
| `in_progress` | the monitoring box is being set up (`pgai mon deploy --no-wait`; also when the `--wait` of `pgai mon instances watch` or `pgai dblab deploy` ran out); follow it with the `next` command (`pgai mon instances watch <id>`; for DBLab, `pgai dblab instances watch <id>`) | 0 |
|
|
355
|
+
| `deleting` | a delete is in progress, also the result of `pgai mon instances delete` | 0 |
|
|
356
|
+
| `deleted` | it is gone | 0 |
|
|
357
|
+
| `inactive` | deactivated (billing) | 1 |
|
|
358
|
+
| `action_required` | do what `next` says, then re-run; also when the `--wait` of `pgai mon deploy` ran out with the box still starting (`next`: "Still in progress ... resume with pgai mon instances watch <id>") | 3 |
|
|
359
|
+
| `failed` | `next` has the reason | 1 |
|
|
360
|
+
|
|
361
|
+
When PostgresAI is slow to answer the box request for a database URL, `pgai mon deploy` says it is still
|
|
362
|
+
creating the monitoring box and looks for the box for up to 5 minutes (30 seconds from the MCP tool)
|
|
363
|
+
before `--wait` starts, also with `--no-wait`; then it follows the box as usual. If no box appears, it
|
|
364
|
+
stops with `action_required` and says to check `pgai mon instances list` before running deploy again.
|
|
365
|
+
|
|
366
|
+
`pgai init` exits with 130 when cancelled at a prompt (Ctrl-C, Ctrl-D).
|
|
367
|
+
|
|
368
|
+
`--self-hosted` starts `mon local-install` with the monitoring URL, the API key and the ClickHouse
|
|
369
|
+
key in its environment (`PGAI_DB_URL`, `PGAI_API_KEY`, `CLICKHOUSE_*`), not in its arguments.
|
|
370
|
+
`mon local-install` reads `PGAI_DB_URL` like `--db-url`, and `PGAI_API_KEY` only together with
|
|
371
|
+
`PGAI_DB_URL`: an exported `PGAI_API_KEY` alone does not change a plain or `--demo` install.
|
|
372
|
+
`mon targets add [name]` reads `PGAI_DB_URL` when argv has no `postgres://` / `postgresql://` URL
|
|
373
|
+
(a URL in argv wins); with it set, a lone argument other than a plain name (ASCII letters,
|
|
374
|
+
digits, `.`, `_`, `=`, `-`, with no `password=` / `pwd=`) is refused. Its default name is
|
|
375
|
+
`<host>-<database>`. Percent-encode the user name and the password one at a time (all but ASCII
|
|
376
|
+
letters, digits, `-`, `.`, `_` and `~`), and an `@` in the database name or the query. A user name
|
|
377
|
+
or password that pgx would misread or refuse is refused; an `@` after the host is refused, since it
|
|
378
|
+
cannot be told apart from one in a password; so is a control character anywhere in the URL.
|
|
379
|
+
Under sudo, pass `PGAI_DB_URL` on stdin, not with `--preserve-env`: sudo logs the variables it keeps.
|
|
380
|
+
Where sudoers enables I/O logging (`log_input`), sudo records stdin too: read the URL from a file
|
|
381
|
+
of mode 0600 inside the root shell instead.
|
|
382
|
+
|
|
144
383
|
### Authentication
|
|
145
384
|
|
|
146
385
|
Authenticate via browser to obtain API key:
|
|
@@ -181,6 +420,7 @@ pgai reports list --org-id 5225 # by numeric id — same on every org-scope
|
|
|
181
420
|
PGAI_ORG=acme pgai checkup ... # for scripts and agents
|
|
182
421
|
|
|
183
422
|
pgai orgs # which organizations can this token reach?
|
|
423
|
+
pgai orgs create --name "My team" --alias my-team --json # global user token required
|
|
184
424
|
```
|
|
185
425
|
|
|
186
426
|
`--org` always means an alias and `--org-id` always means a numeric id.
|
|
@@ -195,6 +435,32 @@ unaffected and need no flag.
|
|
|
195
435
|
The MCP server follows the same rule — under a global token, `org_id` becomes a
|
|
196
436
|
required tool argument instead of falling back to a stored default.
|
|
197
437
|
|
|
438
|
+
### DBLab in PostgresAI cloud: `pgai dblab deploy`
|
|
439
|
+
|
|
440
|
+
```bash
|
|
441
|
+
PGPASSWORD=<password> pgai dblab deploy 'postgresql://<user>@<host>:5432/<db>'
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
The same options as `pgai mon deploy` (`--db-url`, `--name`, `--location`, `--wait`, `--no-wait`, `--yes`, `--json`),
|
|
445
|
+
plus `--size S|M|L` (default `S`), `--disk <GiB>` (default 50), `--cloud hetzner|aws|gcp` and
|
|
446
|
+
`--provider generic|rds|supabase` (default: detected; `self-managed` remains an alias of `generic`). `--name` defaults to
|
|
447
|
+
the database's name; `--wait` to 120 minutes.
|
|
448
|
+
It shows the estimated monthly cost before asking; with no payment method it stops with the billing page (exit 3).
|
|
449
|
+
`pgai dblab instances list | watch (status) | delete` take an id or a name.
|
|
450
|
+
|
|
451
|
+
The server gets no SSH keys of yours: clones are reached through an SSH tunnel as `dblab-tunnel`, a user that can only
|
|
452
|
+
forward to the clone ports. Allow your key after the deploy (organization admins; it applies within a minute):
|
|
453
|
+
|
|
454
|
+
```bash
|
|
455
|
+
pgai dblab access add <id or name> --public-key-file ~/.ssh/id_ed25519.pub # or --ssh-key <org key name or id>
|
|
456
|
+
pgai dblab access list <id or name> # the allowed keys, and the tunnel command
|
|
457
|
+
pgai dblab access remove <id or name> --ssh-key <org key name or id>
|
|
458
|
+
ssh -N -L 6000:127.0.0.1:6000 dblab-tunnel@<server ip> # then: psql "host=127.0.0.1 port=6000 ..."
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
`--ssh-key` on `pgai dblab deploy` puts organization keys on the server itself, only in an environment that allows
|
|
462
|
+
that.
|
|
463
|
+
|
|
198
464
|
### Start monitoring
|
|
199
465
|
|
|
200
466
|
Start monitoring with demo database:
|
|
@@ -256,6 +522,11 @@ When `--instance-id <uuid>` (or `PGAI_INSTANCE_ID`) is set, `local-install` forw
|
|
|
256
522
|
```bash
|
|
257
523
|
postgresai mon targets list # List databases to monitor
|
|
258
524
|
postgresai mon targets add <conn-string> <name> # Add database to monitor
|
|
525
|
+
# Same, URL kept out of argv and out of the sudo log (read from stdin, not exported),
|
|
526
|
+
# unless sudoers enables I/O logging (log_input), which records stdin:
|
|
527
|
+
printf '%s\n' "$URL" | sudo sh -c 'IFS= read -r PGAI_DB_URL; export PGAI_DB_URL; exec postgresai mon targets add <name>'
|
|
528
|
+
# With log_input, read it from a file of mode 0600 inside the root shell:
|
|
529
|
+
sudo sh -c 'IFS= read -r PGAI_DB_URL < /path/to/db-url; export PGAI_DB_URL; exec postgresai mon targets add <name>'
|
|
259
530
|
postgresai mon targets remove <name> # Remove monitoring target
|
|
260
531
|
postgresai mon targets test <name> # Test target connectivity
|
|
261
532
|
```
|
|
@@ -336,6 +607,7 @@ Tools exposed:
|
|
|
336
607
|
- `update_issue_comment`: update an existing comment (args: `{ comment_id, org_id, content?, attachments?, debug? }`).
|
|
337
608
|
- `upload_file`: upload a local file and return the storage URL plus a ready-to-paste markdown link (args: `{ path, org_id, debug? }`).
|
|
338
609
|
- `download_file`: download a file from storage (args: `{ url, org_id, output_path?, debug? }`).
|
|
610
|
+
- `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. Supabase needs no password (PostgresAI prepares the database through the Supabase Management API): the first time, the result is `action_required` with a consent link in `next`; the user opens and approves it, then the tool is called again. Elsewhere `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.
|
|
339
611
|
|
|
340
612
|
#### `attachments` parameter (issue/comment tools)
|
|
341
613
|
|
|
@@ -468,6 +740,22 @@ postgresai show-key # Show stored key (masked)
|
|
|
468
740
|
postgresai remove-key # Remove stored key
|
|
469
741
|
```
|
|
470
742
|
|
|
743
|
+
### Create an organization
|
|
744
|
+
|
|
745
|
+
```bash
|
|
746
|
+
pgai auth login # choose "All my organizations (global token)"
|
|
747
|
+
pgai orgs create --name "My team" --alias my-team --json
|
|
748
|
+
```
|
|
749
|
+
|
|
750
|
+
- Choose the name explicitly. An agent should ask the user to approve its proposed name first.
|
|
751
|
+
- At login, choose "All my organizations (global token)". A token for one organization cannot create organizations.
|
|
752
|
+
- This works before you belong to any organization. The consent page then offers only the global token.
|
|
753
|
+
- 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`.
|
|
754
|
+
- Organization and instance tokens cannot create organizations. The CLI refuses them before sending anything.
|
|
755
|
+
- 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.
|
|
756
|
+
- 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.
|
|
757
|
+
- Requires the Platform change https://gitlab.com/postgres-ai/platform-all/-/merge_requests/1157 to be deployed.
|
|
758
|
+
|
|
471
759
|
## Configuration
|
|
472
760
|
|
|
473
761
|
The CLI stores configuration in `~/.config/postgresai/config.json` including:
|
|
@@ -592,7 +880,7 @@ PGPASSWORD=... postgresai checkup \
|
|
|
592
880
|
`postgresai checkup <ID> <conn>`); stdout is then a one-key object.
|
|
593
881
|
- **stderr** carries only human-readable diagnostics (progress, warnings,
|
|
594
882
|
errors). It never contains report JSON — machine consumers should read stdout
|
|
595
|
-
only. Do not parse stderr as JSON.
|
|
883
|
+
only. Do not parse stderr of `checkup` as JSON (that of `pgai mon deploy` is JSON lines, see above).
|
|
596
884
|
- **Exit codes**: `0` on success; non-zero when the run fails (connection
|
|
597
885
|
failure, insufficient permissions, an unknown/unavailable check ID, or a
|
|
598
886
|
failing check). On a non-zero exit, no JSON report object is written to
|