# Connections & Command Line (CLI) TablePlus connects directly from your computer to your database server without making any interferences. It's end-to-end encrypted. TablePlus never sends or stores any of your data to our server. Only you get access to your data, all database credentials are safely stored on your device's Keychain. You need to prepare your **database credentials** including **database driver,** **host**, **port**, **username**, and **password** to get connected. ![](https://2743975646-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LriZ7WXXZykpg6_MQsw%2F-LryToew9T4cR7yfCgTx%2F-LrybTmaJRPPbEQ6bY6U%2Fnew%20connection.gif?alt=media\&token=4cbc0256-e5d3-4029-8ed8-e782a5a4f57c) ## Create a connection ### **Using connection form** 1. Launch TablePlus 2. From the welcome screen, click **`Create a new connection`** near the bottom 3. Choose the database driver and click **`Create`** 4. Configure your connection using standard properties such as like host, port, user credentials, etc. ![](https://2743975646-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LriZ7WXXZykpg6_MQsw%2F-Lrip6pjSe2GybyujVKR%2F-LrjC8jJKIWpgGDH29O6%2Fconnection%20form.png?alt=media\&token=8f7173a7-7562-4b3f-9782-22595c6e32cd) ### **Importing Connection URL** You can choose to import from URL, copy and paste your URL. You can find and copy the URL from your server configuration. ![](https://2743975646-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LriZ7WXXZykpg6_MQsw%2F-Lrip6pjSe2GybyujVKR%2F-LrjBjJ-5zmQkAtayyfR%2Fimport%20url.png?alt=media\&token=0012d3a5-9880-475e-a667-6acc6eb1dc9f) For example, the URL for PostgreSQL will have this structure: `postgres://user:password@host:port/database` ### **SSH Tunneling** Besides standard properties, you can configure over SSH by entering your credentials or importing an SHH private key. TablePlus has a built-in native SSH. When you use SSH config, you need to tick on **`Use SSH key`**. TablePlus will use the **`~/.ssh/config`** when you leave the private key empty. ![](https://2743975646-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LriZ7WXXZykpg6_MQsw%2F-Lrip6pjSe2GybyujVKR%2F-LrjCKqhgaODMN27Ri1h%2Fconnection%20form%20with%20ssh.png?alt=media\&token=26595b19-2554-41bf-b749-3342c5ed0021) {% hint style="info" %} If you have a problem connecting via SSH, enable the SSH debug log (navigate to the menu **`Help` > `Enable SSH Debug Log`**) then send the log to ****. It will help us troubleshoot faster. {% endhint %} ### **Connection colors** When you create a new connection, you can assign a color to the connection. This will help differentiate the connections, production vs staging for example. You can change the color by clicking on the connection status when you are connecting to it, or edit the connection form on the welcome screen. ### **Connection tags** You need to assign a tag to each connection during the creation. There are 5 current tags to use: | Tag | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | | Local | | | Testing | | | Development | | | Staging | | | Production | ## Saved Connections ### **On startup** Normally, when you start TablePlus, it shows the welcome screen with a list of saved connections. After connecting to a database, the connection will be saved into your favorite list on the right side of the welcome screen. Double-click on a saved connection to open it. ![Welcome screen with saved connections](https://2743975646-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LriZ7WXXZykpg6_MQsw%2F-Lrip6pjSe2GybyujVKR%2F-Lrj498maSSWuuAmHufY%2Fwelcome%20screen.png?alt=media\&token=0b3fb7bf-d27d-419b-92cd-f6ded885551f) {% hint style="info" %} Please be noted that TablePlus doesn't sync connection credentials to the cloud, but saves it securely in your computer's Keychain. See our [Privacy Policy](https://tableplus.com/privacy). {% endhint %} ### Edit a saved connection To edit a saved connection in TablePlus, right-click on the connection and choose **`Edit...`** ### Restore the last session You can config TablePlus to reopen the workspaces you were working on from the last session. To do this: * Go to TablePlus Preferences Setting (**`⌘ + ,`**) * From General Preferences tab, tick on the option **`Reopen closed workspaces at startup`** at the Application section. ### **Command Line (CLI or deeplink)** #### **Open connection from Terminal** You have to prepare the connection URL, you can get this by right-clicking on a connection in TablePlus and choose **`Copy as URL`**. * All values must be URL encoded * Supported parameteres: statusColor: color of the status bar. Ex: statusColor=007F3D env: enviroment tag name. Ex: env=production name: name of the connection. Ex: name=test windowMode: the window mode (tabbed or standalone window). Ex: windowMode=tabbed, windowMode=isolated tLSMode: TLS mode. Ex: tLSMode=0 usePrivateKey: use SSH private key. Ex: usePrivateKey=true safeModeLevel: Safe mode level. Ex: safeModeLevel=0 advancedSafeModeLevel: advanced safe mode level. Ex advancedSafeModeLevel=0 driverVersion: the version of driver. Ex: driverVersion=0 lazyload: enable lazy load items in all schema. Ex: lazyload=true schema: schema name. Ex: schema=public table or view: item name. Ex: table=comments operation (or operator): the operation for the filter. Ex: operation=Contains column: the column name for the filter: Ex: column=id value: the value of the column for the filter. Ex value=Love condition (or raw or query): if you want to filte with multiple columns or with raw query. Ex: condition=id%3D29%20OR%20id%20%3D%2028\ \ Again all values must be URL encoded \ Examples: From the Terminal, run: `open -a TablePlus "url"` and hit return.\ \ `open -a TablePlus "postgresql://postgres@127.0.0.1/tools"` **Open connection from Terminal with a query or filter (row level) :** * With operation `open -a TablePlus "postgresql://postgres@127.0.0.1/tool?schema=public&name=comments&column=content&operation=contains&value=test"` * With raw query `open -a TablePlus "postgresql://postgres@127.0.0.1/tool?schema=public&name=comments&raw=id%3D29%20OR%20id%20%3D%2028"` ## Connection Group You can organize database connections into groups. For example, Project A, Project B, or Production Group, Staging group, etc. ### **Create a new group** * From the welcome screen, right-click and choose **`New group...`** * Set the group name and icon and save it. To add a connection to a connection group, drag and drop it into the group. To remove a connection from the group, drag the connection out of the group. ### **Edit & delete group** * **To edit the connection group**: Right click on the group and choose **`Edit...`** * **To delete the connection group**: Right click on the group and choose **`Delete`** ## **Export & Import Connections** In TablePlus, you can quickly export and import one or multiple connections using a TablePlus connection file. This can be incredibly helpful when you need to quickly share the connections between multiple devices. ### **Export connection** You can export group name, image, and connection's information into a local file: * Right-click on the group and choose **`Export Connections`** * Choose **`Export all...`** to export all saved connections, or * Choose **`Export this group...`** to export all connections within the selected connection group, or * Choose **`Export this connections...`** to export one selected connection only. * Choose to include/exclude database passwords and server passwords in the export file. * Set a password for the export file and hit **`Export`**. TablePlus will export the connection information into a dump file with **`.tableplusconnection`** extension. ### **Import connection** You can import group name, image, and connection's information from a local file: * Right-click on the welcome screen, choose **`Import Connections...`** * Choose the connection file, enter the password (if required) * Hit **`Import`** {% hint style="info" %} If you need to sync connections between devices, it's not supported yet but we will add syncing via the private cloud (iCloud, Dropbox, Google Drive) soon. For now, you can export connections from one device, send the connection file to the other device, and import connections. {% endhint %} ## **Switch Connection** When connected to a database, to show the list of connections and make a switch, click on the Connections button on the top left panel, or use the shortcut key **`⌘ + ⇧ + K`**. ## Keep connection alive By default, TablePlus will ping the servers every 30 seconds to keep the connection active and avoid being disconnected. If you want to turn this off: * In the Settings/Preferences dialog (**`⌘ + ,`**), go to General tab * Untick the **`Keep connection alive`** to disable it.