postgresai 0.18.0-dev.15 → 0.18.0-dev.17

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
@@ -225,17 +225,40 @@ continues, `s` stops); elsewhere it exits 3 with `"step":"allow_ip"` and `ip`, `
225
225
  --ip-allowed` to create the box with it. `--ip-first` asks for the IP first even when PostgresAI
226
226
  can reach the database. A re-run never reserves a second IP; the IP is held 7 days and stays the
227
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`).
228
+ and its IP kept: allow it, and run with `--ip-allowed` again. Any database can also use self-hosted
229
+ monitoring (`--self-hosted`).
230
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).
231
+ An Amazon RDS that is not publicly accessible is monitored over AWS PrivateLink: nothing becomes public and no port is
232
+ opened. Run the deploy where the database is reachable (in its VPC):
233
+
234
+ ```bash
235
+ pgai mon deploy 'postgresql://postgres:<password>@<instance>.<id>.<region>.rds.amazonaws.com:5432/app'
236
+ ```
237
+
238
+ It reads the instance with the aws CLI when it can (read-only: `sts get-caller-identity`, `rds describe-db-instances`,
239
+ `cloudformation describe-stacks`, `ec2 describe-instance-types`; the profile it uses is printed, `--aws-profile`
240
+ picks one, `--no-aws` skips AWS), else asks public DNS whether the RDS is public (inside the VPC, AWS resolves even a
241
+ public RDS to a private address). Then: the price; a CloudFormation link that creates the stack in your AWS account,
242
+ filled in with what AWS said (`--terraform` writes the same as a Terraform module); the `postgres_ai_mon` role; the box
243
+ on AWS in the RDS's region; and its check of the database over PrivateLink. At a terminal it waits up to 30 minutes for
244
+ the stack, under any name: it is found by its `RdsInstanceIdentifier` (with several for the RDS, you pick one; scripts get
245
+ them listed in `stacks`). `[o]` opens the link where a browser can open. Without AWS, the link leaves the VPC, subnets and
246
+ security group to choose in the form (listed above it), and deploy asks for the stack's `VpceServiceName`. Scripts and agents get
247
+ exit 3 with `"step":"privatelink_stack"` and `cfn_url`: create the stack, then re-run (with `--vpce-service <name>`
248
+ when AWS is not read here). When the URL's user can't create the role, the SQL comes back (`"step":"prepare_db"` with
249
+ `sql`, `nonce`, `monitoring_password`): run it as the master user in that database, then re-run with
250
+ `PGAI_MON_PASSWORD` and `PGAI_MON_NONCE` set to those. `--host-stats` adds host CPU, memory, disk and IOPS through a
251
+ read-only role the stack creates. `--privatelink` / `--no-privatelink` decide public or private instead. Aurora and RDS
252
+ Proxy endpoints are not supported over PrivateLink. A publicly accessible RDS is monitored directly.
253
+
254
+ Supabase hostnames go to the Supabase consent flow (`pgai mon deploy` for Supabase).
232
255
 
233
256
  A Supabase project needs no URL at all: `pgai mon deploy --provider supabase` connects the Supabase organization
234
257
  if needed and lists its projects. At a terminal you pick one; agents and scripts pass
235
258
  `--supabase-project <name or project ID>`. Without either, with `--yes`, or not at a terminal, it stops (exit 3) with the list
236
259
  in the JSON result (`projects`, each with `selectable` and `reason`). The vCPUs come from the project's compute size.
237
260
 
238
- `generic` does not configure AWS PrivateLink, open a firewall, or remove TLS, permission, or
261
+ `generic` does not configure AWS PrivateLink (`rds` does, for a private RDS), open a firewall, or remove TLS, permission, or
239
262
  payment checks. A private endpoint needs a network path, or monitoring hosted in that network
240
263
  (`--self-hosted`).
241
264
 
@@ -264,9 +287,14 @@ terminal, or with `--json`, it only points to `pgai mon deploy`.
264
287
  | `--clickhouse-key <key-id>:<key-secret>` | ClickHouse Cloud API key, for CPU, memory and disk |
265
288
  | `--self-hosted` | run the stack on this machine (`mon local-install`) instead of PostgresAI Cloud |
266
289
  | `--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 |
290
+ | `--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. Refused for a private RDS over AWS PrivateLink (the box uses `postgres_ai_mon`) and for Supabase, where PostgresAI creates `postgres_ai_mon` through the Supabase Management API |
268
291
  | `--db-url <url>` | the database URL, instead of the argument |
269
292
  | `--name <name>` | the instance's name (default: `host[:port]/database`); ignored, with a note, for a database already monitored |
293
+ | `--privatelink` / `--no-privatelink` | RDS: over AWS PrivateLink (not publicly accessible) or directly; default: decided from AWS, else public DNS (see the PrivateLink paragraph above) |
294
+ | `--vpce-service <name>` | RDS over PrivateLink: the stack's `VpceServiceName` output, when AWS is not read here |
295
+ | `--host-stats` / `--host-stats-role <arn>` | RDS over PrivateLink: host CPU, memory, disk and IOPS through the stack's read-only role (its `HostStatsRoleArn` output, when not read from AWS) |
296
+ | `--aws-profile <name>` / `--no-aws` | RDS: the aws CLI profile that reads the instance and its stack (read-only); `--no-aws` skips AWS |
297
+ | `--terraform` | RDS over PrivateLink: write the stack as a Terraform module (`./postgresai-privatelink-<instance>/`) instead of the CloudFormation link |
270
298
  | `--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
299
  | `--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
300
  | `--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`) |
@@ -282,6 +310,7 @@ and asks you to re-run with `--yes` to accept it.
282
310
  | Environment | |
283
311
  |---|---|
284
312
  | `PGAI_API_KEY` | the API key, instead of signing in (agents, CI) |
313
+ | `PGAI_MON_NONCE` | RDS over PrivateLink: with `PGAI_MON_PASSWORD`, the printed SQL (`"step":"prepare_db"`) ran: deploy goes on with its password and nonce, without a new SQL |
285
314
  | `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
315
  | `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
316
  | `PGSSLMODE` | the `sslmode` for a URL without one (`sslmode` in the URL wins, as in libpq) |