Correct Method to Install psql Client Only on macOS

Problem Context and Requirements Analysis

Many macOS users working with PostgreSQL require only the client tool psql to connect to remote databases (such as AWS RDS), without needing a full local PostgreSQL server installation. Official documentation does not explicitly address this specific scenario, while Homebrew's postgresql package installs the complete database service, which doesn't meet user requirements.

Core Solution: Using the libpq Package

Installing the libpq package via Homebrew is the optimal solution for this problem. This package specifically provides PostgreSQL client libraries and utilities without including the database server components.

brew install libpq

After installation, users gain access to psql, pg_dump, and other PostgreSQL client utilities. These tools offer identical functionality to their counterparts in a full PostgreSQL installation, enabling users to connect to remote databases, execute queries, backup data, and perform other routine operations.

PATH Configuration Issues and Solutions

Since the libpq package provides the same utilities as the full postgresql package, Homebrew installs it in "keg-only" mode, meaning these tools are not automatically added to the system's PATH environment variable. Users must manually configure access to use these commands directly.

Method 1: Modifying PATH Environment Variable

The most recommended solution involves adding libpq's binary directory to the user's PATH environment variable. For users employing zsh shell (the default in macOS Catalina and later versions), execute the following command:

echo 'export PATH="/usr/local/opt/libpq/bin:$PATH"' >> ~/.zshrc

After executing this command, reload the shell configuration or open a new terminal window for the changes to take effect:

source ~/.zshrc

This approach maintains system cleanliness while ensuring psql and other tools remain available across all terminal sessions.

Method 2: Creating Symbolic Links

An alternative solution involves creating symbolic links for required tools to system paths. For example, creating a link specifically for psql:

ln -s /usr/local/Cellar/libpq/<version>/bin/psql /usr/local/bin/psql

Note that <version> should be replaced with the actual installed version number. Users can determine the exact installation path using:

brew info libpq

This method suits users who need only specific tools, avoiding modification of global environment variables.

Method 3: Force Linking (Not Recommended)

Homebrew provides a force linking option to link all binaries to system paths:

brew link --force libpq

However, this method has significant drawbacks: if users later need to install the full postgresql package, conflicts may arise. Therefore, unless certain that a full PostgreSQL installation won't be needed in the future, this approach is not recommended.

Comparison with Other Installation Methods

Referencing official documentation, several other methods exist for installing PostgreSQL on macOS:

• EDB Official Installer: Provides graphical installation but installs the complete database service
• Postgres.app: Simple menu bar application that also includes the full database server
• MacPorts and Fink: Alternative package managers with similar installation processes but smaller user bases

In comparison, installing the libpq package via Homebrew is most suitable for scenarios requiring only client tools because it:

• Does not install unnecessary database service components
• Is managed through a package manager, facilitating updates and maintenance
• Integrates well with the macOS ecosystem

Practical Verification and Testing

After installation and configuration, users can verify psql functionality using:

psql --version

Example command for successfully connecting to a remote database:

psql -h your-rds-endpoint -U username -d database_name

If connection issues occur, check network connectivity, security group settings, and authentication credentials.

Conclusion

The best practice for installing only PostgreSQL client tools on macOS involves installing the libpq package via Homebrew and selecting an appropriate PATH configuration method based on personal preference. Modifying the PATH environment variable is the most recommended approach, ensuring tool availability while maintaining system maintainability. This method particularly benefits cloud database users, developers, and system administrators who require client tools to manage remote PostgreSQL instances without running local database services.