Managing Connections

Create, organize, and switch database connections

Press Cmd+N anywhere in the app to open the connection form. New Connection… on the welcome window does the same, and the Import menu under it takes one from a URL, another client, an exported file, or a project folder. Saved connections fill the right side of that window under a search field, focused by Cmd+F. Until you save one, that side offers Open Sample Database instead, plus Import from Other App… when a client TablePro imports from is installed.

Welcome window

Create a connection

1. Pick a database type

   The chooser sheet groups drivers as Relational, Document, Key-Value, Analytical, Wide-Column, Cloud Native, Coordination & Config, and Other. Picking a driver badged Not Installed offers the download before the form opens. See Plugins.

2. Fill in the connection details

   Host, port, and credentials live on General. Everything else has a pane of its own; see Connection form.

3. Click Test Connection

   On success the button becomes a green checkmark and reads Connected. On failure a Connection Test Failed sheet carries the driver’s own message, and for errors the driver recognizes a diagnostic sheet appears instead, with suggested fixes and Copy Diagnostic Info.

4. Click Save & Connect

   The connection is saved and the window opens on it. Save alone keeps it without connecting.

Database type chooser

Every driver’s default port, and which of SSH tunnel, SSL/TLS, Cloudflare Tunnel, Cloud SQL Proxy, and SOCKS Proxy it accepts, is in the connection form reference.

Import from URL

Paste a connection string instead of typing the fields. Click Import from URL… in the chooser sheet footer, paste, check the parsed preview, and click Import. The form opens filled in, ready to save. Schemes, query parameters, and the +ssh form are in the Connection URL Reference.

Import from URL sheet with parsed preview

Special characters in passwords (@, #, %) need percent-encoding. p@ssword becomes p%40ssword.

Open a URL without saving anything

open "postgresql://user:pass@host:5432/dbname"

A confirmation alert names the target first. Matching a saved connection on type, host, port, database, and username reuses it; otherwise the session is temporary and never joins your connection list, and the URL’s password stays in memory rather than reaching the Keychain. Confirmation and trusted links covers Always Allow and how to revoke it.

Organize connections

The Customization pane holds a color, tags, and a group. The color tints the toolbar while the connection is open.

Color, tags and group on the Appearance section

Red for production, green for development. Set Safe Mode to Read-Only on production to block accidental writes. See Safe Mode.

	How it works
Groups	Folders in the connection list, nested up to three levels. Right-click empty space for New Group…, or a group for Rename, New Subgroup, Change Color, Move Group to…, and Delete Group. Deleting a group deletes its subgroups too and leaves the connections inside ungrouped rather than deleted
Tags	Several per connection, each with a name and color. Once any connection is tagged, a row of pills appears above the list; click to filter, and with two or more selected a Match Any / Match All menu switches between OR and AND. Clear resets it
Favorites	Hover a row and click the star, or right-click and choose Add to Favorites. Favorites gather in a section at the top, sorted alphabetically, while the connection keeps its place in its group

A connection’s group, tags, and favorite star sync through iCloud unless it is marked local only. See iCloud Sync.

Switch connections and databases

Press Ctrl+Cmd+C for Switch Connection. Whatever is already open sits at the top, and the rest are listed under the group they belong to, a nested group carrying its full path. Arrow keys move, Return switches the window to that connection, and Cmd-click opens a saved one in a window of its own. Typing searches every group at once and collapses the matches into a single list.

A footer under that list names the transport the window’s connection runs on. On an SSH tunnel or a SOCKS proxy it also carries the bytes that have crossed since the transport opened, received and sent.

The rest show their name alone. Cloudflare Tunnel, Cloud SQL Auth Proxy and Tunnel Command each run a separate binary that holds the connection end to end, a remote database file is fetched once and then read from disk, and a direct connection’s socket belongs to the database driver.

Throughput in the toolbar

The same two transports put a live figure beside the connection name in the middle of the toolbar, an arrow for whichever direction is busier and the rate: ↓145 kB/s. It reads 0 kB/s while nothing moves, which is most of the time on a database connection. A connection on any other transport has no figure there at all.

Open Database (Cmd+K) moves to another database on the same server.

Database switcher in toolbar

Leaving Database empty on MySQL, MariaDB, MongoDB, SQL Server, and ClickHouse browses every database the user can reach. PostgreSQL and Redshift need one to connect at all: use postgres (Redshift: dev) and switch with Cmd+K. To hide the rest, choose View > Filter Databases and check the ones you want; the choice is saved per connection.

Edit, delete, and where it all lives

Right-click a connection to edit or delete it, or swipe left on the row for the same two buttons. Swiping never deletes on its own. Edits apply on the next connect, and deleting removes the saved settings, nothing on the server.

Connections are stored in ~/Library/Application Support/TablePro/connections.json with their passwords in the macOS Keychain, so copying that file to another Mac restores the connections without the passwords.

Right-clicking the Dock icon lists saved connections under Open Connection.