How to Fix Ruby on Rails PostgreSQL Gem Error "No pg_config trying anyway. If building fails, please try again"

If you've ever set up a Ruby on Rails application on a VPS running CentOS 7, you've likely encountered a range of installation challenges. One particularly common issue is when running bundle install fails to install the pg gem, which is essential for Rails applications that use PostgreSQL. Let’s go through this issue and the solution step-by-step.

The Problem

When running bundle install on a CentOS 7 VPS, you may encounter an error similar to the following:

No pg_config... trying anyway. If building fails, please try again with
--with-pg-config=/path/to/pg_config
checking for libpq-fe.h... no
Can't find the 'libpq-fe.h header
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.

This error usually points to missing PostgreSQL development libraries or an incorrect path to the PostgreSQL configuration file pg_config.

Why This Happens

The pg gem requires access to PostgreSQL’s development files during installation. Specifically, it looks for pg_config, a tool that provides information about PostgreSQL installation paths. Without it, the gem can't find necessary files such as libpq-fe.h. The error is often caused by one of the following:

• PostgreSQL development headers (postgresql-devel) are missing.
• The system doesn’t know where to find pg_config.
• pg_config exists, but it’s not in the system’s PATH.

Solution

Let’s tackle this issue in three steps:

1. Confirm PostgreSQL Packages Are Installed

   Make sure you have the necessary PostgreSQL development libraries installed. Run:

   
   sudo yum install postgresql94-server postgresql94-devel postgresql94-libs libpqxx libpqxx-devel
   

   This should install the required headers and libraries for PostgreSQL 9.4. Adjust the version number based on the PostgreSQL version you are using.

2. Install the pg Gem with Configuration Options

   If pg_config isn't in the system’s PATH, you need to provide its full path manually when installing the pg gem. On CentOS, pg_config is typically located in /usr/pgsql-9.4/bin/pg_config. You can install the pg gem directly using:

   
   gem install pg -- --with-pg-config=/usr/pgsql-9.4/bin/pg_config
   

   This should allow the gem to find the necessary PostgreSQL files.

3. Automate the Process with Capistrano

   If you’re using Capistrano for deployments, manually setting the pg_config path every time isn’t efficient. To streamline deployments, create a Capistrano task that configures Bundler to use the correct path for pg_config automatically.

   Add the following task to your deploy.rb file:

   
   desc "Create bundle config"
   task :prepare_bundle_config do
     on roles(:app) do
       within release_path do
         execute :bundle, 'config build.pg --with-pg-config=/usr/pgsql-9.4/bin/pg_config --local'
       end
     end
   end
   

   This task will create a ./bundle/config file for your project and add the pg_config path to the build.pg configuration. By setting it before bundler:install, you ensure Bundler uses the correct pg_config path during each deployment.

4. Update the System’s PATH (Optional)

   Another way to resolve this is by adding the pg_config directory to your system’s PATH. This way, you don’t have to specify the full path every time. Create a symbolic link to the PostgreSQL binaries with:

   
   sudo ln -s /usr/pgsql-9.4/bin/* /usr/local/bin
   

   After creating this link, your system should recognize pg_config globally, eliminating the need for the --with-pg-config option.

5. Verify Installation

   Run bundle install again to ensure the pg gem installs successfully. If everything is set up correctly, Bundler should be able to locate pg_config and install the gem without issues.

Common Pitfalls

• Outdated PostgreSQL Version: Make sure the version of PostgreSQL you’re using matches the development packages installed on your system. If you’re using PostgreSQL 9.6, for example, make sure to install postgresql96-devel instead of postgresql94-devel.
• Multiple PostgreSQL Versions: Having multiple versions of PostgreSQL installed can confuse the pg gem installation. Ensure that only one version is in your PATH or specify the exact path to pg_config for the version you intend to use.
• User Permissions: Make sure you’re running the commands as a user with sufficient permissions (usually sudo is required for installations and system-wide changes).

Conclusion

Installing the pg gem on CentOS 7 can be a bit tricky, especially when PostgreSQL headers and libraries aren’t readily available in the PATH. By ensuring the PostgreSQL development packages are installed and that pg_config is accessible, you can avoid these issues. Automating the configuration with Capistrano also simplifies the deployment process.

If you’ve followed these steps and are still encountering issues, double-check your installation paths and environment variables. With this setup, you should be able to successfully deploy your Rails application with PostgreSQL support on a CentOS 7 VPS.