CockroachDB "ERROR: relation ... does not exist" in CI

CockroachDB returns "relation X does not exist" when a query references a table that is not present. A fresh CI cluster starts empty, so this means migrations did not run, ran against a different database, or have not finished.

What this error means

A query or test fails with "ERROR: relation \"users\" does not exist" (SQLSTATE 42P01) against a Cockroach cluster that was just started for the job.

ERROR: relation "users" does not exist
SQLSTATE: 42P01

Common causes

Migrations did not run before the query

The test step executed before the schema migration step, so the table was never created in the fresh cluster.

The query targets the wrong database

Connecting to defaultdb while migrations created tables in another database leaves the expected relation missing.

How to fix it

Run migrations before any query, in the right database

1. Create or select the target database first.
2. Apply all migrations against that database.
3. Verify the table exists before running tests.

cockroach sql --insecure --host=127.0.0.1:26257 -e "CREATE DATABASE IF NOT EXISTS app"
cockroach sql --insecure --host=127.0.0.1:26257 -d app -f migrations.sql

Point the app at the same database as migrations

Set the connection string to the database where migrations created the schema.

env:
  DATABASE_URL: postgresql://root@127.0.0.1:26257/app?sslmode=disable

How to prevent it

• Order the migration step before the test step.
• Use one database name for migrations and the app.
• Fail fast if an expected table is missing after migrating.

Related guides