How to Change the Default Port in PostgreSQL

PostgreSQL is one of the most powerful and widely used relational database management systems (RDBMS) in the world. By default, PostgreSQL listens for incoming connections on port 5432.

In this article, we will describe the process of changing the default port for PostgreSQL in detailed and step-by-step manner from basic configurations to advanced setups.

1. Where is the Default Port Defined?

The default port for PostgreSQL is specified in the Postgresql.conf configuration file. This file controls various settings for the PostgreSQL server, including the port it listens on.

• By default, the port is set to 5432, but we can change it to any other port number (within the valid range of 1024 to 65535) according to our needs.

2. Why Change the Default Port?

There are several reasons we might want to change the default port (5432) for the PostgreSQL instance:

Security

Using a non-default port can add an additional layer of "security through obscurity". While this does not replace proper security practices, it can help reduce exposure to automated attacks or unwanted traffic.

Running Multiple PostgreSQL Instances

If we want to run multiple instances of PostgreSQL on the same server (for example, development, staging, and production databases), we will need to assign different ports to each instance.

Port Conflicts

Sometimes, other services may already use port 5432 (such as another PostgreSQL instance, or a different database service). In such cases, changing the port is a simple way to avoid conflicts.

Compliance or Networking Policies

Some organizations may have specific networking policies or compliance regulations that require running database services on custom ports.

3. How to change the default port in PostgreSQL

Overall, changing the port is a simple yet effective way to manage database configurations, improve security, and run multiple instances smoothly. However, there may be times when we need to change this port. For example

• We might run multiple database instances on the same machine.
  
• We may want to enhance security by using a non-default port.

4. Steps to Change the Default Port in PostgreSQL

Locate the postgresql.conf File

The postgresql.conf file is usually located in the data directory of PostgreSQL installation. The exact location depends on how PostgreSQL was installed, but we can easily find the file by following these steps:

• Linux/Unix Systems: Common paths include /var/lib/pgsql/data or /etc/postgresql/12/main. We can also search for it using the following command:

sudo find / -name postgresql.conf

• Windows Systems: The data directory is usually located in C:\Program Files\PostgreSQL\version\data.

Edit the postgresql.conf File

Open the postgresql.conf file in a text editor of your choice:

• Linux/Unix:

sudo nano /etc/postgresql/12/main/postgresql.conf

• Windows: Use a text editor like Notepad to open the file.

Look for the following line in the configuration file. The line is commented out by default with a # symbol, meaning the default port (5432) is used

#port = 5432

Uncomment the line and change the port number to your desired value. For example, to change the port to 5433, modify the line as follows then save and close the file.

port = 5433

Restart the PostgreSQL Service

For the changes to take effect, we must restart the PostgreSQL server.

• On Linux/Unix:

sudo systemctl restart postgresql

• On Windows:

Open Services (press Windows + R, type services.msc, and hit enter). Find PostgreSQL in the list, right-click it, and select Restart. Alternatively, we can restart the PostgreSQL service from the command line:

pg_ctl -D /path/to/data/directory restart

• On macOS (using Homebrew):

brew services restart postgresql

Confirm the Port Change

To verify that PostgreSQL is listening on the new port, we can use the following command:

• On Linux/Unix:

sudo netstat -plnt | grep postgres

We should see an output like this, indicating that PostgreSQL is now listening on the new port (5433 in this example):

tcp   0   0 0.0.0.0:5433      0.0.0.0:*         LISTEN      12345/postgres

4. Testing the Connection to the New Port

After changing the port, we need to verify that PostgreSQL is accepting connections on the new port.

Connecting Using psql

We can use the psql command-line tool to connect to our PostgreSQL server. To test the new port, specify the port with the -p option:

psql -h localhost -U postgres -p 5433 -d mydatabase

Replace localhost with the PostgreSQL server's address, postgres with the PostgreSQL username, and mydatabase with the database we want to connect to.

Connecting Using a PostgreSQL GUI

If we are using a PostgreSQL GUI like pgAdmin or DBeaver, we can specify the new port in the connection settings:

In pgAdmin, go to Servers > Properties > Connection tab, and enter the new port number (e.g., 5433).

In DBeaver, when setting up a new connection, specify the port under General > Port.

5. Advanced Configuration: Using Multiple Ports

We can run multiple PostgreSQL instances on the same machine by assigning different ports to each instance. This is particularly useful in development and testing environments where we want to simulate a multi-database setup on a single host.

• Running Multiple Instances: Create a New Data Directory for the second instance (let’s call it pg2)

mkdir /var/lib/pgsql/pg2

• Initialize the new database:

sudo -u postgres initdb -D /var/lib/pgsql/pg2

• Edit the postgresql.conf file in the new data directory (/var/lib/pgsql/pg2):

sudo nano /var/lib/pgsql/pg2/postgresql.conf

• Start the new instance: You can now connect to the new instance on port 5434.

sudo pg_ctl -D /var/lib/pgsql/pg2 start

Automating PostgreSQL Instances

To run multiple PostgreSQL instances automatically, we can set up separate service files for each instance (for example, postgresql-5433 and postgresql-5434), each pointing to its respective configuration and data directory.

6. Troubleshooting Common Issues

Port Already in Use

If we attempt to start PostgreSQL and get an error like:

Could not bind to address '127.0.0.1:5433': Address already in use

This means another process is already using the port. You can use netstat or lsof to identify the process using that port:

sudo netstat -tuln | grep 5433

or

sudo lsof -i :5433

Once you identify the process, you can either stop the service or choose a different port for PostgreSQL.

Connection Refused

If you get a connection refused error after changing the port, make sure:

• The PostgreSQL service has been restarted properly.
  
• The firewall is not blocking the new port.
  
• The postgresql.conf file is configured with the correct IP addresses (check the listen_addresses parameter, which should be set to * to allow all addresses or localhost for local connections).

Authentication Errors

After changing the port, make sure we update the connection string or any client configurations to use the new port. For example, in a connection string:

postgresql://user:password@localhost:5433/mydatabase

7. Best Practices

Use Ports Above 1024

When choosing a new port for PostgreSQL, ensure that the port number is above 1024 (the range reserved for system processes and root services). This avoids conflicts with other system processes.

Update Firewall and Security Rules

If we change the port, ensure that firewall rules, security groups, and access control lists (ACLs) are updated to allow traffic on the new port.

Monitor Logs

After changing the port, monitor the PostgreSQL logs (/var/log/postgresql/postgresql.log) for any issues that may arise related to connection or performance.

Conclusion

Changing the default port in PostgreSQL is a simple process that can help improve security, resolve port conflicts, and enable running multiple instances on the same server.

Whether we are working in development, staging, or production environments, customizing the PostgreSQL port is a valuable tool for managing your database configurations.