Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Rails raises PG::UndefinedTable: relation "users" does not exist

ErrorPG::UndefinedTable: ERROR: relation "users" does not exist

Short answer

PostgreSQL could not find a table named users in the schemas it searches for the database Rails connected to. Check which database and environment Rails uses, then compare db:migrate:status with the real tables. Run the migrations for that environment, or fix the table name or schema if the table exists elsewhere.

  • Applies to Rails 8, PostgreSQL 17, Ruby 3.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Rails which migrations are applied in the environment that fails. Pending ones are shown as down.

    bin/rails db:migrate:status RAILS_ENV=development
  2. 2Match what you see, then jump to its fix

    1. 1db:migrate:status lists the create-table migration as downThe migration that creates the table was never run in this environmentFix
    2. 2The error appears only under bin/rails test or rspec, and the app works in developmentThe test database is behind the schemaFix
    3. 3Other tables work, but this model asks for a name you did not createThe model points at a different table name than the one that existsFix
    4. 4psql finds the table with a schema prefix (for example app.users), but Rails does notThe table is in a schema that is not on the search pathFix

What does the error look like?

  • PG::UndefinedTable: ERROR: relation "users" does not exist
  • 42P01 undefined_table

Cause 1 of 4

The migration that creates the table was never run in this environment

1Check

Compare the status list with the tables in the database. Production and test are separate databases from development, so a table can exist in one and be absent in the others.

bin/rails db:migrate:status
psql "$DATABASE_URL" -c '\dt'

2Fix

Run the pending migrations for the environment that fails. On a new database, db:prepare creates it and loads the schema.

bin/rails db:migrate
RAILS_ENV=production bin/rails db:migrate

3Verify

The status list shows every migration as up and the query works in the console.

bin/rails db:migrate:status
bin/rails runner "puts User.count"

Confirmed by guides.rubyonrails.org

Did this fix it?

Cause 2 of 4

The test database is behind the schema

1Check

The test helper tries to load db/schema.rb (or db/structure.sql) into the test database and raises when migrations are pending.

bin/rails db:migrate:status RAILS_ENV=test

2Fix

Bring the test database up to date. If you edited migrations that had already run, rebuild it.

bin/rails db:migrate RAILS_ENV=test
bin/rails test:db

3Verify

Run the test suite again.

bin/rails test

Confirmed by guides.rubyonrails.org

Did this fix it?

Cause 3 of 4

The model points at a different table name than the one that exists

1Check

Rails pluralizes the class name to find the table (User becomes users), unless the model sets its own name or a module sets a prefix.

bin/rails runner "puts User.table_name"
grep -rn "table_name" app/models

2Fix

Make the migration and the model agree: rename the table in a migration, or set the name on the model.

class User < ApplicationRecord
  self.table_name = "app_users"
end

3Verify

The printed table name matches a table in \dt.

bin/rails runner "puts User.table_name"

Confirmed by guides.rubyonrails.org

Did this fix it?

Cause 4 of 4

The table is in a schema that is not on the search path

1Check

PostgreSQL looks only in the schemas listed in search_path, which defaults to "$user", public. A table in another schema is not found by an unqualified name. Run \dt without a pattern and read the Schema column of the list.

psql "$DATABASE_URL" -c 'SHOW search_path;'
psql "$DATABASE_URL" -c '\dt'

2Fix

Move the table into a schema on the search path (you need CREATE privilege on the target schema), or change search_path for the role so the schema is included.

ALTER TABLE app.users SET SCHEMA public;

3Verify

Restart the app and run the query from the console.

bin/rails runner "puts User.count"

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • Run bin/rails db:migrate as a step of every deploy, before the new code takes traffic.
  • Commit db/schema.rb after each migration so a fresh database loads the same structure.
  • Keep one DATABASE_URL per environment and print which one is in use when debugging.
  • Do not edit a migration that already ran elsewhere; add a new one.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.