Connections, projects, sessions
Three nested ideas: connections, projects, sessions.
Connection
Section titled “Connection”A connection profile is what you’d type into a CLI client: dialect, host, port, user, password, database, optional SSH tunnel, optional TLS settings. Quay stores them at:
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/com.unclez.quay/connections.json |
| Linux | ~/.config/quay/connections.json |
Passwords stay plaintext (locked decision — the file is chmod 0600,
and a Keychain swap was deliberately not taken to keep the
edit-the-password recovery path simple). Each connection has a
required tag field — dev, staging, prod, or anything you set.
The prod tag triggers extra confirmation rules (see
Confirmation rules).
Project
Section titled “Project”A project is a folder you assign one or more connections to.
Same project, different environments — myapp/dev-pg, myapp/staging-pg,
myapp/prod-pg. Projects exist purely for visual grouping in the
left rail; nothing in the engine layer cares which project a connection
belongs to.
Move connections between projects by drag-and-drop. Delete a project to drop the grouping; the connections themselves stay (they default back to the “Unfiled” project).
Session
Section titled “Session”When you open a connection (double-click in the rail), Quay creates a session — a live, named handle on the underlying database driver. Sessions are the per-tab unit: each editor pane, schema browser, and result grid is bound to one session.
Quay keeps sessions independent across panes. Two tabs against the same connection get two sessions, two transactions, two pending-edit buffers. That’s deliberate — a long-running ANALYZE in one tab won’t freeze the editor in the other.
Internally a session is (runtime_id, profile_id, dialect, driver_handle).
The runtime_id is opaque + ephemeral, regenerated every reconnect;
profile_id stays stable across the connection’s lifetime. The
scheduler, team sync,
and cross-DB sync all key on profile_id so a reconnect doesn’t break
their wiring.
Connection vs session — when does it matter?
Section titled “Connection vs session — when does it matter?”- Disconnect from rail: drops the session. Profile + project survive.
- Edit connection settings: kills the session, re-opens against the new settings (asks first if there are pending edits).
- Tunnel drops mid-query: session goes into a “reconnecting…” state with a yellow dot on the chip. SSH keepalives auto-reconnect; a real timeout asks you to retry the query.
- App restart: sessions are not persisted. Re-open the connections you want.
What’s not in this concept
Section titled “What’s not in this concept”- Workspaces (Pro Plus): a Pro Plus team-sync feature for sharing connection profiles across team members. See Team sync.
- Saved queries (Pro Plus): connection-scoped query bookmarks.
- Per-engine deep tools: each engine has its own depth — see the Engine overview.