Fix PG::ConnectionBad: could not connect to server: No such file or directory in Rails

This error occurs when Rails cannot connect to PostgreSQL because the server is not running, the socket file is missing, or the connection parameters are incorrect. Fix it by starting PostgreSQL, verifying the socket path or switching to TCP connections, and checking your database.yml configuration matches your PostgreSQL setup.

Reading the Stack Trace

Here's what each line means:

• Is the server running locally and accepting connections on Unix domain socket "/var/run/postgresql/.s.PGSQL.5432"?: PostgreSQL is configured to use a Unix socket, but the socket file does not exist, meaning PostgreSQL is not running or uses a different socket path.
• lib/active_record/connection_adapters/postgresql_adapter.rb:98:in `connect': ActiveRecord's PostgreSQL adapter attempted to open a connection and failed.
• lib/active_record/connection_adapters/abstract/connection_pool.rb:622:in `new_connection': The connection pool tried to create a new connection because no existing connections were available.

Common Causes

# database.yml
default: &default
  adapter: postgresql
  encoding: unicode
  pool: 5

development:
  <<: *default
  database: myapp_development
# PostgreSQL is not running: brew services list shows postgresql -> stopped

# PostgreSQL socket is at /tmp/.s.PGSQL.5432
# But database.yml has no host specified, defaulting to /var/run/postgresql/
default: &default
  adapter: postgresql
  database: myapp_development

# docker-compose.yml service is called 'postgres'
# database.yml uses:
default: &default
  adapter: postgresql
  host: localhost  # Wrong in Docker

The Fix

Configure database.yml to read connection parameters from environment variables, making it work across local development, Docker, and production. Setting an explicit host forces a TCP connection instead of relying on the Unix socket path.

# database.yml
default: &default
  adapter: postgresql
  encoding: unicode
  pool: 5

development:
  <<: *default
  database: myapp_development

# database.yml
default: &default
  adapter: postgresql
  encoding: unicode
  pool: <%= ENV.fetch('RAILS_MAX_THREADS', 5) %>
  host: <%= ENV.fetch('DB_HOST', 'localhost') %>
  port: <%= ENV.fetch('DB_PORT', 5432) %>
  username: <%= ENV.fetch('DB_USERNAME', 'postgres') %>
  password: <%= ENV.fetch('DB_PASSWORD', '') %>

development:
  <<: *default
  database: myapp_development

test:
  <<: *default
  database: myapp_test

production:
  <<: *default
  database: myapp_production
  url: <%= ENV['DATABASE_URL'] %>

Testing the Fix

require 'rails_helper'

RSpec.describe 'Database connection' do
  it 'connects to the database successfully' do
    expect(ActiveRecord::Base.connection).to be_active
  end

  it 'can execute a simple query' do
    result = ActiveRecord::Base.connection.execute('SELECT 1 AS one')
    expect(result.first['one']).to eq(1)
  end

  it 'uses the correct adapter' do
    adapter = ActiveRecord::Base.connection.adapter_name
    expect(adapter).to eq('PostgreSQL')
  end
end

Run your tests:

rspec

Pushing Through CI/CD

git checkout -b fix/pg-connection-config,git add config/database.yml,git commit -m "fix: use environment variables for database configuration",git push origin fix/pg-connection-config

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: myapp_test
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true
      - run: bundle exec rails db:create db:migrate
        env:
          DB_HOST: localhost
          DB_PORT: 5432
          DB_USERNAME: postgres
          DB_PASSWORD: postgres
          RAILS_ENV: test
      - run: bundle exec rspec
        env:
          DB_HOST: localhost
          DB_PORT: 5432
          DB_USERNAME: postgres
          DB_PASSWORD: postgres
          RAILS_ENV: test

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

gem install bugstack

require 'bugstack'

Bugstack.init(api_key: ENV['BUGSTACK_API_KEY'])

Deploying the Fix (Manual Path)

1. Start PostgreSQL with brew services start postgresql or sudo systemctl start postgresql.
2. Set the required environment variables (DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD).
3. Open a pull request with the updated database.yml.
4. Have a teammate review to ensure no credentials are committed.
5. Merge to main and verify database connectivity in staging.

Frequently Asked Questions