{"record":{"id":"f7ce7f7d3e5552fb","repo":"cube-js/cube","slug":"unable-to-connect-to-the-database-poolname","errorCode":null,"errorMessage":"Unable to connect to the database (${poolName}): ${message}","messagePattern":"Unable to connect to the database \\((.+?)\\): (.+?)","errorType":"exception","errorClass":"ConnectionError","httpStatus":null,"severity":"critical","filePath":"packages/cubejs-postgres-driver/src/PostgresDriver.ts","lineNumber":183,"sourceCode":"    this.pool.on('factoryDestroyError', (err) => this.databasePoolError(err));\n\n    this.config = <Partial<Config>>{\n      ...this.getInitialConfiguration(dataSource, preAggregations),\n      executionTimeout: getEnv('dbQueryTimeout', { dataSource, preAggregations }),\n      exportBucketCsvEscapeSymbol: getEnv('dbExportBucketCsvEscapeSymbol', { dataSource, preAggregations }),\n      ...config,\n    };\n    this.enabled = true;\n  }\n\n  protected async createConnection(poolConfig: PgClientConfig, poolName: string): Promise<PgClient> {\n    const client = new PgClient(poolConfig);\n    client.on('error', (err) => this.databasePoolError(err));\n\n    try {\n      await client.connect();\n    } catch (e: unknown) {\n      throw new ConnectionError(e as Error, poolName);\n    }\n\n    return client;\n  }\n\n  protected primaryKeysQuery(conditionString?: string): string | null {\n    return `SELECT\n      columns.table_schema as ${this.quoteIdentifier('table_schema')},\n      columns.table_name as ${this.quoteIdentifier('table_name')},\n      columns.column_name as ${this.quoteIdentifier('column_name')}\n    FROM information_schema.table_constraints tc\n    JOIN information_schema.constraint_column_usage AS ccu USING (constraint_schema, constraint_name)\n    JOIN information_schema.columns AS columns ON columns.table_schema = tc.constraint_schema\n      AND tc.table_name = columns.table_name AND ccu.column_name = columns.column_name\n    WHERE constraint_type = 'PRIMARY KEY' AND columns.table_schema NOT IN ('pg_catalog', 'information_schema', 'mysql', 'performance_schema', 'sys', 'INFORMATION_SCHEMA')${conditionString ? ` AND (${conditionString})` : ''}`;\n  }\n\n  protected foreignKeysQuery(conditionString?: string): string | null {","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-postgres-driver/src/PostgresDriver.ts#L165-L201","documentation":"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.","triggerScenarios":"Constructing a PostgresDriver (constructor -> createConnection) where `client.connect()` fails: unreachable host/port, wrong credentials, DNS resolution failure, or SSL requirement not satisfied.","commonSituations":"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.","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)."],"exampleFix":"// before\nCUBEJS_DB_HOST=wrong-host.example.com\n// after\nCUBEJS_DB_HOST=postgres.internal\nCUBEJS_DB_PORT=5432\nCUBEJS_DB_SSL=true","handlingStrategy":"retry","validationCode":"const net = require('net');\nfunction assertReachable(host, port) {\n  return new Promise((ok, fail) => {\n    const s = net.connect(port, host, () => { s.destroy(); ok(); });\n    s.on('error', fail);\n  });\n}\nawait assertReachable(process.env.CUBEJS_DB_HOST, +process.env.CUBEJS_DB_PORT);","typeGuard":null,"tryCatchPattern":"try {\n  await driver.testConnection();\n} catch (e) {\n  console.error(`DB connect failed (${e.message}). Check CUBEJS_DB_* env vars and network/SSL.`);\n  await new Promise(r => setTimeout(r, backoff));\n  // retry with exponential backoff for transient network issues\n}","preventionTips":["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."],"tags":["postgres","connection","configuration","network"],"backgroundTag":"database-connection-failed","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}