cube-js/cube · critical · ConnectionError

Unable to connect to the database (${poolName}): ${message}

Error message

Unable to connect to the database (${poolName}): ${message}

What it means

PostgresDriver.createConnection attempts to establish a new pg client connection for the named pool; any failure during `client.connect()` is wrapped in a ConnectionError with the pool name and underlying message. It surfaces TCP/DNS/auth/TLS failures at pool construction time rather than at query time.

Source

Thrown at packages/cubejs-postgres-driver/src/PostgresDriver.ts:183

    this.pool.on('factoryDestroyError', (err) => this.databasePoolError(err));

    this.config = <Partial<Config>>{
      ...this.getInitialConfiguration(dataSource, preAggregations),
      executionTimeout: getEnv('dbQueryTimeout', { dataSource, preAggregations }),
      exportBucketCsvEscapeSymbol: getEnv('dbExportBucketCsvEscapeSymbol', { dataSource, preAggregations }),
      ...config,
    };
    this.enabled = true;
  }

  protected async createConnection(poolConfig: PgClientConfig, poolName: string): Promise<PgClient> {
    const client = new PgClient(poolConfig);
    client.on('error', (err) => this.databasePoolError(err));

    try {
      await client.connect();
    } catch (e: unknown) {
      throw new ConnectionError(e as Error, poolName);
    }

    return client;
  }

  protected primaryKeysQuery(conditionString?: string): string | null {
    return `SELECT
      columns.table_schema as ${this.quoteIdentifier('table_schema')},
      columns.table_name as ${this.quoteIdentifier('table_name')},
      columns.column_name as ${this.quoteIdentifier('column_name')}
    FROM information_schema.table_constraints tc
    JOIN information_schema.constraint_column_usage AS ccu USING (constraint_schema, constraint_name)
    JOIN information_schema.columns AS columns ON columns.table_schema = tc.constraint_schema
      AND tc.table_name = columns.table_name AND ccu.column_name = columns.column_name
    WHERE constraint_type = 'PRIMARY KEY' AND columns.table_schema NOT IN ('pg_catalog', 'information_schema', 'mysql', 'performance_schema', 'sys', 'INFORMATION_SCHEMA')${conditionString ? ` AND (${conditionString})` : ''}`;
  }

  protected foreignKeysQuery(conditionString?: string): string | null {

View on GitHub (pinned to 7d981676b3)

Solutions

Verify CUBEJS_DB_HOST, CUBEJS_DB_PORT, CUBEJS_DB_USER, CUBEJS_DB_PASSWORD, CUBEJS_DB_NAME env variables.
Test reachability: `psql -h <host> -p <port> -U <user> -d <db>` or `nc -vz host port`.
Set CUBEJS_DB_SSL=true if the database requires TLS (e.g., cloud-managed Postgres).
Read the wrapped `${message}` in the error for the root cause (ECONNREFUSED vs auth vs TLS).

Example fix

// before
CUBEJS_DB_HOST=wrong-host.example.com
// after
CUBEJS_DB_HOST=postgres.internal
CUBEJS_DB_PORT=5432
CUBEJS_DB_SSL=true

Defensive patterns

Strategy: retry

Validate before calling

const net = require('net');
function assertReachable(host, port) {
  return new Promise((ok, fail) => {
    const s = net.connect(port, host, () => { s.destroy(); ok(); });
    s.on('error', fail);
  });
}
await assertReachable(process.env.CUBEJS_DB_HOST, +process.env.CUBEJS_DB_PORT);

Try / catch

try {
  await driver.testConnection();
} catch (e) {
  console.error(`DB connect failed (${e.message}). Check CUBEJS_DB_* env vars and network/SSL.`);
  await new Promise(r => setTimeout(r, backoff));
  // retry with exponential backoff for transient network issues
}

Prevention

Validate CUBEJS_DB_HOST/PORT/USER/PASSWORD/NAME in deployment config.
Run a connectivity check (psql/nc) in your container entrypoint.
Enable CUBEJS_DB_SSL=true for cloud-managed Postgres.
Inspect the inner message to distinguish refused vs auth vs DNS failures.

When it happens

Trigger: Constructing a PostgresDriver (constructor -> createConnection) where `client.connect()` fails: unreachable host/port, wrong credentials, DNS resolution failure, or SSL requirement not satisfied.

Common situations: Wrong CUBEJS_DB_HOST/PORT/USER/PASSWORD env values; database not running or behind a firewall; database requires SSL but CUBEJS_DB_SSL is not set; Kubernetes service name typos.

Related errors

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/f7ce7f7d3e5552fb. Report an issue: GitHub.