How to Fix PG::ConnectionBad: Connection Refused in Rails with PostgreSQL

By the end of this page, you will understand what PG::ConnectionBad with connection refused means in Rails, how Rails uses database.yml to connect to PostgreSQL, and how to systematically check whether PostgreSQL is running, listening on the expected port, and configured correctly for your app.

PG::ConnectionBad is a PostgreSQL connection error raised by the Ruby pg driver when Rails cannot open a database connection.

In this specific case, connection refused usually means:

• Rails successfully tried to reach the machine and port you specified.
• But nothing was accepting connections there.
• In other words, PostgreSQL is likely not running, not listening on that host/port, or your Rails config points to the wrong place.

This is different from other database errors:

• authentication failed → PostgreSQL is running, but username/password is wrong.
• database does not exist → PostgreSQL is running, but the named database has not been created.
• could not translate host name → the hostname itself is invalid.
• connection refused → the service is not available at that address and port.

In Rails, the connection details typically come from config/database.yml:

• adapter: which database system to use
• database: the database name
• username / password: login credentials
• host: where PostgreSQL is running
• port: which TCP port to connect to

If Rails says it cannot connect to , the first question is not whether the gem is installed. The first question is:

Think of Rails as a customer trying to enter a building.

• host is the street address.
• port is the door number.
• PostgreSQL is the business inside.

If you get connection refused, Rails reached the address and tried the door, but nobody was there to answer.

That usually means one of these:

• the building is closed → PostgreSQL is not running
• the business moved to another door → PostgreSQL uses a different port
• you went to the wrong address → wrong host in database.yml

So the fix is usually not rewriting Rails code. It is checking the address, the door, and whether the business is open.

In Rails, a PostgreSQL database connection is commonly configured like this:

development:
  adapter: postgresql
  encoding: unicode
  database: my_app_development
  username: myuser
  password: secret
  host: localhost
  port: 5432

A more minimal version often works too:

development:
  adapter: postgresql
  encoding: unicode
  database: my_app_development
  pool: 5

If PostgreSQL is installed locally and configured with default settings, Rails may connect without explicitly setting host, port, username, or password.

Example: checking whether PostgreSQL is reachable

From your terminal, try:

psql -h localhost -p 5432 -U postgres -d postgres

Consider this Rails configuration:

development:
  adapter: postgresql
  database: my_app_development
  host: localhost
  port: 5432

When you start Rails and load a page, this is roughly what happens:

1. Rails boots the application.
2. Active Record reads config/database.yml.
3. It sees that the development environment uses PostgreSQL.
4. It asks the pg gem to open a connection to:
   • host: localhost
   • port: 5432
   • database: my_app_development
5. The operating system attempts a TCP connection to localhost:5432.
6. If PostgreSQL is listening there, the connection continues.
7. If nothing is listening there, the OS returns connection refused.
8. The pg gem raises PG::ConnectionBad.
9. Rails cannot continue because it needs the database connection.

Small troubleshooting trace

Command:

This kind of debugging appears constantly in real software work.

Local app development

A Rails app connects to PostgreSQL on your machine. If the database service is stopped after a reboot, the app fails at startup.

Team onboarding

A developer clones a project, installs dependencies, and runs the app. The code is fine, but PostgreSQL was never started or the local user/database was never created.

CI and test environments

Automated test jobs fail because the database service was not started before running migrations.

Docker or container setups

The app uses localhost, but PostgreSQL actually runs in another container and should be accessed by service name instead.

Production deployment

An app deploy succeeds, but runtime requests fail because the configured database host or port is incorrect.

In all these cases, the main skill is the same: confirm whether the service exists, is reachable, and matches the application configuration.

In real projects, developers usually treat database connectivity as a configuration and environment problem first.

Common patterns

1. Environment-specific configuration

Different environments use different databases:

development:
  adapter: postgresql
  database: my_app_development

test:
  adapter: postgresql
  database: my_app_test

2. Environment variables

Instead of hardcoding credentials, teams often use environment variables:

development:
  adapter: postgresql
  database: my_app_development
  username: <%= ENV['PGUSER'] %>
  password: <%= ENV['PGPASSWORD'] %>
  host: <%= ENV.fetch('PGHOST', 'localhost') %>
  port: <%= ENV.fetch('PGPORT', 5432) %>

1. Reinstalling gems before checking whether PostgreSQL is running

A pg gem issue and a database service issue are different things.

If you see connection refused, check the service first:

pg_isready -h localhost -p 5432

2. Assuming localhost always works

Sometimes PostgreSQL is configured to use a Unix socket or a different host.

Broken assumption:

host: localhost
port: 5432

If PostgreSQL is not listening on TCP port 5432, this fails.

3. Forgetting to create the database

Even after PostgreSQL is running, your app database may not exist yet.

Run:

bundle exec rake db:create
bundle exec rake db:migrate

4. Using an invalid or awkward database name

Your config shows:

database: metals-directory_development

Hyphens in PostgreSQL identifiers can be problematic because they often require quoting. Prefer underscores:

# Basic Rails PostgreSQL config
development:
  adapter: postgresql
  encoding: unicode
  database: my_app_development
  username: myuser
  password: secret
  host: localhost
  port: 5432

# Check whether PostgreSQL is accepting connections
pg_isready -h localhost -p 5432

# Try connecting manually
psql -h localhost -p 5432 -U postgres -d postgres

# See whether anything is listening on port 5432
lsof -i :5432

# Create app databases
bundle exec rake db:create
bundle exec rake db:migrate

What connection refused means

• Rails reached the host
• But no process accepted the connection on that port
• Usually PostgreSQL is not running, not listening on that port, or database.yml is wrong

Good troubleshooting order

1. Check that PostgreSQL is installed
2. Check that PostgreSQL is running
3. Check that it listens on localhost:5432

What does PG::ConnectionBad mean in Rails?

It means the PostgreSQL driver could not establish a connection. The exact reason depends on the rest of the message.

What does connection refused mean for PostgreSQL?

It usually means nothing is listening on the host and port Rails tried to use, such as localhost:5432.

Can this happen even if the pg gem is installed correctly?

Yes. The gem can be installed properly while PostgreSQL itself is stopped or misconfigured.

Should I always set host: localhost in database.yml?

Not always. Some local setups work better without it, especially when using local socket-based connections.

Why is Rails checking the database when I only start the server?

Rails and Active Record often check the database during boot or on the first request because the app needs schema and migration information.

Could the database name be part of the problem?

Yes. If the database does not exist or uses an awkward name such as one with hyphens, it can cause issues. Underscores are safer.

How do I know whether the problem is PostgreSQL or Rails config?

Try connecting manually with psql. If manual connection fails, the issue is probably PostgreSQL service or system configuration rather than Rails code.

What should I check first on macOS?

• Rails database.yml — This file controls how Rails connects to each environment's database.
• Active Record — Rails uses Active Record to manage database connections and queries.
• PostgreSQL service management — Starting, stopping, and checking PostgreSQL is essential for local development.
• TCP host and port — localhost and 5432 are network connection details used by the app.
• Environment variables — Real projects often move database credentials and host settings into environment variables.
• Database creation and migrations — Even after connecting successfully, the app still needs the database and schema set up.
• Authentication vs connectivity errors — These are different classes of database problems and require different fixes.