[update] Securely Manage Remote PostgreSQL Servers with pgAdmin on Mac (

#7150)

* [update] Securely Manage Remote PostgreSQL Servers with pgAdmin on Mac OS X

updated the guide to include instructions using the inbuilt SSH tunneling in pgAdmin 4

* Add files via upload

* fix blueberry whitespace error

* Update the image file name

* removed quotes

* Rename pg-admin-open-new-window.png.jpg to pg-admin-open-welcome-window.png

* Update the image name

* copy edit and format updating

* Update index.md

* fix the blueberry check

---------

Co-authored-by: John Dutton <[email protected]>

docs/guides/databases/postgresql/securely-manage-remote-postgresql-servers-with-pgadmin-on-macos-x/index.md

@@ -6,7 +6,7 @@ description: "Use the Open-source PgAdmin Program to Securely Manage Remote Post
 authors: ["Linode"]
 contributors: ["Linode"]
 published: 2010-04-30
-modified: 2018-11-29
+modified: 2024-11-21
 keywords: ["pgadmin", "mac os x", "postgresql gui", "manage postgresql databases", "ssh tunnel"]
 license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)'
 aliases: ['/databases/postgresql/pgadmin-macos-x/','/databases/postgresql/securely-manage-remote-postgresql-servers-with-pgadmin-on-macos-x/']
@@ -18,62 +18,76 @@ tags: ["database","postgresql"]
 
 ![Securely Manage Remote PostgreSQL Servers with pgAdmin on Mac OS X](Securely_Manage_Remote_PostgreSQL_Servers_with_pgAdmin_on_Mac_OS_X_smg.jpg)
 
-pgAdmin is a free, open-source PostgreSQL database administration GUI for Microsoft Windows, Apple Mac OS X and Linux systems. It offers excellent capabilities with regard to database server information retrieval, development, testing, and ongoing maintenance. This guide will help you get up and running with pgAdmin on Mac OS X, providing secure access to remote PostgreSQL databases. It is assumed that you have already installed PostgreSQL on your Linode in accordance with our [PostgreSQL installation guides](/docs/databases/postgresql/).
+pgAdmin is a free, open-source PostgreSQL database administration GUI for Microsoft Windows, Apple Mac OS X, and Linux systems. It features capabilities with regard to database server information retrieval, development, testing, and ongoing maintenance. This guide provides steps to get you up and running with pgAdmin on Mac OS X, providing secure access to remote PostgreSQL databases.
 
-## Install pgAdmin
+## Before You Begin
 
-1.  Visit the [pgAdmin download page](https://www.pgadmin.org/download/pgadmin-4-macos/) to obtain the most recent version of the program. Save the installer to your desktop and launch it. Read the license agreement and click the "Agree" button to continue.
+1.  If you have not already done so, create a Linode account and Compute Instance. See our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides.
 
-    ![pgAdmin on Mac OS X installer license agreement dialog](pg-admin-tos.png)
+1.  Follow our [Setting Up and Securing a Compute Instance](/docs/products/compute/compute-instances/guides/set-up-and-secure/) guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access.
 
-2.  After the program has uncompressed itself, you'll see a pgAdmin icon in a Finder window. You may drag this to your Applications folder or your dock.
+1. Install PostgreSQL on your Linode using one of our [PostgreSQL installation guides](/docs/databases/postgresql/).
 
-1.  After starting pgAdmin, open a new pgAdmin window by selecting the pgAdmin logo in the menu bar and selecting "New pgAdmin 4 window..."
+{{< note >}}
+This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Linux Users and Groups](/docs/guides/linux-users-and-groups/) guide.
+{{< /note >}}
 
-    ![pgAdmin on Mac OS X menu bar icon menu](pg-admin-open-new-window.png)
+## Install pgAdmin
 
-    A new window will be displayed in your web browser with the pgAdmin interface.
+1.  Visit the [pgAdmin download page](https://www.pgadmin.org/download/pgadmin-4-macos/) to obtain the most recent version. Save the installer to your desktop and launch it. Read the license agreement and click the "Agree" to continue.
 
-## Configure SSH Tunnel
+    ![pgAdmin on Mac OS X installer license agreement dialog](pg-admin-tos.png)
 
-While PostgreSQL supports SSL connections, it is not advisable to instruct it to listen on public IP addresses unless absolutely necessary. For this reason, you'll be using the following command to create an SSH tunnel to your database server, replacing `username` with your Linux username and `remote-host` with your Linode's hostname or IP address:
+1.  After the program is installed, you'll see a pgAdmin icon in a Finder window. You may drag this to your Applications folder or your dock.
 
-    ssh -f -L 5433:127.0.0.1:5432 username@remote-host -N
+1.  Start the pgAdmin interface. A welcome page should be displayed:
 
-Although PostgreSQL uses port 5432 for TCP connections, we're using the local port 5433 in case you decide to install PostgreSQL locally later on.
+    ![pgAdmin on Mac OS X menu bar icon menu](pg-admin-open-welcome-window.png)
 
 ## Use pgAdmin
 
-1.  Launch pgAdmin and you'll be presented with a default view containing no servers. Right click "Servers" and then navigate to "Create > Server".
-
-    ![pgAdmin III default view on Mac OS X](pg-admin-new-server.png)
-
-2.  If you're having problems connecting, you may need to check PostgreSQL's configuration to ensure it accepts connections. Modify the following lines in `/etc/postgresql/9.5/main/postgresql.conf` if necessary:
-
-    {{< file "/etc/postgresql/9.5/main/postgresql.conf" aconf >}}
-listen_addresses = 'localhost'
-
-port = 5432
-
-{{< /file >}}
+1. Open **pgAdmin 4**.
+2. In the **Quick Links** section, click **Add New Server**.
+3. Under the **General** tab, enter a name for your server connection. For example: `Linode PostgreSQL`
+4. Navigate to the **Connection** tab:
+   - **Hostname/address**: `localhost`.
+     The SSH tunnel redirects this to the Linode server.
+   - **Port**: The PostgreSQL port on your Linode, typically `5432`.
+   - **Maintenance Database**: `postgres` or your database name.
+   - **Username**: Your PostgreSQL username. For example: `postgres`
+   - **Password**: The password for your PostgreSQL user.
+5. Navigate to the **SSH Tunnel** tab:
+   - **Use SSH tunneling**: Enable this option.
+   - **Tunnel host**: Your Linode's IP address.
+   - **Tinnel port**: `22` . This is the default SSH port.
+   - **Username**: Your SSH username for the Linode instance.
+   - **Authentication**: Choose `Identity file` if you are using an SSH key, or `Password` for password-based authentication.
+   - **Identity file**: If you are using an SSH key, provide the location of the private key file.
+   - **Password**: If you are using password-based authentication, enter your SSH password.
+6. Click **Save** to create the server connection.
 
+### Verify Connection
 
-    Restart PostgreSQL to activate these changes. This command may vary among different distributions:
+1. After saving the configuration, right-click your new server in **pgAdmin** and select **Connect**.
+2. If the connection is successful, you should see your databases listed in the **Servers** panel.
 
-        sudo systemctl restart postgresql
+### Troubleshooting
 
-3.  In the "Create-Server" dialog that appears, enter a name for your server.
+- **SSH Access Issues**: Ensure your Linode firewall allows port `22`.
 
-    ![Supply a local name for your server.](pg-admin-server-name.png)
+- **PostgreSQL Bind Address**:
 
-4.  In the "Connections" tab enter "localhost" for the "Host name/address" field, as you'll be connecting via your SSH tunnel, and set the port to 5433. In the username and password fields, enter the credentials you specified when setting up PostgreSQL.
+  1.  Check the PostgreSQL `postgresql.conf` file to confirm it's listening on `127.0.0.1` or `localhost`. Update `listen_addresses` if necessary:
 
-    For greater security, uncheck the "Save password" box. Click "Save" to connect to your server.
+  ```file
+  listen_addresses = 'localhost'
+  ```
 
-    ![pgAdmin new server connection settings on Mac OS X](pg-admin-server-connection-settings.png)
+  2.  Restart PostgreSQL after making changes:
 
-5.  You will be presented with a full view of the databases that your user account has access to:
+  ```command
+  sudo systemctl restart postgresql
+  ```
 
-    ![pgAdmin full database view on Mac OS X](pg-admin-database-view.png)
+- **Firewall**: Ensure PostgreSQL's port (`5432`) is open for local connections.
 
-Congratulations! You've securely connected to your remote PostgreSQL server with pgAdmin 4.