Connections.

Engines and defaults#

Creating a connection#

New connection opens Add a connection: paste a URL or pick an engine. Inside the form, Import URL… (top right of the Connection card) fills the fields from a URL you paste and click Apply on. A saved connection can be copied with the copy-URL button, which never includes the password. The engine of a saved connection is fixed; to change it, delete and add again.

postgres://user:pass@host:5432/db?sslmode=verify-full
mysql://user:pass@host:3306/db?sslmode=verify-full
clickhouse://user:pass@host:8123/default
redis://user:pass@host:6379/0
rediss://user:pass@host:6380/0
https://user:pass@search.example.com:9200

TLS and certificates#

The Security card has one mode selector. Its label is SSL mode for PostgreSQL and MySQL, TLS for Redis and HTTPS for ClickHouse and OpenSearch.

Pick CA certificate to trust a private CA, and Client certificate plus Client key for mutual TLS. A client certificate needs its key and the other way round.

SSH tunnels#

Switch on Connect over SSH tunnel in the SSH tunnel card to reach a database on a private network through a bastion host. Fill SSH host, SSH port (default 22) and SSH user, then give at least one way to log in:

• SSH private key: paste the key text (it takes priority over a password), with a Key passphrase if it has one;
• SSH key file: a path such as ~/.ssh/id_ed25519, used when no key is pasted;
• Use the ssh-agent (SSH_AUTH_SOCK) (on Windows Plasma looks for Pageant or the OpenSSH pipe);
• SSH password.

Plasma tries every method you set. The first time it reaches a bastion it shows the host key’s SHA256 fingerprint and asks you to verify it with the server’s administrator: Trust and connect or Cancel. If a host you trusted before presents a different key, the dialog warns that the server may have been reinstalled or that someone is intercepting the connection, and the buttons become Cancel connection and Trust the new key.

Read-only, tags and the Prod gate#

These two settings are the first line of defence, and both live on the Connection card.

Test, errors and diagnosis#

Test shows the steps it went through, in order: Open the SSH tunnel (when one is set), Find the host, Reach the port, Set up TLS, Log in, and last Open the database (Redis: Select the database; OpenSearch: Check the cluster; a file: Open the file). It stops at the first step that fails and marks the rest as skipped. Each step shows how long it took.

A failure is turned into a title, a short explanation and the likely fixes, with the offending field highlighted. A Copy the error details button copies the diagnosis; secrets are removed from it first. These are the problems Plasma recognises:

Anything else is shown as Could not connect with the server’s own message.

Saved connections#

• The list is searchable (Search connections…) and grouped by Folder. In the editor, Duplicate copies a connection and Delete asks Delete connection? first.
• On the Connections home each card has Edit, Duplicate and Allow AI tools…, the last of which opens Settings at the MCP server section.
• The switcher in the top bar changes connection (or database) from anywhere, and holds Reconnect to …, Disconnect from … and New connection…. Disconnecting with staged grid edits asks first.
• Settings → General can reconnect to your last connection on launch and retry automatically after a lost connection (see Reconnecting).

Where passwords are stored#

Database passwords, SSH passwords and keys, OpenSearch keys and your AI API key are encrypted with the operating system’s secret store (macOS Keychain, Windows Credential Vault, or GNOME Keyring or KWallet on Linux) and stored as ciphertext in Plasma’s local database. The renderer process never receives a saved password back. If the system has no working secret store, Plasma refuses to save connections rather than store a password in the clear. More on Safety and privacy.

Team workspaces#

A workspace is a folder you can commit to git. It holds a .plasma/ directory with shared connection profiles, saved queries, snippets and notebooks. Open one with Open workspace folder… (File menu, the Connections home, or the command palette), or with plasma open <folder>. The home also lists Recent workspaces, each with a forget button, and a workspace section in the sidebar has a close button.

Files are written in a fixed, sorted order with no timestamps, so saving an unchanged item produces an identical file and a diff shows only real edits.

{
  "version": 1,
  "connections": [
    {
      "id": "shop-staging",
      "name": "Shop (staging)",
      "engine": "postgres",
      "tag": "staging",
      "host": "${SHOP_DB_HOST}",
      "port": 5432,
      "database": "shop",
      "user": "${SHOP_DB_USER:-app}",
      "tlsMode": "verify-full",
      "readOnly": true
    }
  ]
}