@kazurolabs/psql-explorer 0.1.0 → 0.3.1

package/README.md

@@ -52,6 +52,228 @@ their tables, views, functions, sequences and types, and the one you pick is sho
 Every view has an address of its own, e.g. `#/staging/table/app/users`. The server listens on loopback only. From a checkout, `npm run dev:web` starts the API and Vite with hot reload together (run
 `npm run install:web` once first), and `npm run build` compiles the CLI and builds `web/dist`.
 
+### Settings on the SQL page
+
+The **Settings** button on the SQL page sets Postgres settings (GUCs) such as `statement_timeout`,
+`work_mem`, `search_path` or a custom `app.tenant_id` on the session before each Run, Explain and
+export. They are kept per environment in the browser. In a read only environment the read only
+settings themselves cannot be changed.
+
+### Seed page
+
+Beside **SQL**, a **Seed** tab fills a table with generated rows, for building up a development
+database (`#/dev/seed/app/users`). Pick a table, then a generator for each column: Faker's people,
+places, companies, internet, text, numbers and dates, plus a fixed value, one of a list, a counter, a
+Faker template such as `{{person.firstName}}-{{number.int(99)}}`, or an existing row of the table
+a foreign key points at. Each column starts on a suggestion from its name, type and constraints
+(serials, identities and `now()` defaults keep their default; enums and `CHECK (x IN (...))` lists
+become "one of a list", where each allowed value can be ticked or not and given a weight, so
+`shipped` can come up six times as often as `paid`; a typed list takes weights one a line), and has
+its own options, a share of NULLs and a "unique" switch. Choose
+how many rows (up to 100,000), a locale and optionally a seed (the same seed makes the same rows),
+preview the first ten, then insert. All rows go in one transaction, so a run adds every row or
+none; "Skip rows that clash" adds `ON CONFLICT DO NOTHING` instead. A unique column tries 100 times
+for a value it has not made yet and then fails the run; "Skip rows that run out of unique values"
+leaves that row out instead. Either skip can add a few fewer rows than asked for, and the result
+says how many were skipped. Your picks for a table are kept in the browser.
+
+Columns can depend on each other, so rows hang together. **Add condition** under a column's
+generator adds "when ‹another column› is / is not / is one of / > / < / is NULL ‹value›, use ‹this
+generator›" cases: for a book, `num_pages` can be 10 to 1000 when `is_digital` is true and 100 to
+2000 otherwise, and `file_mb` NULL unless it is digital. The first case that matches is used, and
+the column's own generator otherwise. A template can also use another column of the same row,
+e.g. `{{row.first_name}}.{{row.last_name}}@{{internet.domainName}}` for an email that matches the
+name. Columns are made in the order this needs, so conditions may point either way; a loop, or a
+condition on a column left on its default (whose value is not known), is refused.
+
+Rows can take values from other tables through **Linked tables**. Each foreign key of the table is
+a link already (named after its constraint), and **Link a table** adds any other table, say a
+lookup table. A link gives each new row one row of its table, and every column that reads the link
+reads that same row, so all the columns of a composite foreign key always point at a row that
+exists. Columns read a link with "Existing row it references" (a foreign key column),
+**Column of a linked table** (any link and column), or `{{link.name.column}}` in a template. A
+link either picks **a random row for each new row** (optionally each row once, for a one-to-one
+key) or makes **new rows for each of its rows**: set the orders link of `order_lines` that way with
+3 to 5 rows for each, and every order gets 3 to 5 lines; the number of rows to insert then follows
+from the table. Several such links make rows for every combination of their rows. **Counting up for
+each linked row** starts again for each of them, for line numbers 1, 2, 3 of each order.
+
+Array columns (`text[]`, `int[]`, an array of an enum) get a list per row: **Some of a list** picks
+between a min and max of distinct values from the ones you give (an enum array starts with its
+labels), and any other generator is repeated for each item, with a min and max number of items
+per array (1 to 3 unless you say). A fixed value written as an array literal, like `{a,b}`, is used
+as it is.
+
+The tab is only offered where the environment says `seeder: true`, which is the default for the
+`development` and `local` tiers (and for local connections). A read only environment can only
+preview, unless it is protected and switched to write mode.
+
+### Graph page
+
+A **Graph** tab beside **Compare** draws rows and the rows linked to them through foreign keys, so
+"this order, its customer, its lines and their products" can be seen at once
+(`#/dev/graph/app/orders?filters=...&depth=1`). It only reads, and works on every environment. Pick a
+table, narrow it with the same filters as the Rows tab, choose a depth (0 to 3) and a direction
+(rows it points at, rows pointing at it, or both), and press **Draw**. Each row is a dot coloured by its
+table that pushes the others apart while its links pull it towards the rows it is linked to (a
+force-directed layout). The dot is named by a label from the row's data, and under it, fainter, is the
+name of its table. An arrow runs from the row holding a key to the row it points at (hover for the
+key's name). Click a dot to follow its links, shift-click to see its row, and click a "+37 more in
+order_lines" node to load the next rows of a key. Drag a dot to move it, drag the background to move
+around, scroll to zoom, and **Re-layout** lays it out afresh and fits it to the screen. The legend hides
+and shows tables and keys. (The earlier layout, in columns of cards by distance, is still in the code
+as `Canvas` in `web/src/components/graph-view.tsx`, but the page no longer uses it.)
+
+A **schema map** above the graph is a small entity relationship diagram of the table's schema: a box
+for each table (with the number of its rows drawn) and an arrow for each foreign key. Click a table to
+leave it out of the graph, which then goes through it as it does for a join table, and click an arrow to
+stop following that key; a bar offers **Draw again** (or **Undo**) to apply the changes. Clusters of
+rows that are not linked to each other push each other further apart than rows of one cluster do.
+
+**Labels and tables** sets how the drawing is named, for each kind of row in it. The first time a table
+shows up it is asked about: a row is named by its primary key (the values joined for a composite key)
+until other fields are picked, and several picked fields are joined too. A table can also be
+**removed from the graph**, which is for join tables of many to many relationships: its rows are not
+drawn, and the rows at either end are linked directly by a dashed line (named `via` the table) as if it
+were not there. This also works for a chain: with `orders` and `order_lines` both removed, a customer is
+linked to the products it ordered (`via orders › order_lines`). The foreign keys are followed in either
+direction through up to three removed tables, with one join that gives the distinct pairs of rows, and
+the shortest way to each table is used. A table that a key leads to directly is not also reached the long
+way. At most 20 rows are linked to a row this way, and the graph says when that cut some off. The tables that look like join tables (two or more keys leaving their rows) are marked.
+Removing or restoring a table draws the graph again. These choices, and the keys not followed, are remembered in the browser for each
+environment.
+
+The Rows tab has a **Graph** link that starts from its filters, and the row drawer a graph button that
+starts from that row.
+In the **SQL** tab, a result whose columns include a table's primary key gets a checkbox on each row;
+tick some, pick which table they are rows of (the ones the statement names come first) and follow
+**Graph N rows** to draw exactly those rows (`?keys=...` in the address). The address carries the table, filters, depth, direction and the cards that were
+opened, so a copied link draws the same graph. **Export** saves the drawing as SVG or PNG, or the nodes
+(with their rows) and edges as JSON.
+
+### Cypher page
+
+A **Cypher** tab queries the database in a small, read only subset of Cypher, the language of Neo4j. A
+label is a table and a relationship is a foreign key, so you ask for the shape of what you want rather
+than writing the joins. To find products that customers buy together:
+
+```cypher
+MATCH (a:Product)<-[]-(c:Customer)-[]->(b:Product)
+WHERE a.id < b.id
+RETURN a, b, count(DISTINCT c) AS customers
+ORDER BY customers DESC
+LIMIT 25
+```
+
+Rows that are returned (`a`, `b`) are drawn as a graph, linked as the pattern links them, and a number the
+query returns for each link (`customers`) labels it and sets its thickness. There is also a table of the
+result. **Show SQL** shows the statement the query becomes, with the values written in, and how each
+relationship was joined. The query is also in the address (`#/dev/cypher?q=...&run=1`).
+
+- **Labels** name a table: `Customer`, `customers` and `OrderLine` (for `order_lines`) all work, and a
+  name in backticks may carry a schema, as in `` `shop.customers` ``. The environment's schema is tried first;
+  a name found in two other schemas must be given with one.
+- **Relationships** follow a foreign key: `-[]->` from the table holding it, `<-[]-` to it, `-[]-` either
+  way. Tables with no key between them are joined through the shortest chain of keys through other tables
+  (up to three), as customers to products are through orders and order lines; the direction of the arrow
+  is not used for such a chain. When two keys, or two chains, are equally good, the error lists them and
+  a hint in the brackets picks one: the name of a key or its column (`-[:billing_address_id]-`), or a
+  table on the way (`-[:orders]-`). The nodes along a chain can also be written out.
+  A relationship cannot be named, and has no properties; paths of any length (`*`) are not supported.
+- **Properties** in a node (`(c:Customer {country: 'NZ'})`) and **WHERE** narrow the rows: `=`, `<>`, `<`,
+  `<=`, `>`, `>=`, `IN [...]`, `IS [NOT] NULL`, `STARTS WITH`, `ENDS WITH`, `CONTAINS`, `=~` (a regular
+  expression for the whole value), `AND`, `OR`, `NOT`, and `toLower`, `toUpper`, `coalesce`, `abs`. Two
+  rows are compared with `=` and `<>` by their primary keys, which is how to leave out a row paired with
+  itself (`a <> b`), or to count each pair once (`a.id < b.id`).
+- **RETURN** takes rows, columns (`c.name`, optionally `AS`) and `count`, `sum`, `avg`, `min`, `max` and
+  `collect`, which group by whatever else is returned; with `DISTINCT`, `ORDER BY`, `SKIP` and `LIMIT`.
+  `RETURN *` returns every named node.
+- Two relationships that follow the same keys use different rows, as in Cypher (so a row is never its own
+  neighbour); the same row may still be matched by two nodes, which `<>` rules out.
+- Not supported: anything that writes, `OPTIONAL MATCH`, `WITH`, `UNWIND`, `UNION`, parameters and
+  arithmetic.
+
+Before a query runs, the SQL it becomes is **planned** (`EXPLAIN`, which runs nothing) and assessed. A
+query that looks heavy shows what makes it so: a pattern in parts that nothing joins (a cross join), many
+tables, grouping or sorting large tables that nothing narrows, or a plan that Postgres estimates at a high
+cost or with a join producing millions of rows. A medium warning is shown with the result. A high one is
+not run until **Run anyway** is pressed. A query that runs does so in a read only transaction that is
+stopped after 15 seconds, and reads at most 200 rows (1000 with a `LIMIT`).
+
+### Build page
+
+A **Build** tab makes a `SELECT` from a form, for when you would rather click than type
+(`#/dev/build`). Pick a table to start from, then add what you need and the SQL is written beside it as
+you go:
+
+- **Join**: the tables related by a foreign key are offered first, with the columns that match already
+  filled in. Any other table can be joined too, on any two columns you pick: a foreign key is not
+  needed. A join can be inner, left, right, full or cross, take several tests (`=`, `<>`, `<`, ...), and
+  compare as text when the types differ. Each test says whether it follows a foreign key, and columns of
+  different types are flagged before Postgres refuses them.
+- **Columns**: any column of any table, a count of rows, or a count, count distinct, sum, average, min
+  or max; a date can be cut into days, months, ... in a time zone. Columns that are not totals are
+  grouped by.
+- **Filter**: tests that fit the column's type (contains, starts with, one of a list, between, within
+  the last 7 days, is empty, ...), against a value or another column, in groups of "all of" or "any
+  of" inside each other. A filter that is not filled in yet is left out. **Having** filters the totals.
+- **Sort and limit**, and unique rows only.
+
+**Run** shows the result with pages and export, **Edit as SQL** opens the statement in the SQL page, and
+the address carries the whole form, so a link opens the same query. The form is also kept in the
+browser per environment. The page only ever writes a `SELECT` (values are quoted, names are quoted when
+they need it, and a statement is checked to read before it runs), so it works the same in a read only
+environment. Joins, filters, grouping, sorting and a limit are covered; subqueries, `WITH` and window
+functions are for the SQL page.
+
+### Design page
+
+A **Design** tab makes tables from a form and changes the ones that exist, always showing the SQL it
+will run (`#/dev/design/new`, and `#/dev/design/app/orders` to change `app.orders`; the table view
+has an **Edit design** button). A form holds the table (schema, name, comment, unlogged, partitioning
+by range, list or hash), a grid of columns (add, remove, reorder; built-in types with their sizes,
+the database's enums, domains and composite types, arrays, `NOT NULL`, a default, identity, a stored
+generated expression and a comment), constraints (primary key, unique, check, foreign key with its
+actions, `MATCH FULL` and `DEFERRABLE`) and indexes (columns or expressions, unique, btree, hash, gin,
+gist or brin, a partial `WHERE`, `INCLUDE`). Problems show as you type: a duplicate name, a foreign key
+whose column types differ, a primary key on a nullable column (it becomes `NOT NULL`). The SQL is
+formatted beside the form, with **Copy** and **Open in SQL**. **Create** runs it in one transaction and
+names the statement that failed; afterwards **Seed it** opens the Seed page on the new table where
+the environment allows seeding. A new form is kept in the browser until the table is created or cleared.
+
+Editing loads the table into the same form and works out the `ALTER` statements from what you change:
+adding, dropping and renaming columns, constraints and indexes (rows are followed by their own id, so
+a rename is a `RENAME` and not a drop and an add), a changed type with a `USING` expression you can
+write, defaults, `NOT NULL`, identity, comments, and renaming the table or moving it to another schema.
+Partitioning, exclusion constraints and indexes with a custom operator class or ordering cannot be
+changed here, and the page says which parts it leaves alone. Next to a statement are the warnings
+that apply, with the table's row estimate: a type change that rewrites the table, `NOT NULL` or a new
+constraint that reads every row. A foreign key or check can be added `NOT VALID` and then validated in a
+second statement, and an index can be built `CONCURRENTLY`, which cannot run in a transaction and so
+runs afterwards. Everything else runs in one transaction that starts with `SET LOCAL lock_timeout`
+(5 seconds, editable), so a busy table fails fast instead of queueing behind other locks.
+
+Anything that drops something (a table, column, constraint or index) lists what depends on it first
+(views, foreign keys from other tables, functions), adds `CASCADE` only when ticked, and asks for two
+random words before it runs, as write mode does. **Drop table** is a separate button.
+
+The page needs `designer: true`, which defaults to on for the `development` and `local` tiers; where it
+is off, or the environment is read only (unless it is protected and switched to write mode), the SQL
+can only be previewed. The search box (`Cmd/Ctrl-K`) has **New table** and `edit design of orders`.
+
+### Compare page
+
+A **Compare** tab shows how this environment's database is built differently from another's, for
+checking that staging matches production before a release (`#/staging/compare/production`). It
+compares every schema, or one, which may have another name on the other side (`shop` against
+`shop_next`). Tables with their columns, indexes, constraints, triggers and row level security
+policies, views, materialized views, functions, sequences, types and extensions are each listed as
+differing, or only on one side; what differs is shown side by side, and view and function
+definitions line by line. Owners, grants, comments, column order and the objects an extension
+creates are not compared. Filter by name or by kind of difference, open either side's object, or
+copy the whole comparison as text. Only the catalogs are read, so it works on read only
+environments, and a password the other environment asks for is asked on this page.
+
 ## Commands
 
 ```sh
@@ -65,6 +287,7 @@ psql-explorer query    --env staging "select count(*) from orders"
 echo "select now()" | psql-explorer query --env staging
 psql-explorer info     --env staging
 psql-explorer history  --env staging
+psql-explorer diff     --env staging --with production [--schema app] [--with-schema app_v2]
 psql-explorer configgen:file                    # a commented example environment file
 psql-explorer configgen:vault
 psql-explorer secret:set prod-password          # for `source: stored`; asks, or reads stdin
@@ -143,8 +366,6 @@ quits (when not typing), and so does `Ctrl+C`.
   and a query reads at most `--max-rows` rows (1000 in the TUI), so a `SELECT *` on a big table
   does not fill your memory.
 - Values are shown as the text Postgres sends: no time zone conversion, no rounding.
-- Short-lived credentials and certificates issued by Vault are revoked when you leave the
-  environment or the command ends.
 
 ## Configuration
 
@@ -212,6 +433,8 @@ tier: production # production | reference | demo | development | local
 protected: true # optional; default: tier is production
 readOnly: true # optional; default: protected
 confirm: true # optional; default: protected (type two random words to open it)
+seeder: false # optional; default: tier is development or local (the web UI's Seed page)
+designer: false # optional; default: tier is development or local (the web UI's Design page runs SQL)
 host: db.prod.internal
 port: 5432
 database: app
@@ -237,26 +460,14 @@ Any of `host`, `port`, `database`, `schema`, `username`, `password` and the TLS
 | `prompt`              | asked for when connecting (no `value`), and remembered until the program ends      |
 | `vault`               | a key of a KV v2 secret: `value: <data path>#<key>`, e.g. `secret/data/db/prod#pw` |
 
-Vault can also issue the login and the client certificate:
-
-```yaml
-credentials: # instead of username and password
-  source: vault-database
-  value: database/creds/readonly
-tls:
-  mode: verify-full
-  client: # instead of cert and key (and ca, unless given)
-    source: vault-pki
-    value: pki/issue/psql-explorer
-    commonName: psql-explorer
-```
-
 ### Vault
 
 Vault needs `VAULT_ADDR`, and a token from the first of: `VAULT_TOKEN`; an AppRole login with
 `VAULT_ROLE_ID` and `VAULT_SECRET_ID`; a JWT login with `VAULT_JWT` and `VAULT_ROLE`; the
-`~/.vault-token` the `vault` CLI writes on `vault login`. Secrets are read each time they are
-needed and never kept, so a rotated password is picked up at once. An expired token is reported
+`~/.vault-token` the `vault` CLI writes on `vault login`. Only plain KV v2 secrets are read, not
+dynamic ones such as the database or PKI engines. Secrets are read each time they are needed and
+never kept, so a rotated password is picked up at once. A batch of queries that runs side by side
+(the value search reads tables on up to 4 connections) reads them once and shares the result. An expired token is reported
 as such, with a reminder to `vault login`.
 
 ### Local connections

package/RELEASES.md

@@ -0,0 +1,95 @@
+# Release notes
+
+## 0.3.1 (2026-11-02)
+
+### 2026-11-02
+
+- Fix: Send explain as one statement in a rolled-back transaction, so text after a `;` can no longer write to a read-only environment
+- Fix: Make SQL page links wait for a click before running or explaining their statement
+- Fix: Run a query that cannot be paged as written only when the person pressed Run on it, and page a query that ends in `; -- comment`
+
+## 0.3.0 (2026-11-02)
+
+### 2026-11-01
+
+- [cli] Add a --relnotes flag that prints the release notes
+- Fix: Do not draw nodes for the null side of an outer join in the graph
+- Fix: Leave out rows whose chosen label is null from the row graph
+
+## 0.2.0 (2026-11-01)
+
+Everything built so far, from the commit summaries, oldest first. Print it with `psql-explorer --relnotes`.
+
+### 2026-10-28
+
+- [cli] Initial psql-explorer CLI and TUI
+
+### 2026-10-29
+
+- Database view with schema navigation and object details
+- SQL editor with paged results, ERD view and themes
+- Explain button describing a query plan in plain English
+- Answer prompted config values in the browser
+- Confirm protected environments with two random words
+- Switch protected databases to write mode from the SQL box
+
+### 2026-10-30
+
+- Filter, follow keys, inspect rows and profile columns
+- Open a table as a pre-filled query in the SQL box
+- Deep links carry the SQL statement, tab and page, and refuse unknown databases
+- [tui] Serve the web UI from the TUI and show where it is running
+- Fix: Keep the address bounded so a huge statement cannot stop a query from running
+- Open several query tabs on the SQL page and rename them
+- Copy and share buttons on the SQL page, and paste a share code to open it
+- Numbered pages and a go-to-page box on results pages
+- Export results, query history and saved queries, and cancel with timing
+- Result charts with image export, and inline row editing in write mode
+- Group by day, month and more of date columns, with a time zone setting
+- Format SQL, run scripts statement by statement, and read special types
+- Table stats, an explain plan tree and a dependency view
+- A Seed page that fills tables with generated rows
+- Fix: Only pop up questions for the environment the page is on
+- Skip seeded rows that run out of unique values
+- Link seeded rows to other tables, and make rows for each of their rows
+- Tick and weight the allowed values of a seeded column
+- Compare schemas between environments on a Compare page and with diff
+- Give the dev demo environment a database with a different schema
+- Docs: Plan a record graph and a table designer in TASKS2.md
+- Add a designer setting for environments
+- Add a graph API for rows linked by foreign keys
+- Add a DDL builder for table designs
+- Add a Graph page that draws rows linked by foreign keys
+- Add Graph entry points, a shareable address and export
+
+### 2026-10-31
+
+- Add a Design page that creates tables from a form
+- Edit and drop tables from the Design page
+- Docs: Document the Design page and add New table and Edit design to the search box
+- Add a Cypher page that queries foreign keys as a graph, and rework the Graph page
+- Add a Settings editor for GUCs on the SQL page
+
+### 2026-11-01
+
+- Explain functions and column defaults when hovering SQL
+- Autocomplete function names in the SQL editor
+- Show parameter help for the function call being written in the SQL editor
+- Update the sidebar when DDL changes the database objects
+- Autocomplete column types in CREATE TABLE and split the bundle
+- Autocomplete columns in the column list of CREATE INDEX
+- Autocomplete tables after ON and REFERENCES and columns in more DDL
+- Add an LCARS theme with console sounds, a star chart graph and block navs
+- Show row level security policies on tables and the roles of the server
+- Show security details for views and functions
+- Add a dark variant of the standard theme
+- Fix: Share the standard title styling with the dark variant
+- Give each theme its own splash text
+- Add a Build page that makes SELECT queries from a form
+- Drop a file onto a field in the row editor
+- Raise the dropped file limit to 20 MB
+- Fix: Accept a dropped file in an edit request
+- Add a download link for bytea fields in the row viewer
+- Detect more file types and offer a gzip download for bytea
+- Fix: [cli] List confirm in the configgen examples
+- Add a warp field behind the environment list in the lcars theme

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { jsx as _jsx } from "react/jsx-runtime";
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { render } from 'ink';
 import meow from 'meow';
@@ -20,7 +21,7 @@ import { createWebServer, DEFAULT_WEB_PORT, listen, openBrowser } from './web/se
 // a single source of truth. It handles --help and --version (exit 0) itself.
 const cli = meow(`
 	Usage
-	  $ psql-explorer                                   start the interactive TUI
+	  $ psql-explorer                                   start the interactive TUI (also serves the web UI; --port picks its port)
 	  $ psql-explorer envs
 	  $ psql-explorer schemas  --env <name>
 	  $ psql-explorer tables   --env <name> [--schema <schema>]
@@ -29,6 +30,7 @@ const cli = meow(`
 	  $ psql-explorer query    --env <name> "<sql>"         (or "-", or pipe the SQL in)
 	  $ psql-explorer info     --env <name>
 	  $ psql-explorer history  --env <name>
+	  $ psql-explorer diff     --env <name> --with <name> [--schema <schema>] [--with-schema <schema>]
 	  $ psql-explorer --web [--port 7878] [--no-open]     serve the web UI and open it
 	  $ psql-explorer web                                same as --web
 	  $ psql-explorer configgen:file
@@ -46,6 +48,9 @@ const cli = meow(`
 	                   environment anything that would change data is refused by the server.
 	  info             Show the server version, database size and session settings.
 	  history          The statements run with query or the TUI, newest first.
+	  diff             Compare the structure of two environments' databases: tables,
+	                   columns, indexes, constraints, triggers, policies, views, functions,
+	                   sequences, types and extensions. All schemas, or the one --schema names.
 	  web              Serve the web UI and its API on http://127.0.0.1:<port> until stopped.
 	  configgen:file   Print a fully commented example environment kept in a directory.
 	  configgen:vault  Print the same for one kept in Vault.
@@ -57,7 +62,11 @@ const cli = meow(`
 	                   directory, or vault:<KV v2 path> such as vault:secret/data/psql-explorer.
 	                   It holds one <environment>/explorer.yaml per environment.
 	  --env <name>     The environment: a shared one, or a local connection by name
-	  --schema <name>  tables, describe, rows: the schema (default: the environment's)
+	  --schema <name>  tables, describe, rows: the schema (default: the environment's);
+	                   diff: compare only this schema
+	  --with <name>    diff: the environment to compare --env with
+	  --with-schema <name>
+	                   diff: the schema on the --with side, when it is named differently
 	  --format <f>     table (default), csv or json
 	  --json           Same as --format json
 	  --limit <n>      rows: rows per page (default 100); history: how many (default 50)
@@ -71,6 +80,7 @@ const cli = meow(`
 	  --port <n>       web: the port to listen on (default 7878; the next free one is used if taken)
 	  --help           Show this help
 	  --version        Show the version
+	  --relnotes       Show the release notes
 
 	Run without a command to start the interactive TUI.
 `, {
@@ -78,6 +88,8 @@ const cli = meow(`
     flags: {
         config: { type: 'string' },
         env: { type: 'string' },
+        with: { type: 'string' },
+        withSchema: { type: 'string' },
         schema: { type: 'string' },
         format: { type: 'string' },
         json: { type: 'boolean' },
@@ -89,9 +101,21 @@ const cli = meow(`
         timeout: { type: 'number' },
         port: { type: 'number' },
         web: { type: 'boolean' },
+        relnotes: { type: 'boolean' },
         open: { type: 'boolean', default: true },
     },
 });
+// RELEASES.md ships next to dist, like web/dist, and needs neither the database nor a config.
+if (cli.flags.relnotes) {
+    try {
+        process.stdout.write(readFileSync(join(import.meta.dirname, '..', 'RELEASES.md'), 'utf8'));
+        process.exit(0);
+    }
+    catch {
+        process.stderr.write('psql-explorer: the release notes are missing from this install\n');
+        process.exit(1);
+    }
+}
 // Prints an example config and needs neither the local database nor a config.
 const [command, ...args] = cli.input;
 if (command === 'configgen:file' || command === 'configgen:vault') {
@@ -163,7 +187,6 @@ if (command === 'web' || (command === undefined && cli.flags.web)) {
         // Questions are answered in the browser: the page polls /api/prompt and posts the answer.
         resolvers: defaultRegistry(undefined, prompts, store, vault),
         prompts,
-        groups: vault.groups,
         openSession,
     };
     const server = createWebServer({
@@ -188,10 +211,8 @@ if (command === 'web' || (command === undefined && cli.flags.web)) {
     }
     process.once('SIGINT', () => {
         server.close();
-        void vault.groups.releaseAll().finally(() => {
-            store.close();
-            process.exit(0);
-        });
+        store.close();
+        process.exit(0);
     });
     await new Promise(() => { });
 }
@@ -212,7 +233,6 @@ if (command !== undefined) {
             config,
             configError,
             resolvers: defaultRegistry(undefined, prompter, store, vault),
-            groups: vault.groups,
             openSession,
         };
         code = await runCommand({
@@ -226,8 +246,6 @@ if (command !== undefined) {
             stdinIsTTY: process.stdin.isTTY === true,
         });
     }
-    // Credentials and certificates issued for this command end with it.
-    await vault.groups.releaseAll();
     store.close();
     // Let piped output drain before exiting.
     await new Promise((resolve) => process.stdout.write('', resolve));
@@ -249,15 +267,41 @@ const services = {
     store,
     tester: testConnection,
     resolvers: defaultRegistry(undefined, prompts, store, vault),
-    groups: vault.groups,
     prompts,
     openSession,
+    openUrl: openBrowser,
 };
 services.startup = createStartup({ services, base: cli.flags.config, vault });
+// The web UI is served from the same process, so the Environments screen can say where it is.
+// Questions it triggers are answered in the browser, so it gets a prompt queue of its own; the
+// config is the one the splash screen loads. Failing to start it never stops the TUI.
+const webPrompts = createPromptQueue();
+const webServices = {
+    store,
+    tester: testConnection,
+    resolvers: defaultRegistry(undefined, webPrompts, store, vault),
+    prompts: webPrompts,
+    openSession,
+    get config() {
+        return services.config;
+    },
+    get configError() {
+        return services.configError;
+    },
+};
+const webServer = createWebServer({
+    services: webServices,
+    staticDir: join(import.meta.dirname, '..', 'web', 'dist'),
+});
+try {
+    services.webUrl = await listen(webServer, cli.flags.port ?? DEFAULT_WEB_PORT);
+}
+catch {
+    webServer.close();
+}
 const app = render(_jsx(App, { version: cli.pkg.version ?? '0.0.0', fullScreen: true, services: services }), 
 // The app owns the whole terminal, and the shell's screen comes back when it exits.
 { alternateScreen: true });
 await app.waitUntilExit();
-// Short-lived credentials and certificates issued for this session end with it.
-await vault.groups.releaseAll();
+webServer.close();
 store.close();

package/dist/commands/configgen.js

@@ -12,6 +12,19 @@ protected: true
 # Open every session read only (default_transaction_read_only), so nothing run here can change
 # data. Optional, default: the value of protected.
 readOnly: true
+
+# Opening the environment first asks for two random words to be typed back, so it is never
+# entered by accident. Optional, default: the value of protected.
+confirm: true
+
+# Offer the web UI's Seed page, which fills tables with generated rows. Optional, default: true
+# for the development and local tiers, false otherwise.
+# seeder: false
+
+# Let the web UI's Design page run statements that create, alter and drop tables; without it the
+# page only previews the SQL. Optional, default: true for the development and local tiers, false
+# otherwise.
+# designer: false
 `;
 const fileEnvironment = `# One environment: <environment>/explorer.yaml below the base path.
 # Use with: psql-explorer --config <base path>   (or export PSQL_EXPLORER_ENVIRONMENTS=<base path>)
@@ -28,13 +41,13 @@ database: app
 # The schema browsing starts in. Optional, default: public
 # schema: app
 
-# Database login. username is required unless the login comes from Vault (see the vault example).
+# Database login. Required.
 username: readonly
 
 # password (default) needs a password; none means the database takes no password.
 auth: password
 
-# Required when auth is password. Left out when auth is none.
+# Required when auth is password. Must be left out when auth is none.
 password:
   source: file
   value: ./password.txt # relative to this file's folder; the whole content, trimmed
@@ -85,34 +98,21 @@ database: app
 # The schema browsing starts in. Optional, default: public
 # schema: app
 
-# Short-lived login issued by Vault's database secrets engine on every connect, and revoked when
-# you leave the environment. It fills username and password: set neither, and auth must stay
-# password.
-credentials:
-  source: vault-database
-  value: database/creds/readonly
-# Or a fixed login instead of credentials:
-# username: readonly
-# auth: password          # password (default) | none
-# password:               # required when auth is password
-#   source: vault
-#   value: secret/data/db/prod#password
+username: readonly
+auth: password # password (default) | none; none takes no password, so leave password out
+password: # required when auth is password
+  source: vault
+  value: secret/data/db/prod#password
 
 # TLS. Optional, default: mode disable
 tls:
   # disable | require | verify-ca | verify-full
   mode: verify-full
-  # Client certificate issued by Vault's PKI engine. It fills cert and key (set neither),
-  # and ca too unless you give one. Has no effect with mode disable.
-  client:
-    source: vault-pki
-    value: pki/issue/psql-explorer
-    commonName: psql-explorer
-  # CA certificate (PEM text). Required for verify-ca and verify-full unless client is given.
-  # ca:
-  #   source: vault
-  #   value: secret/data/db/prod#ca
-  # A fixed client certificate and key instead of client. Give both or neither.
+  # CA certificate (PEM text). Required for verify-ca and verify-full.
+  ca:
+    source: vault
+    value: secret/data/db/prod#ca
+  # Client certificate and key, for mutual TLS. Give both or neither.
   # cert:
   #   source: vault
   #   value: secret/data/db/prod#cert