remix-run/remix · error · Error

Postgres database config requires a database name

Error message

Postgres database config requires a database name

What it means

resolvePostgresDatabaseName tries config.connectionString, config.database, then PGDATABASE to determine which database to target. If none is set it throws, because operations like maintenance-connection setup cannot proceed without a database name.

Source

Thrown at packages/data-table-postgres/src/lib/driver.ts:512

  return typeof value === 'object' && value !== null && 'query' in value
}

function isPostgresPool(client: PostgresQueryable): client is PostgresPool {
  if (client instanceof pg.Client) {
    return false
  }

  return 'connect' in client && typeof client.connect === 'function' && !('release' in client)
}

function resolvePostgresDatabaseName(config: PostgresPoolConfig): string {
  let database =
    resolveDatabaseNameFromConnectionString(config?.connectionString) ??
    config?.database ??
    process.env.PGDATABASE

  if (!database) {
    throw new Error('Postgres database config requires a database name')
  }

  return database
}

function replaceDatabaseInConnectionString(
  connectionString: string | undefined,
  database: string,
): string | undefined {
  if (!connectionString) {
    return undefined
  }

  let url: URL

  try {
    url = new URL(connectionString)
  } catch (cause) {

View on GitHub (pinned to 9696913134)

Solutions

1. Set `database` (or `connectionString`) explicitly in the PostgresPoolConfig passed to the driver
2. Export PGDATABASE in the environment where the app runs
3. Verify the .env file is loaded before the driver is constructed

Example fix

// before
new PostgresDatabase({ config: { host: 'localhost', user: 'app' } }) // throws

// after
new PostgresDatabase({ config: { host: 'localhost', user: 'app', database: 'app_db' } })

if (!config.database && !config.connectionString && !process.env.PGDATABASE) {
  throw new Error('Missing database: set config.database or PGDATABASE')
}

When it happens

Trigger: Constructing the driver with a config that has neither `database` nor `connectionString`, while PGDATABASE is unset in the environment; CI containers where PGDATABASE isn't exported; .env file not loaded in the process calling the driver.

Common situations: Local dev relying on PGDATABASE set in a shell that CI doesn't have; dotenv loaded too late or in a different process; typos like PG_DATABASE instead of PGDATABASE.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• throw new TypeError(message)
• Postgres database + method + () requires config-based const
• Postgres connection string must be a valid URL to resolve th
• throw new AssertionError({ message, actual, expected, operat
• expect(received).toThrow() requires a function (got ${typeof

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/fa06e13d03c6d9e7. Report an issue: GitHub.