Extensions
An extension is a plain text file. Its double extension says what it is, wherever it lives, and the Explorer manages it like any other file: new, rename, cut, paste, drag, pins, Frequent. This page is the orientation; the full product document and the annotation specification hold the rest.
Three flavors
| Flavor | File name | Answered by |
|---|---|---|
| Grid extension | name.plumesql.js | the result grid it shapes: formatting rules, computed and companion columns, result views |
| Query extension | name.plumesql.sql | a grid, from a saved query with annotations |
| Command extension | name.plumesql.run | a terminal, from a saved command such as pg_dump, pg_restore or psql |
A row wears a feather in the flavor's hue, and the tab strip a lettermark (GRID, EXT, RUN). The older spellings .plume.*, .grid.js, .action.sql and .action.run stay recognized for good; a file in your repository is never renamed.
Where they live
Anywhere the Explorer sees: in the workspace (versioned with the project, plain SQL or JavaScript to every other tool), in Scripts (shared by every workspace) or in Workspace Scripts (this workspace's own, kept in the global directory so the repository is never written to). The same name in two roots is two extensions.
The starters
A fresh install ships dozens of editable starters: Activity (with a chart of what pgAdmin's dashboard draws), idle in transaction, long running queries, locks with cancel and terminate buttons, table and database sizes, vacuum candidates, transaction wraparound, replication, server settings, roles and privileges, the system catalogs, top queries from pg_stat_statements, TimescaleDB, Citus, pg_cron and pg_partman folders, backup and restore with pg_dump and pg_restore, and psql itself on the connection in the integrated terminal.
New files come from the Explorer's menus, the F1 palette ("PlumeSQL: New Extension", New Action, New Command Action) and, on the desktop, File > New. Each starter template is typed, so completion works from the first keystroke.
A query extension in one glance
sql
-- @description What every backend on this database is doing
-- @refresh 3s
select pid, usename, state, query from pg_catalog.pg_stat_activity;
-- @button cancel
-- @on pid
-- @confirm Cancel the running query on backend $pid?
select pg_catalog.pg_cancel_backend($pid);The first command is the extension's own. Every command below it is a button, its $column bound from the clicked row, never pasted. @open instead of @button asks a question with the row's values and replaces the grid one step deeper, with Back, Forward and a crumb trail.
@for: an extension on a kind of object
-- @for table attaches an extension to every table: in the row menu, in the open table's DDL header and in the title bar while the table is the active tab, running with {schema}, {name}, {object} and {type} filled in. The same works for view, routine, sequence, hypertable, continuous aggregate, distributed table and reference table. Eleven of the starters are attached this way: a table's size and maintenance state, its indexes, a routine's calls, a sequence's state, a pg_dump of one table, a hypertable's chunks, a distributed table's shards.
Pins in the title bar
-- @toolbar pins an extension where you want it: the title bar's start or end, either sidebar's strip, the status bar, the active script's toolbar or the first result's header. At results, a @for extension is offered for the tables the result's query reads. The row menu's Pin to places or moves a pin without editing the file.
Typed inputs
An extension asks for what it cannot know in advance. @var, @file, @dir and @pick open one form (the row form's shape), with fields typed by asking the server what the statement's parameters expect, pickers fed by queries, and defaults answered without asking. {host}, {port}, {db}, {user}, {conn}, {date}, {time} and {timestamp} come from PlumeSQL itself. {password} exists only for a command extension's @env line and is refused everywhere else.
Command extensions
A command extension runs a PostgreSQL client tool directly on a PTY, with no shell in between (argv is split, nothing is escaped), the tool resolved to a version that suits the server, and the password handed over only through the child's environment. Flags for psql, pg_dump, pg_restore, pg_dumpall, pg_isready, vacuumdb, reindexdb, createdb, dropdb and plumesql dump-tree complete and explain themselves in the editor. The integrated terminal that answers them exists on macOS and Linux.
Refresh
-- @refresh 3s re-runs an extension on a timer while its tab is active, and keeps a result view live. A refresh that fails adds a Log entry only when what is wrong changes.
Grid extensions
A .plumesql.js file exports rules that match a column by name or type, guard with when(columns), format cells, add computed and companion columns, or declare a result view. It is attached from the grid's Extensions menu or a script's -- @extension line, scoped with // @for and // @query, and edited with type-aware completion, hover and @ts-check squiggles. extensions.enabled is the master switch. A broken extension reports to the Log, and the console's extensions.<name>.explain() says what it did to a grid.
Reference
- Actions: the product document, how PlumeSQL surrounds the format: the pane, the buttons, the run model, the Log.
- Annotations: the specification, every annotation, every placeholder and the conformance requirements, written to be implemented by other tools too.