The workspace
A workspace is the directory you start PlumeSQL in, or the folder you open with it from the file manager. Everything you do in it comes back exactly as you left it, and nothing PlumeSQL keeps about it is written into the directory unless you ask.
Opening one
sh
cd ~/db-scripts && plumesql # the current directory
plumesql ~/db-scripts # named explicitlyFinder's Open With, Explorer's right-click menu (after the System page's one-time registration) and a Linux file manager can hand PlumeSQL a folder too. A folder always gets its own window: an open workspace is never switched out from under you. Open Recent lists the workspaces you had before.
The Explorer
The Explorer side tab (Ctrl+Shift+E, Cmd+Shift+E on macOS) lists the workspace the VS Code way: file kinds, glob presets, sizes and counts on rows, multi-select, drag and drop to move or copy, rename, delete with Undo, and folders that start collapsed on a first open. A file's first comment can carry -- @description (shown under its row) and -- @color (its tab).
Three roots share the tree:
- the workspace itself;
- Scripts, the store shared by every workspace, kept in PlumeSQL's global directory;
- Workspace Scripts, this workspace's own store, also kept in the global directory so the repository is never written to.
A Frequent root lists what you open most. Each root can be hidden from the Explorer menu (files.showGlobalScripts, files.showScripts, files.showFrequent). Auto save is on by default (files.autoSave) with stale-write detection, and a file changed on disk reloads.
What restores
Reopening a workspace restores its open tabs and the active one, each editor's cursor, selection, scroll and folding, both sidebar docks with their widths and pane groups, the editor and results split, the bottom panel, the object tree's expansion and selection per connection, its filters, pins and hides, the collapsed folders of every file tree, each tab's results tab or chart, dismissed parser problems, each file's last used connection, the navigation trail, the palette's recent commands, and the recently opened files and objects.
The session lives in the global directory (sessions/<hash of the workspace path>.json), never in the repository and never in browser storage. Startup opens nothing you did not leave open: an error, an unreachable connection or a missing file goes to the Log and waits there.
Workspace settings
Settings have two scopes, Global and Workspace. Workspace settings stay out of the repository by default (settings.workspaceStorage is global, the file lives beside the session). A committed <workspace>/.plumesql/settings.json always wins, which is how a team's settings take over on checkout; the Settings page's Workspace tab moves the file between the two homes explicitly, the one way .plumesql ever appears in a repository.
The Log panel
Every error and message has one home, the Log in the bottom panel (Ctrl+Shift+U, Cmd+Shift+U on macOS). There are no error toasts and no inline banners: the panel reveals itself for errors, corner cards flash for a few seconds (log.flash) and never steal focus, and a red badge counts what you have not seen. Entries carry their own answers as buttons (Try again, Unhide, Edit connection, Open settings.json) that still work after a restart. The Log is an append-only file per workspace, rotated by size (log.rotateSize), and a change chronicle records the SQL of every run that altered structure or data.
Under the panel is a console line: one line of JavaScript over the app's own state, or a psql command, answering in Markdown tables and code.
The terminal
On macOS and Linux the bottom panel has an integrated terminal on a real PTY (Ctrl+`), following the theme, surviving a reload with its scrollback, with several shells as tabs. Any tree row offers Open in Integrated Terminal and Open in System Terminal. Command extensions and the psql starter run there, the password handed over through the environment. Windows has no integrated terminal yet.
Getting around
- Go Back / Go Forward (
Alt+LeftorCtrl+Alt+-and their Forward pairs;Ctrl+-andCtrl+Shift+-on macOS) walk every kind of view: files, DDL viewers, Settings, a connection editor, a reference page. A closed tab reopens. - Go to Tab or File (
Ctrl+P) ranks tabs, files and extensions by frecency; Go to Object (Ctrl+Shift+O) does the same over database objects. - The command palette (
F1) lists every command grouped by area (Go, Run, Connection, File, View, Editor, Preferences, Help) and keeps a "recently used" section on top. - Search (
Ctrl+Shift+F, replace withCtrl+Shift+H) runs across scripts, workspace files and the DDL snapshot, with regex, preserve case and a per-match preview.
Tabs preview on a single click and pin on a double click, in four strip layouts. Two sidebar docks stack panes with splitters, and one-gesture arrangements put everything left, everything right or split.