Connections

A profile is configuration: a name, server address, database, user and connection options. A session is a live PostgreSQL connection owned by a query console, with its own transaction and session state. Saving a profile does not save a running transaction.

Create and test a profile

1. Open the quick switcher with Command+K and choose new connection.
2. Enter a recognizable name and the PostgreSQL host, port, database and user supplied by your administrator. Enter the password in the password field, not in SQL or the profile name.
3. Set TLS options to match your server’s requirements. Do not weaken certificate checks just to dismiss an error.
4. Use test connection to check the current form values. A successful test checks connectivity, not permission to run every query, and does not occupy a query-session slot.
5. Save the connection and open it from the quick switcher. Choose new query when you need another document.

Passwords are stored through the macOS Keychain, not embedded in the saved profile file. An existing profile can resolve its saved password through Keychain when the password field is empty. Denied Keychain access is not proof that credentials are missing; read the error before replacing or deleting anything.

Profiles, tabs and sessions

Dockwave supports up to 16 query documents and at most 4 live query sessions. A document may exist without a connection; once bound, its console keeps its own PostgreSQL session rather than borrowing interchangeable pooled connections.

Restored tabs remember SQL and their intended profile, but launch does not reconnect them or restore database transaction state. Run can connect an idle or disconnected tab before sending the SQL captured at that click; it does not automatically retry SQL after dispatch.

History, saved queries and restored document SQL are persisted locally. Do not put passwords or other secrets into SQL text expecting Keychain to protect that text.

SSH and connection failures

SSH tunnelling supports strict host-key verification and Keychain-backed secrets. Verify an unknown host’s fingerprint through an independent trusted channel before accepting it. Do not accept a changed key simply to make a connection succeed. The profile editor exposes the first SSH hop; this guide does not promise a multi-hop editing interface or SSH-agent support.

For authentication, TLS, timeout or unreachable-host errors, verify the current settings with your administrator. The quick switcher’s disconnect action ends that session; it is different from deleting a saved profile.

Next step

Run a safe SQL example.