Skip to content

Connection URLs and .pgpass

Give Alcuin a connection with a postgres:// URL, or fill in the form field by field. Either way, test it before you save it.

Connect with a URL

Section titled “Connect with a URL”
postgres://app:s3cret@db.example.com:5432/shop?sslmode=verify-full
  1. Open the launcher with ⌘⇧O on macOS or Ctrl+Shift+O on Windows and Linux.
  2. Paste the URL into the box at the top and press Connect.

Alcuin opens it as a one-off connection: it is not saved, and it counts as Local. It opens read-only, unless the URL points at this computer (localhost or a name ending .localhost, a 127.x.x.x address, or ::1). Unlock it to make changes; see Projects, environments and production. To keep it, click Save beside it in the Connections view, or fill in the form as below so you can choose its project and environment.

To fill in the form from a URL instead, open New connection, click Paste a URL to fill this in, and paste. The fields fill in, and you can change any of them before you test.

What Alcuin reads from a URL

Section titled “What Alcuin reads from a URL”
postgres://user:password@host:port/database?sslmode=…&sslrootcert=…&sslcert=…&sslkey=…
Part Becomes When it is missing
postgres:// or postgresql:// Either scheme works Required
user User postgres
password Password, saved encrypted with your system keychain Nothing is saved
host Host localhost
port Port 5432
database Database The user name
sslmode Encryption Preferred
sslrootcert, sslcert, sslkey CA certificate, Client certificate, Client key None

Alcuin reads only those parameters. Others, such as application_name, options, connect_timeout or channel_binding, are ignored.

Alcuin connects to one host. A URL that lists several hosts with ports (host1:5432,host2:5432) is refused with Invalid URL. Without ports (host1,host2) the list is read as one host name, which doesn’t resolve, so the connect fails at Reached server. Give the one host you want.

TLS and sslmode explains each sslmode and how it maps to Encryption. A misspelled mode, such as verify_full, is refused with sslmode=verify_full is not a TLS mode Postgres knows. rather than quietly turned into Preferred.

Percent-encoding

Section titled “Percent-encoding”

The user name, password and database are percent-decoded. A password with @, :, /, #, ? or % in it must be encoded in a URL, or the URL splits in the wrong place:

Character Write
@ %40
: %3A
/ %2F
# %23
? %3F
% %25

So the password p@ss#1 is written p%40ss%231. If a URL is hard to encode, fill in the form instead: the form takes the password as typed.

Fill in the form

Section titled “Fill in the form”

Open New connection from the launcher, or the + at the top of the Connections view.

Field What to enter
Project, Name Where the connection is listed and what it is called. See Projects, environments and production.
This database is Local, Development, Staging or Production. Production opens read-only.
Host, Port The server’s name or address, and its port, 5432 by default. Through an SSH tunnel, the SSH server resolves the host; see SSH tunnels.
Database The database to open. You can leave it empty and test: Alcuin connects through the server’s postgres database (or template1) and lists the databases you may connect to, to pick from. Save needs one. See Server and database.
User The role to sign in as.
Authentication Password, Password from command (see Passwords from a command), or .pgpass file (below).
Password Kept encrypted with your system keychain. Editing a saved connection, leave it blank to keep the saved one.
Encryption How TLS is used. The stricter settings add CA certificate, Client certificate and Client key. See TLS and sslmode.
Connect through SSH Click Set up to tunnel through a bastion host.
Open read-only, Stop queries after This connection’s own safety settings. See Projects, environments and production.

A saved password belongs to the server it was saved for: the host, port, user and tunnel. If you point the connection at another server, Alcuin does not send the old password there, and asks you to enter it again.

Take the password from .pgpass

Section titled “Take the password from .pgpass”

Set Authentication to .pgpass file. Alcuin then sends no saved password and reads your password file at each connect, as psql does:

# host:port:database:user:password
db.example.com:5432:shop:app:s3cret
*:5432:*:app:s3cret
  • Alcuin looks for ~/.pgpass, or the file PGPASSFILE names in the environment Alcuin started with. On Windows the file is %APPDATA%\postgresql\pgpass.conf.
  • A line matches on the Host, Port, Database and User you typed, and * matches anything.
  • Under Authentication, the form says whether a line in the file matches this connection, and when the file is missing or ignored.
  • On macOS and Linux the file must be readable by you only (chmod 600 ~/.pgpass). Otherwise it is ignored.
  • A password from the file gets the same check as a saved one: if the server asks for it in clear text or as MD5, Alcuin sends it only over a connection that checks the certificate. See TLS and sslmode.

To make a connection for each line of the file at once, see Bring your connections from another tool.

What Alcuin does not read

Section titled “What Alcuin does not read”

A connection is always what its form says. Alcuin’s engine starts without PGHOST, PGUSER, PGPASSWORD, PGSSLMODE and the other PG* variables, so a variable in your shell never changes where a connection goes; PGPASSFILE, for the password file above, is the one exception. pg_service.conf isn’t read either: copy a service’s settings into the form. Not supported yet lists what else Alcuin doesn’t do.

Test before you save

Section titled “Test before you save”

Click Test connection. Alcuin connects once, step by step, and shows how far it got.

On success you see ✓ Connected in and the time, then the server’s version, how it connected (over TLS, through the SSH tunnel or directly) and the user it signed in as.

Under the connection form: Connected in 84 ms, PostgreSQL 17.2 directly, as sam, above the Test connection, Cancel and Save buttons.

A test that connected.

On failure, a box names the step that failed, with a row of steps (SSH tunnel, Reached server, Encryption, Sign in) and the field to change outlined. Steps before the failed one worked, so leave their settings alone. Click Test again after a change, and Copy details to quote the error.

The lower part of the connection form after a failed test. The Password field is outlined in red. A box headed Couldn't sign in shows the steps Reached server and Encryption with check marks and Sign in with a cross, the message password authentication failed for user readonly_sam, and the advice to check the password. Under it are Test again and Copy details.

A test that failed at Sign in.

  1. The steps, up to the one that failed.
  2. The field to change is outlined.
  3. Test again, and Copy details.

To test a saved connection without opening it, right-click it in the launcher and choose Test connection….

If it does not connect, Connection errors by message has each message and its fix.