Getting Started

Using Postico

Troubleshooting

More Information

You are looking at the documentation for Postico v1.1.1 — would you like to go to the latest version instead?

Working with Connection Favorites

To connect to a PostgreSQL server with Postico, you must first create a favorite. The favorite window is shown on launch, but you can always bring it to the front by pressing ⌘N.

A favorite contains parameters for connecting to a server. Some connection parameters are optional. For example, if you use Postgres.app to run a local server, you can leave everything as default, just click ‘Connect’.

PostgreSQL server parameters

Host: the host name or IP address of the PostgreSQL server. Use 'localhost' to connect to a server running on your Mac.

Port: leave blank for default value of 5432.

User: leave blank to use the same as your Mac login name

Password: leave blank to have Postico prompt you for password every time you connect (if a password is required).

Save in Keychain: Check to store the password securely in your keychain. Otherwise the password will only be remembered until you quit the application.

Database: Provide the name of a database on the server to connect to. You must provide the name of a database on the server, even if you want to show a list of all databases when connecting (see below). Leave blank to use the same as the user name. If unsure, try 'postgres'.

Show All Databases

By default, Postico will open the database you chose when connecting to a server. If you'd rather see a list of all databases on the server when connecting, select the “Show All Databases” option from the gear menu.

Favorite Colors

Also in the “Options” menu, you can choose a highlight color for each favorite. When connected, the status display will be highlighted with the selected color.

SSH Tunnels

If your server is behind a Firewall, or your server doesn't support SSL, you can connect through a SSH tunnel. Just select “Connect via SSH” from the “Options” popup menu.

SSH Host: the host name or IP address of the SSH server. Can not be left blank. If the SSH server is running on the same machine as the PostgreSQL server, type the host name here, and type “localhost” in the PostgreSQL host field.

Port: leave blank for default value of 22.

User: leave blank to use the same as your Mac login name

Password: To use password authentication, provide a password.

Private Key: To use key based authentication, click the button to select a private key file. If the key is encrypted, Postico will show a prompt for the passphrase when connecting.

Sharing Favorites

Exporting Favorites

To share a connection favorite with another user of Postico, right click on it an select ‘Export Favorite…’. You have the option of including the password and query history in the favorite file. You can also choose to encrypt the stored password and query history in the favorite file.

An even more convenient way to export a favorite is to simply drag it to the Finder. Beware: The dragged file will contain the password in plain text.

Favorite files are stored in the Binary Property List format. You can convert them to XML format using the plutil program: plutil -convert xml1 example.pgfav. Postico will open files in XML format just fine, so you can easily generate Postico favorite files yourself.

Importing Favorites

To import a Postico favorite file, just drag it on the Favorites window from the Finder. You can also drag them on the Postico app icon. PG Commander favorite files are also compatible with Postico.

URL Scheme

Postico supports the PostgreSQL URL scheme. Simply click on an URL starting with postgres:// or postgresql:// to immediately connect to that server. A favorite for the server will be added automatically if it doesn't exist yet.

You can also use the URL scheme to open Postico from the command line. Try typing the following command in Terminal: open postgres://localhost

To copy an URL that corresponds to a favorite, right-click on it and choose the ‘Copy URL…’ command in the context menu.

The following URLs are recognized by Postico:

For more information about PostreSQL connection URLs, please refer to the section on connection strings in the online documentation of PostgreSQL. However, not all connection parameters are supported by Postico.

URLs are also a great way to share connection parameters with someone who isn't using Postico. You can right click on favorites to copy the connection URL.