How to Run PostgreSQL on a Custom Port

Overview

Managing ports is vital for system security and resource management. This tutorial delves into using a custom port for PostgreSQL to enhance your database configuration management skills.

Introduction

PostgreSQL is a powerful open-source object-relational database system. By default, PostgreSQL listens to port 5432. However, there might be scenarios where running it on a different port is necessary, such as when avoiding conflicts with other services or for security reasons. In this tutorial, we’ll explore how to configure PostgreSQL to use a custom port, and discuss how to connect to the database once the changes are made.

Changing the PostgreSQL Port

To specify a custom port, you must edit the postgresql.conf file, which contains configuration settings for your PostgreSQL server. This file is typically located in PostgreSQL’s data directory. The exact path differs depending on your operating system and the method you used to install PostgreSQL.

# On a Linux system default installation, the file might be found at:
/etc/postgresql/12/main/postgresql.conf

# For a MacOS installation with Homebrew, it could be accessed with:
/usr/local/var/postgres/postgresql.conf

# On Windows, you may find it at:
C:\Program Files\PostgreSQL\12\data\postgresql.conf

Once located, open the file with your favorite text editor. To specify a new port, locate the line starting with port = 5432, and change the number to the desired port number.

# Change the following line in postgresql.conf
port = 5432
# To your custom port number
port = 5433

After saving the file, you need to restart the PostgreSQL service for the change to take effect. The method of restarting the service will again depend on your system.

# On a Linux system with systemd, you would use:
sudo systemctl restart postgresql

# On MacOS with Homebrew:
brew services restart postgresql

# On Windows, you can use the Services management console or Command Prompt:
NET STOP postgresql-x64-12 && NET START postgresql-x64-12

Connecting to PostgreSQL on a Custom Port

Once your PostgreSQL server is running on a new port, you should update your connection string in your applications or tools that access the database. Here, we use the psql command-line utility as an example.

# Connecting via psql to the server on custom port 5433
psql -h localhost -p 5433 -U yourUsername dbName

Most libraries and ORMs require you to update the database configuration to specify the port. Here’s an example in Python using the psycopg2 library:

import psycopg2

connection = psycopg2.connect(
    dbname="yourDatabase",
    user="yourUsername",
    password="yourPassword",
    host="localhost",
    port="5433"
)

Advanced Configuration (with Docker)

More complex setups may require running multiple instances of PostgreSQL or dynamic port assignments. Running several instances might be beneficial for separating different environments or for specialized configurations. For such situations, creating multiple service files or using a configuration manager might be necessary.

Additionally, when running PostgreSQL within containerized environments, such as Docker, the port configuration is typically handled in the docker-compose.yml or Dockerfile, mapping the internal port used by the container to any port on the host system.

# Example docker-compose.yml using PostgreSQL on a custom port
services:
  db:
    image: postgres
    ports:
      - "5433:5432"
    environment:
      POSTGRES_PASSWORD: yourPassword

Security Considerations

When configuring a custom port for PostgreSQL, consider the security implications. Ensure that the chosen port is properly secured by your firewall and is not publicly accessible unless absolutely necessary. Configuring these security aspects is beyond the scope of this tutorial, but you should be mindful of them when modifying the default PostgreSQL configuration.

Conclusion

Customizing the PostgreSQL port can be a useful skill in any database administrator’s toolbox. We explored how to modify PostgreSQL’s configuration to listen on a custom port, how to connect to it after the change, and took a glimpse at more advanced setups. With appropriate security measures and system management, adapting PostgreSQL to your environment needs becomes a seamless process.