Chapter 2

Connections

A connection is everything Rowan needs to reach a PostgreSQL server: its address, who you sign in as, and how the link is secured. Save one once and open it with a double-click.

The welcome window#

The welcome window lists your saved connections. It opens when Rowan starts with nothing to restore, and whenever you press Ctrl+Shift+K in a workspace.

On the left are Rowan's actions: Create Connection, New Group, Import from URL…, Import from File…, Open SQL File…, Backup Database… and Restore Database…. On the right are the search field and your connections.

• To open a connection, double-click it, or select it and press Enter.
• To open it in a window of its own, right-click it and choose Open in New Window.
• To find one, start typing in Search connections, or press Ctrl+F first.
• For everything else, right-click a connection: Edit…, Duplicate, Copy as URL, Move to Group, Export This Connection… and Delete.

The + button beside the search field creates a connection. The ⋯ button holds the New, Import Connection, Export Connections and Sort By menus.

Create a connection#

1. In the welcome window, choose Create Connection, or click +.
2. Fill in the fields described below. Only Host and User are required; Rowan suggests the rest.
3. Choose Test. Rowan connects and reports the result in place: a green check with the server's version, or the exact reason it couldn't connect.
4. Choose Save to keep the connection, or Connect to save it and open it at once.

Name

What the connection is called in the list and in the status pill. If you leave it empty, Rowan uses the host.

Host and port

The server's name or IP address, and its port (5432 unless your server uses another).

Database

The database to open first. You can switch databases once you're connected; see Open a database.

User

The PostgreSQL role to sign in as.

Password

The password, and where it's kept. See Passwords and the keychain.

SSL

How the connection is encrypted and checked. See SSL modes and certificates.

Over SSH

Reach the server through an SSH server. See SSH tunnels.

Tag and Status Color

Mark a connection as Local, Development, Testing, Staging or Production, with a color you can see from across the room. See Tags, colors and groups.

Safe Mode

How carefully Rowan asks before sending statements. See Safe Mode.

Read-only

Turn off editing and have the server refuse writes. See Read-only connections.

Bootstrap Commands

SQL to run each time the connection opens. See Bootstrap commands.

To change a saved connection later, right-click it in the welcome window and choose Edit…. In a workspace, choose Connection > Edit… from the menu.

Passwords and the keychain#

The menu beside the password field decides where the password comes from:

Store in Keychain

The password is saved in Windows Credential Manager, never in Rowan's own files. This is the default.

Ask Every Time

Nothing is saved. Rowan asks for the password each time you connect.

No Password

For servers that sign you in another way, such as a client certificate or a trusted local connection.

Command Line

Rowan runs a command as you connect and uses the first line it prints as the password. This suits short-lived tokens, such as aws rds generate-db-auth-token …. The command runs in the background and has 20 seconds to answer.

SSL modes and certificates#

SSL encrypts everything between Rowan and the server. Choose a mode from the SSL menu:

For the verify modes, Rowan trusts the usual public certificate authorities. If your server's certificate was signed by your own authority, choose its file in CA Certificate. If the server wants a client certificate, choose it in Client Certificate and its key in Private Key; if the key is encrypted, enter its Key Password. Each field shows its path, with Choose… beside it.

After you connect, the lock in the status pill tells you how the connection is secured. Hover over it to see whether the certificate was verified and the host name checked.

SSH tunnels#

When a server is only reachable through another machine, such as a bastion host, Rowan can connect through SSH.

1. In the connection form, turn on Over SSH.
2. Enter the SSH Host and its port (22 unless yours differs), and the SSH User.
3. Choose how to sign in with Sign In With:
   • Password: enter the SSH Password, and choose whether to store it in the keychain, ask every time, or use no password.
   • Key: choose your Private Key, and enter its Passphrase if it has one. Leave the key empty to use your SSH agent or your usual keys.
4. Set Host and Port to the database server as the SSH server sees it, often localhost or a private address.
5. Choose Test. Rowan reports the SSH step and the PostgreSQL step separately, so you can tell which one failed.

Rowan reads your ~/.ssh/config file, so host aliases, user names, ports and IdentityFile entries there work as they do in a terminal. When you choose Key without picking one, Rowan tries your SSH agent, then the keys in your config, then the usual key files.

Several connections to the same SSH server share one tunnel, and Rowan keeps it alive while you work. With Verify Full over SSH, Rowan still checks the certificate against the database server's real host name.

Host keys#

The first time you connect to an SSH server, Rowan shows its key fingerprint and asks whether to trust it. Compare the fingerprint with the one your server's administrator gave you, then choose Trust and Connect. Rowan saves the key in its own known_hosts file and doesn't ask again.

If a host key changes#

If the server's key is different from the one Rowan saved, Rowan doesn't connect. It shows a warning titled The host key for server has changed, because someone could be listening in on the connection, or the server's key was replaced.

• If the key is in Rowan's own file and your administrator confirms the new fingerprint, choose Replace Key and Connect.
• If the old key is in your own ~/.ssh/known_hosts, Rowan never changes that file. Remove the host's line yourself, for example with ssh-keygen -R "bastion.example.com", then connect again.

Tags, colors and groups#

A tag tells you at a glance which kind of server you're on. Each one brings a color and a Safe Mode level:

Choose a tag in the connection form's Tag menu; you can still change its color and Safe Mode afterward. To make your own tags, rename them or change their colors, choose Add/Remove Tags… from the same menu. Restore Default Tags brings back the five above.

In a workspace, the tag's color runs as a thin strip under the toolbar, with the tag's name at its right end, and colors the dot in the status pill. See Tags and production colors.

Groups#

• To make a group, choose New Group. Groups can hold other groups.
• To move a connection, drag it onto a group, or right-click it and choose Move to Group.
• Right-click a group for New Connection Here, New Group Inside, Rename Group, Export This Group… and Delete.
• To change the order, click ⋯ and choose Sort By > Recently Used, Name or Tag. Rowan remembers your choice.

Connection URLs#

Rowan reads and writes standard PostgreSQL connection URLs:

postgresql://app_user@db.example.com:5432/shop?sslmode=verify-full

• Import from URL… in the welcome window fills in the connection form from a URL, so you can check it before saving.
• Copy as URL, from a connection's menu, puts its URL on the clipboard. Rowan asks whether to include the password; without it, the URL is safe to share.
• From the command line: start Rowan with a URL, such as Rowan.exe "postgresql://app_user@db.example.com/shop". If it matches a saved connection, Rowan opens that one, with its saved password; otherwise it opens a one-off connection.

Besides the usual parts, Rowan understands a few extra query parameters: name, env (the tag), statusColor, safeModeLevel (0 to 4), readOnly, the SSL settings sslmode, sslrootcert, sslcert and sslkey, and schema and table to open a table straight away. Add column, operation, value and condition to open that table already filtered.

Import and export connections#

To move connections to another PC, or share them with your team, export them to a .rowanconnection file.

1. In the welcome window, click ⋯ and choose Export Connections > Export All…. To export one group or connection, right-click it and choose Export This Group… or Export This Connection….
2. To include passwords, enter a File password. Passwords are then encrypted in the file with AES-256. Leave it empty to export without passwords.
3. Choose where to save the file.

To import, choose Import from File… and pick the file. If it holds passwords, enter the password it was exported with. Without one, Rowan asks for each connection's password the first time you connect.

Bootstrap commands#

Bootstrap commands are SQL statements Rowan runs every time the connection opens, before anything else. Use them to set a search path, a role or a time zone for the session:

SET search_path TO app, public;
SET ROLE reporting;
SET TIME ZONE 'Europe/Lisbon';

Enter them in the connection form's Bootstrap Commands field, one per line. If one fails, the connection fails and Rowan tells you which command it was.

Keep-alive and timeouts#

Two options in Settings > General > Connections keep long sessions healthy:

Keep connection alive

Rowan pings the server every 30 seconds, so routers and firewalls don't drop an idle connection. If the connection is lost, the status pill says so at once, with Reconnect.

Query timeout

If a query gets no answer from the server for this long (300 seconds unless you change it), Rowan says The server is taking too long to respond and offers Wait or Reconnect. Reconnecting never sends the query again. Enter 0 to never ask.

To limit how long the server itself lets a query run, use the statement timeout.

If a connection fails#

When Rowan can't connect, it says why in plain words, both in the form's Test result and in the workspace. The most common messages:

SSH problems have their own messages, and Show Details reveals each step. See SSH errors.