@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kazuro Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,506 @@
-# Temporary Holding Version
+# psql-explorer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Explore your Postgres databases from the terminal: browse schemas and tables, page through rows,
+look at columns, indexes and constraints, and run SQL, in an interactive TUI or from the command
+line. It is in the spirit of pgweb, without a browser.
+
+A team shares one set of environments without a database of its own: the config is a folder of
+small YAML files, kept in a directory or in HashiCorp Vault, and every password is looked up when
+it is needed (from Vault, an environment variable, a file, a prompt, ...). Production environments
+are opened **read only** by default, so nothing typed there can change data.
+
+> **Disclaimer:** psql-explorer is under active development and has not reached a stable release.
+> It connects to real databases, including production ones, and runs the SQL you give it. Check
+> which environment you are in, keep production read only, and expect breaking changes between
+> versions. It is provided as is, without warranty (see [LICENSE](LICENSE)).
+
+## Requirements
+
+- Node.js 22.13 or newer
+- PostgreSQL databases
+- An interactive terminal for the TUI. The commands (`tables`, `query`, ...) need none.
+
+## Install and run
+
+```sh
+npx @kazurolabs/psql-explorer             # once, without installing
+npm i -g @kazurolabs/psql-explorer        # or install the psql-explorer command
+```
+
+### Quick start
+
+```sh
+export PSQL_EXPLORER_ENVIRONMENTS=vault:secret/data/psql-explorer   # or a directory
+export VAULT_ADDR=https://vault.example.com:8200
+vault login                                                          # or VAULT_TOKEN, see below
+psql-explorer
+```
+
+Pick an environment and press `Enter`. Without a shared config psql-explorer still starts, and `n`
+saves your own connections.
+
+## Web UI
+
+```sh
+psql-explorer --web [--port 7878] [--no-open]  # serves the UI and API on http://127.0.0.1:7878 and opens it
+```
+
+The UI lives in `web/` (Vite, React, Tailwind, shadcn/ui) and is powered by the same config,
+Vault lookups and read-only rules as the TUI. A value the config says to `prompt` for (a password, say) is asked for in a dialog in the page, and remembered until the server stops. Picking an environment opens its database: the schemas on the left open to
+their tables, views, functions, sequences and types, and the one you pick is shown on the right
+(columns, indexes, constraints, definition and rows for a table; the source of a function; and so on).
+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
+psql-explorer                                   # the interactive TUI
+psql-explorer envs                              # the environments you can use
+psql-explorer schemas  --env staging
+psql-explorer tables   --env staging [--schema app]
+psql-explorer describe --env staging users      # or app.users
+psql-explorer rows     --env staging users --limit 20 --order created_at --desc
+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
+psql-explorer secret:delete prod-password
+```
+
+Every command prints a table like psql's; `--format csv` or `--format json` (or `--json`) give
+output for other tools. In JSON, numbers that fit a JavaScript number, booleans and `json`/`jsonb`
+values are themselves; `bigint`, `numeric` and everything else are the text Postgres sent, so no
+digit is lost.
+
+| Option            | Used for                                                                    |
+| ----------------- | --------------------------------------------------------------------------- |
+| `--config <base>` | the shared config's base path; default `$PSQL_EXPLORER_ENVIRONMENTS`        |
+| `--env <name>`    | the environment: a shared one, else a local connection of that name         |
+| `--schema <name>` | `tables`, `describe`, `rows`: the schema; default the environment's         |
+| `--format <f>`    | `table` (default), `csv` or `json`                                          |
+| `--limit <n>`     | `rows`: rows per page (default 100); `history`: how many (default 50)       |
+| `--offset <n>`    | `rows`: rows to skip                                                        |
+| `--order <cols>`  | `rows`: sort by these columns, comma separated; `--desc` for descending     |
+| `--max-rows <n>`  | `query`: read at most this many rows (default 1000), the rest are not read  |
+| `--timeout <s>`   | the server cancels a statement after this many seconds (default 30, 0 none) |
+
+Exit codes: `0` done, `1` failed (the reason is on stderr), `2` wrong command line. A value the
+config says to `prompt` for is asked for on the terminal (a secret without echo); with no terminal
+the command fails and names the value.
+
+`query` runs one statement at a time. Each statement is kept in the history of that environment
+(in your local data, see below), with how long it took and how many rows it returned.
+
+## The TUI
+
+The **Environments** screen lists the shared environments and your local connections, with their
+tier, address, TLS mode and whether they are read only. `Enter` explores one, `t` tests the
+connection, `n` adds a local connection, `e` and `d` edit and delete one.
+
+Exploring an environment has four tabs (`1`–`4`, or `Tab`):
+
+1. **Tables** — the tables, views and materialized views of a schema, with row estimates, sizes
+   and comments. `/` filters, `s` picks another schema (remembered per environment), `Enter` opens
+   a table on its **Rows** (a page at a time, sorted by the primary key), its **Structure**
+   (columns, types, defaults) and its **Indexes & constraints**; `Tab` switches between them.
+   In the rows, `n`/`p` page, `o` sorts by the selected column (again for descending, a third time
+   for the default), `c` counts the rows exactly, and `Enter` shows a row field by field.
+2. **Query** — type a statement and press `Enter`; `↑`/`↓` recall earlier ones. The result is a
+   grid like the rows. `Esc` leaves the editor, `e` returns to it, `r` runs it again.
+3. **History** — what was run against this environment, newest first. `Enter` puts a statement
+   back in the Query tab.
+4. **Info** — the server version, database size and session settings, and the other connections
+   to the database.
+
+In every grid the arrow keys (or `h` `j` `k` `l`) move a cell at a time, `PgUp`/`PgDn` a page,
+`g`/`G` to the first and last row, `0`/`$` to the first and last column. `Esc` goes back, `q`
+quits (when not typing), and so does `Ctrl+C`.
+
+## Read only, and other safety
+
+- An environment with `readOnly: true` opens every session with
+  `default_transaction_read_only = on`, so the server refuses `INSERT`, `UPDATE`, `DELETE`, DDL
+  and the like. `readOnly` defaults to `protected`, which defaults to true for the `production`
+  tier. The header shows **READ ONLY**. This guards against mistakes; it is not a permission
+  system, so give people a database role that can only read where it matters (Vault's database
+  secrets engine is a good way to hand those out, see below).
+- An environment with `confirm: true` makes you type back two random words (for example
+  `maple ticket`) before it is opened, in the TUI, the web UI and on the terminal, so a protected
+  environment is never entered by accident, even when its password is stored in the config.
+  `confirm` defaults to `protected`; set `confirm: false` to turn it off. It is asked once per run
+  of the program, nothing is looked up before it is answered, and it fails (rather than skips)
+  when nobody can be asked, e.g. in a script with no terminal. The web UI also shows a banner
+  above the SQL box on a protected environment.
+- In the web UI, the SQL box of a protected, read only environment has a switch at its top right.
+  Turning it on asks for two random words again (always, whatever `confirm` says), then every
+  connection of that environment is opened read write until you switch it off or stop the server.
+  The banner turns red and pulses while it is on. Turning it off needs no words.
+- Every statement has a time limit (`statement_timeout`, 30 s unless `--timeout` says otherwise),
+  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.
+
+## Configuration
+
+### Environment variables
+
+| Variable                           | Used for                                                                                         |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `PSQL_EXPLORER_ENVIRONMENTS`       | the shared config's base path, a directory or `vault:<path>`; `--config` wins                    |
+| `PSQL_EXPLORER_CONFIG`             | the directory holding `explorer.db` (local connections, stored secrets, settings, query history) |
+| `XDG_CONFIG_HOME`                  | without `PSQL_EXPLORER_CONFIG`, `explorer.db` is in `$XDG_CONFIG_HOME/psql-explorer`             |
+|                                    | (else `~/.config/psql-explorer`)                                                                 |
+| `VAULT_ADDR`                       | Vault's address (required for anything in Vault)                                                 |
+| `VAULT_TOKEN`                      | the Vault token to use                                                                           |
+| `VAULT_ROLE_ID`, `VAULT_SECRET_ID` | log in to Vault through AppRole                                                                  |
+| `VAULT_JWT`, `VAULT_ROLE`          | log in to Vault with a JWT / OIDC token                                                          |
+| `VAULT_NAMESPACE`                  | the Vault Enterprise namespace                                                                   |
+| any name                           | read by an environment's `source: env` values, for example `STAGING_DB_PASSWORD`                 |
+
+Empty values count as unset. `explorer.db` is created readable by its owner only.
+
+### Shared configuration
+
+Environments shared by a team live under a **base path**, given with `--config <base>` or
+`$PSQL_EXPLORER_ENVIRONMENTS`. It holds one folder per environment, each with an `explorer.yaml`:
+
+```
+<base>/staging/explorer.yaml       one environment; the folder name is its name
+<base>/production/explorer.yaml
+```
+
+The base path is a directory (a git checkout, a shared drive, ...) or Vault:
+
+```sh
+psql-explorer --config ~/team/explorer-config
+psql-explorer --config vault:secret/data/psql-explorer   # a KV v2 "<mount>/data/<path>"
+```
+
+Environments are found by listing the base path. A folder without an `explorer.yaml` is ignored.
+An environment file that is wrong is reported (on the Environments screen, or on stderr) and left
+out; the others still load.
+
+#### Config in Vault
+
+In Vault each environment is the `explorer.yaml` key of a secret below the base path:
+`secret/data/psql-explorer/staging` is the `staging` environment. psql-explorer lists
+`secret/metadata/psql-explorer` to find them, so **what a person sees follows their Vault policy**:
+an environment they may not read is simply not in their list.
+
+```sh
+vault kv put secret/psql-explorer/staging explorer.yaml=@staging.yaml
+```
+
+```hcl
+path "secret/metadata/psql-explorer"         { capabilities = ["list"] }
+path "secret/data/psql-explorer/staging"     { capabilities = ["read"] }   # one per environment
+# or: path "secret/data/psql-explorer/*"     { capabilities = ["read"] }
+```
+
+### An environment file
+
+`psql-explorer configgen:file` (or `configgen:vault`) prints a fully commented example. In short:
+
+```yaml
+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
+schema: app # optional; where browsing starts, and first on the search_path; default public
+username: readonly
+password: # or `auth: none` for a server that takes no password
+  source: vault
+  value: secret/data/db/prod#password
+tls:
+  mode: verify-full # disable | require | verify-ca | verify-full
+  ca: {source: file, value: ./ca.pem}
+```
+
+Any of `host`, `port`, `database`, `schema`, `username`, `password` and the TLS `ca`, `cert`,
+`key` and `keyPassphrase` can be written as plain text or as a `source` and a `value`:
+
+| `source`              | the value is                                                                       |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| `plaintext`, `inline` | the text in `value`                                                                |
+| `env`                 | the environment variable named in `value`                                          |
+| `file`                | the content of the file in `value`, relative to the environment's folder           |
+| `stored`              | a secret of that name in your local store (`psql-explorer secret:set <name>`)      |
+| `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
+
+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`. 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
+
+Press `n` on the Environments screen to save a connection of your own (host, port, database,
+username, password, schema and SSL). They live in `explorer.db` with the password unencrypted,
+in a file only you can read, are never read only, and can be used by name with `--env`.
+
+## Development
+
+```sh
+npm install
+npm run build        # compile src/ to dist/ with tsc
+node dist/cli.js     # run the built CLI
+npm test             # run the tests (Vitest; builds dist/ first)
+npm run lint         # typecheck + ESLint + Prettier check
+npm run format       # apply Prettier formatting
+```
+
+`npm run dev` starts psql-explorer against a demo: a `demo_shop` database (customers, products,
+orders, a 200,000-row `page_views` table with no index on `customer_id` for trying Explain, a view,
+a materialized view and an `audit` schema) on the `psql-explorer-pg` container
+(port 55440, started if it is not running; set `DEMO_PG_URL` to use another server), and a shared
+config in `.demo/config` with a read-write, a read-only and a protected environment. Its data
+directory is `.demo/data`, so your real `~/.config/psql-explorer` is untouched.
+`npm run dev:web` starts the web UI against the same demo. `npm run dev:reset` and
+`npm run dev:web:reset` build the demo again. `npm run dev:plain` runs the TUI without it.
+
+The tests that need a real Postgres run when `PSQL_EXPLORER_TEST_PG_URL` is set, and are skipped
+otherwise:
+
+```sh
+PSQL_EXPLORER_TEST_PG_URL=postgres://postgres:postgres@localhost:55440/app npm test
+```
+
+Each run creates a schema of its own (`explorer_test_<random>`) and drops it afterwards.

package/RELEASES.md

@@ -0,0 +1,87 @@
+# Release notes
+
+## 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/app.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useState, useSyncExternalStore } from 'react';
+import { Box, useApp, useInput, useStdin } from 'ink';
+import { screens as defaultScreens, } from './screens/index.js';
+import PromptModal from './screens/prompt-modal.js';
+import { useTerminalSize } from './screens/terminal.js';
+const noSubscribe = () => () => undefined;
+const noPrompt = () => undefined;
+export default function App({ version, services, initialScreen = 'splash', initialParams, fullScreen = false, screens = defaultScreens, }) {
+    const [route, setRoute] = useState({
+        name: initialScreen,
+        params: initialParams,
+        key: 0,
+    });
+    const { exit } = useApp();
+    const { columns, rows } = useTerminalSize();
+    const { isRawModeSupported } = useStdin();
+    const navigate = useCallback((name, ...[params]) => {
+        setRoute((previous) => ({ name, params, key: previous.key + 1 }));
+    }, []);
+    const entry = screens[route.name];
+    const { prompts } = services;
+    const prompt = useSyncExternalStore(prompts ? prompts.subscribe : noSubscribe, prompts ? prompts.current : noPrompt);
+    const screenInput = isRawModeSupported && !prompt;
+    // Global quit key, off on screens that take text input; Ctrl+C is handled by Ink (exitOnCtrlC).
+    useInput((input) => {
+        if (input === 'q')
+            exit();
+    }, { isActive: screenInput && !entry.capturesInput });
+    // The registry ties each component to its own params type; the route carries the params that
+    // navigate() type-checked for this screen, so widening here is safe.
+    const Screen = entry.component;
+    const screen = (_jsx(Screen, { version: version, navigate: navigate, params: route.params, services: services, isInputActive: screenInput }, route.key));
+    const modal = prompt && (_jsx(PromptModal, { prompt: prompt, isInputActive: isRawModeSupported }, `${prompt.envName}.${prompt.field}`));
+    if (!fullScreen) {
+        return (_jsxs(_Fragment, { children: [screen, modal] }));
+    }
+    return (_jsxs(Box, { width: columns, height: rows, flexDirection: "column", justifyContent: prompt ? 'center' : 'flex-start', children: [_jsx(Box, { display: prompt ? 'none' : 'flex', flexDirection: "column", flexGrow: 1, children: screen }), modal] }));
+}