remix-run/remix · error · Error

Postgres database + method + () requires config-based const

Error message

Postgres database  + method + () requires config-based construction

What it means

Some Postgres driver methods (those needing a database name from config, like maintenance/wipe operations) only work when the driver was constructed with a config object. If the driver was constructed from a pool or client instance instead, this internal config is absent and #configOrThrow throws.

Source

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

      }
    } finally {
      releaseQueue()
    }
  }

  async #closePool(): Promise<void> {
    this.#transactions.clear()
    // pg pools reject end() when called twice, so ending must be tracked to
    // keep close() idempotent.
    if (isPostgresPool(this.#client) && !this.#poolClosed) {
      this.#poolClosed = true
      await this.#client.end()
    }
  }

  #configOrThrow(method: string): PostgresPoolConfig {
    if (!this.#config) {
      throw new Error('Postgres database ' + method + '() requires config-based construction')
    }

    return this.#config
  }

  #assertNoOpenTransactions(method: string): void {
    if (this.#transactions.size > 0) {
      throw new Error('Postgres database cannot ' + method + ' while transactions are open')
    }
  }

  #maintenanceConfig(targetDatabase: string): PostgresClientConfig {
    let maintenanceDatabase = this.#maintenanceDatabase

    if (maintenanceDatabase === targetDatabase) {
      maintenanceDatabase = targetDatabase === 'postgres' ? 'template1' : 'postgres'
    }

View on GitHub (pinned to 9696913134)

Solutions

1. Construct the driver with a PostgresPoolConfig object (location/database/credentials) for the operations that need it
2. Pass an explicit database name via config so the method can proceed
3. For tests, create a config-based driver against a disposable database instead of injecting a pool

Example fix

// before
let db = new PostgresDatabase({ pool: sharedPool })
await db.wipe() // throws

// after
let db = new PostgresDatabase({ config: { host: 'localhost', database: 'test' } })
await db.wipe()

let needsConfig = !db.hasConfig // or track construction mode yourself
if (needsConfig) throw new Error('Create a config-based driver before calling wipe')

When it happens

Trigger: Creating PostgresDatabase from an existing pg Pool/client (dependency injection for tests) and then calling a config-requiring method such as wipe()/dropDatabase-related helpers named in the message.

Common situations: Test suites injecting a mock or shared pool, then calling wipe() between tests; reusing a connected client for convenience and later needing destructive/admin operations.

Related errors

• SQLite database + method + () requires config-based constru
• Unknown transaction token: + token.id
• Postgres database cannot + method + while transactions are
• Postgres database config requires a database name
• Postgres connection string must be a valid URL to resolve th

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