Workbench User Manual
The Workbench (wb) is Planck's control plane. It runs as a single Zig binary on the same host as your databases, and gives you one browser tab for everything operational: authenticating, browsing the service tree, writing PQL, deploying WASM services, watching health, taking backups, and wiring up recurring jobs.
This manual walks through the UI in roughly the order you will come across it after your first login. Sections marked (admin only) show up only for users who have the admin role.
For the matching CLI, do see planctl-user-manual. For the language and the data model, refer to the Planck client docs.
Contents
- Logging in
- Header and navigation
- The sidebar tree
- Query editor
- Dashboard
- Server Overview
- Services table
- Backups
- Schedules
PQL syntax has its own page: PQL Reference.
1. Logging in
The login screen authenticates you to system_db, the local Planck instance that holds users, sessions, deploys, and schedules.
You will see two fields:
- Admin User. Defaults to
admin. - Admin Key. Your Base64-encoded API key.
On a fresh install, log in once using the factory default key:
UGxhbmNrX0RlZmF1bHRfQWRtaW5fS2V5XzAwMTA=Right after that first login, wb rotates the key. A dialog shows you the new one. Kindly copy and store it then and there itself. Do note that there is no recovery flow in case you lose it. Click "Continue" to land in the main UI.
Credentials are cached locally, so on subsequent visits you get auto-reconnected. If you are running a replicated control plane, a small role badge (command or query) appears next to the logo.
2. Header and navigation
The blue header is the top-level switcher.
| Button | Section | Access |
|---|---|---|
| Query | Query editor workspace | All users |
| Services | Deployed services table | All users |
| Dashboard | Live metrics and logs | Admin only |
| Schedules | Cron-style task scheduler | Admin only |
| Settings | Workbench configuration | Admin only |
| PQL Ref | Inline language reference | All users |
| Logout | End the session | All users |
Most of the day-to-day work happens in Query, Services, and Dashboard. The other tabs are administrative in nature.
3. The sidebar tree
The left sidebar mirrors the runtime topology: apps at the top, services under each app, and stores under each service.
v myapp
o myapp-command (green = running)
users (store)
orders (store)
o myapp-query (green = running)
v analytics
. analytics-svc (grey = stopped)
events (store)Status dots: green is running, red is crashed, grey is stopped.
Click behavior:
- Click a service to open or focus a query tab against the same.
- Click a store to open a tab and pre-fill a query scoped to that store.
- Hover over a service to reveal the plug (connect / disconnect), refresh (reload schema), and gear (open Server Overview) icons.
The tree is built from /api/left-pane, which wb assembles from AppServices (the supervisor) and the live wire connection to each service.
4. Query editor
The query workspace is tabbed. Each tab is one session against a single service.
Tabs
A tab shows a status dot along with the service name. Hit + to open a new tab, and x to close one. Tabs are independent of each other, so you can keep a long-running scan going in one tab while you poke around in another.
Writing and running queries
Type your PQL in the upper pane. Separate multiple statements with ;.
To execute, click the play button or press Ctrl+R / Cmd+R. The editor picks one statement automatically:
- If you have a selection, it runs the selection.
- Otherwise, if the cursor is sitting inside a
;-delimited statement, that one runs. - Otherwise, the first statement in the buffer runs.
The Run button stays disabled while a query is in flight, both on click and on the keyboard shortcut. This is intentional. It stops accidental double-fires when a slow scan is still working.
On the server side, /api/query is bounded. At most 16 queries run concurrently across the whole workbench, and each one has a 30 second deadline. If you exceed the concurrency cap, you get a clear error back. In case your query times out, the status indicator flips red and reports the timeout. Long-running operational work (backup, GC, restore) goes through the scheduler instead, which has its own longer budget.
Results
The lower pane gives you two views:
- Results: a scrollable, sortable table. Click a row to expand the nested documents. The status bar shows row count, payload size, and elapsed time.
- JSON: the raw response, pretty-printed. Handy for inspecting an error or for copying a value out verbatim.
Status indicator
- Yellow pulsing dot: query running.
- Green dot: idle. Shows the last query's row count, size, and elapsed.
- Red dot: error. The message appears inline.
5. Dashboard
The Dashboard is the live monitoring view (admin only). It samples through wb's scheduler and the per-service stats endpoints, so what you see is exactly what the supervisor is seeing.
It has seven tabs.
Overview
KPI cards across the top:
- Total Reads, Writes, Deletes, Updates.
- Read and Write latency in microseconds.
- WAL bytes written.
- VLog size.
- Dead Ratio (percentage of VLog space that is reclaimable).
Below that, line charts plot the same metrics over time.
Operations
Four charts: DB ops (reads, writes, updates, deletes), WAL ops (appends, fsyncs, flushes), index ops (inserts, searches, scans), and VLog ops (reads, writes, GC runs).
Latency
Two trend charts, one for read latency and one for write latency.
VLogs
Summary cards for total VLog count, entries, and sizes (total, live, dead).
A VLog table lists each file along with its ID, entry count, deletions, sizes, dead ratio, and a tail flag. The Dead Ratio column renders as a colored bar so that reclaim candidates stand out clearly: green under 40%, orange 40 to 70%, red at 70% and above. Files in the red band usually pay back a GC pass. You can wire that as a schedule (see Schedules) or trigger it ad hoc.
HTTP Stats
Per-method HTTP request stats for WASM services. Total count up top, then a table of method, count, average latency, and a distribution bar. The auto-refresh selector (5s, 10s, 30s, off) comes in handy during a load test.
WASM Stats
Health and utilization for a service's WASM runtime:
- Gauge cards for active instances, pool size, and recycle count.
- Progress bars showing utilization against the configured maximum.
- A pool grid where each slot is colored: green = active, blue = idle, grey = empty. Useful for spotting saturation at a glance.
- The configured min and max instance counts.
- Average request latency across the pool.
Logs
A split-pane log viewer:
- Left: a tree of Apps > Services > Log files.
- Right: a line-numbered viewer in monospace.
Type a keyword to highlight the matching lines. ERROR lines render red, WARN lines amber. Pagination is fixed at 1000 lines per page, with Previous / Next controls.
6. Server Overview
Open Server Overview from the gear icon on a service in the sidebar. It is a full-screen admin panel for that one service only.
Schema tab
Browse stores and indexes:
- Expandable tree of every store and its indexes.
- Create Store button (admin only).
- Drop Store via right-click. Confirmation is required.
- Create Index dialog from any store row.
Schema operations post to /api/schema. The changes appear in the sidebar tree on the next refresh.
Configuration tab (admin only)
A YAML editor for the service's config.yaml. Save writes the file and restarts the service. Reset reverts to whatever is on disk. No environment overrides are layered on top of this. The YAML is the source of truth.
Users tab (admin only)
User management for this database:
- Table of username, role, and inline actions.
- Create User: pick a role (
admin,read_write,read_only) and optionally supply a custom key. - Regenerate Key: shows the new key in a modal. Copy it immediately. It is hashed before storage and cannot be retrieved later.
- Update Role: inline dropdown per row.
- Delete User: with confirmation.
For the systemdb service specifically, admins also get a Permissions tab for finer-grained access.
Service controls (top bar)
A running indicator on the left. Start / Stop / Restart / Undeploy on the right, plus a Back button. WASM bundles can be hot-swapped from the Configuration tab using Update WASM.
7. Services table
The Services view is a flat table of every deployed service across every app.
| Column | Description |
|---|---|
| Name | Service identifier |
| App | Parent app |
| Status | Running (green), Stopped (grey), Crashed (red) |
| Port | TCP port the service is listening on |
| Role | command, query, or standalone |
Hover over a row for inline actions: Start, Stop, Restart, Undeploy, Overview. The same lifecycle endpoints (/api/app-lifecycle) back both this view as well as the Server Overview controls.
8. Backups
Backups in wb are app-scoped. The whole app is quiesced as a unit so that all of its services land at a consistent point in time. As such, you manage them from an app's view, not from inside a single service.
- Create Backup: pick a directory path, click Create. The backup runs against every service in the app.
- Backup list: a table of path, size, and creation timestamp.
- Restore: per-row button. You can optionally point the restore at a different target path.
- Delete: with confirmation.
For unattended backups, wire them up through Schedules instead. The same code paths run; the scheduler only times the call.
9. Schedules
Schedules are recurring jobs managed by wb's scheduler. Admin only.
Task types
| Type | Scope | What it does |
|---|---|---|
backup | App | App-consistent backup to a target path |
gc | Service | Reclaim dead VLog space |
truncate | Service | Truncate write-ahead log segments |
stats | Service | Sample metrics into the system catalog |
export | Service | Export a store from a YAML manifest |
import | Service | Import a store from a YAML manifest |
restore | Service | Restore from a backup on a cron |
Replication is not a scheduled task. It runs continuously between the leader and follower nodes, so it does not need a cron entry.
Creating a schedule
The form walks top to bottom:
- Name for the schedule.
- App, then Service for service-scoped tasks. Backups skip the service picker, since they cover the whole app.
- Task Type.
- Cron expression, with quick-fill buttons: every minute, every 5 minutes, hourly, daily 2am, daily 4am, and weekly Sunday 3am.
- Backup Path for
backuptasks; Manifest (YAML) forexportandimport. - Description (optional).
- Enabled toggle.
Managing schedules
Each row in the schedules list can be paused, resumed, run immediately, edited, or deleted. The scheduler skips the disabled rows and logs every execution. Failures do not disable the schedule; they simply show up in the logs and in the next health snapshot.