Problem or use case
Orca's workspace is project-scoped, but database tooling proposed so far is global to the desktop app. That breaks down when the desktop is paired to a remote Orca runtime or when the project itself is an SSH worktree: a database connection opened by the desktop may not share the project's network, credentials, or host context.
A representative route is:
desktop / web client → owning Orca runtime → project SSH host → PostgreSQL
The database query should originate from the same environment that owns and executes the project, rather than silently dialing from the client machine.
Proposed solution
Add New Database Query to the existing workspace-tab menu, next to Terminal, Browser, and Markdown. A database query becomes a first-class project tab that:
- persists with the project's workspace session
- executes on the runtime that owns the project
- follows the project's configured SSH connection when the worktree is SSH-backed
- supports saved connection profiles scoped to the owning node (
local or a specific SSH connection)
- keeps passwords in a runtime-owned credential vault and never returns them to paired clients
- lets the user select the PostgreSQL database and schema before running a query
- provides schema browsing, bounded results, read-only mode, timeout, and cancellation
The initial provider is PostgreSQL. The shared provider boundary is intentionally small so more engines can be added later without putting provider-specific behavior into the tab/session model.
Relationship to existing database work
This proposal is not another global database page. Its distinct user-facing and architectural goal is a project-scoped workspace tab whose execution follows the worktree runtime, including SSH worktrees. The implementations could share provider or query-grid primitives later, but the workspace integration and execution ownership solve a separate remote-development requirement.
MVP boundaries
Included:
- PostgreSQL query tabs
- project/runtime/SSH-aware routing
- runtime-owned profiles and remembered credentials
- database/schema selection and schema tree
- bounded, cancellable query execution
- desktop and paired web clients
Not included in the initial change:
- table-data editing or migration tooling
- MySQL, SQLite, or other providers
- a native mobile database-tab UI
- replacing a full database IDE such as DataGrip or DBeaver
Security notes
- Passwords are excluded from tab state, workspace sessions, profile summaries, and query RPC responses.
- Remembered credentials are encrypted with AES-256-GCM and bound to the saved profile ID.
- Where Electron
safeStorage is available, it protects the runtime vault key with the platform secret store.
- Headless Linux environments without a usable secret service fall back to a random key in a mode-
0600 file. This protects against accidental config disclosure and other OS users, but not compromise of the Orca Unix account; improving this fallback is a follow-up security hardening opportunity.
- A saved password is bound to its endpoint identity, preventing it from being silently forwarded after host, user, port, or TLS settings change.
Dogfood validation
The prototype has been exercised end to end with:
- a macOS desktop paired to a Linux Orca runtime
- a project routed from that runtime through its configured
ssh-p8 host
- a live PostgreSQL catalog/schema lookup and query
- password-stripped profile summaries and server-side credential resolution
- production desktop/web builds, lint, typecheck, localization checks, and the full unit test suite
Screenshots
- New-tab menu entry
- Database Query tab running in the project environment
Problem or use case
Orca's workspace is project-scoped, but database tooling proposed so far is global to the desktop app. That breaks down when the desktop is paired to a remote Orca runtime or when the project itself is an SSH worktree: a database connection opened by the desktop may not share the project's network, credentials, or host context.
A representative route is:
The database query should originate from the same environment that owns and executes the project, rather than silently dialing from the client machine.
Proposed solution
Add
New Database Queryto the existing workspace-tab menu, next to Terminal, Browser, and Markdown. A database query becomes a first-class project tab that:localor a specific SSH connection)The initial provider is PostgreSQL. The shared provider boundary is intentionally small so more engines can be added later without putting provider-specific behavior into the tab/session model.
Relationship to existing database work
This proposal is not another global database page. Its distinct user-facing and architectural goal is a project-scoped workspace tab whose execution follows the worktree runtime, including SSH worktrees. The implementations could share provider or query-grid primitives later, but the workspace integration and execution ownership solve a separate remote-development requirement.
MVP boundaries
Included:
Not included in the initial change:
Security notes
safeStorageis available, it protects the runtime vault key with the platform secret store.0600file. This protects against accidental config disclosure and other OS users, but not compromise of the Orca Unix account; improving this fallback is a follow-up security hardening opportunity.Dogfood validation
The prototype has been exercised end to end with:
ssh-p8hostScreenshots