{"record":{"id":"c55fb4580046e431","repo":"SonarSource/sonarqube","slug":"can-not-connect-to-database-please-check-connecti","errorCode":null,"errorMessage":"Can not connect to database. Please check connectivity and settings (see the properties prefixed by 'sonar.jdbc.').","messagePattern":"Can not connect to database\\. Please check connectivity and settings \\(see the properties prefixed by 'sonar\\.jdbc\\.'\\)\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/sonar-db-migration/src/main/java/org/sonar/db/DefaultDatabase.java","lineNumber":174,"sourceCode":"    enableSqlLogging(datasource, logbackHelper.getLoggerLevel(\"sql\") == Level.TRACE);\n  }\n\n  private HikariDataSource createHikariDataSource() {\n    HikariConfig config = new HikariConfig(extractCommonsHikariProperties(properties));\n    if (!dialect.getConnectionInitStatements().isEmpty()) {\n      config.setConnectionInitSql(dialect.getConnectionInitStatements().get(0));\n    }\n    config.setConnectionTestQuery(dialect.getValidationQuery());\n    return new HikariDataSource(config);\n  }\n\n  private void checkConnection() {\n    Connection connection = null;\n    try {\n      connection = datasource.getConnection();\n      dialect.init(connection.getMetaData());\n    } catch (SQLException e) {\n      throw new IllegalStateException(\"Can not connect to database. Please check connectivity and settings (see the properties prefixed by 'sonar.jdbc.').\", e);\n    } finally {\n      DatabaseUtils.closeQuietly(connection);\n    }\n  }\n\n  @Override\n  public void stop() {\n    if (datasource != null) {\n      datasource.close();\n    }\n  }\n\n  @Override\n  public final Dialect getDialect() {\n    return dialect;\n  }\n\n  @Override","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-db-migration/src/main/java/org/sonar/db/DefaultDatabase.java#L156-L192","documentation":"checkConnection is the connectivity probe inside DefaultDatabase.start: it obtains a java.sql.Connection from the datasource and initializes the dialect from database metadata. An SQLException here means the datasource was built but no actual connection could be obtained, and it is rethrown as this IllegalStateException pointing the user at the sonar.jdbc.* properties.","triggerScenarios":"datasource.getConnection() throws SQLException (DB unreachable, auth rejected, TLS/SSL mismatch) or dialect.init fails on metadata while starting the server.","commonSituations":"Database listening on a different host/port than configured; wrong password or locked account; DB not accepting TCP connections (listen_addresses, pg_hba.conf, SQL Server TCP/IP protocol disabled); SSL requiring encryption while the JDBC URL does not enable it.","solutions":["Check the underlying SQLException cause in the stack trace to distinguish refused-connection vs authentication vs SSL errors.","Review every sonar.jdbc.* property in sonar.properties (url, username, password, driver settings) — the message explicitly points there.","Test the exact JDBC URL from the server machine with a standalone connection (e.g. 'psql -h host -p 5432 -U sonar' or a small JDBC test) to isolate network vs config.","Fix server-side access rules: pg_hba.conf/listen_addresses for PostgreSQL, enable TCP/IP for SQL Server, open the firewall port.","Add required JDBC options to the URL (e.g. sslmode=require for PostgreSQL, encrypt=true for SQL Server) if the DB mandates TLS."],"exampleFix":"// before\nsonar.jdbc.url=jdbc:postgresql://db.internal/sonarqube\n\n// after — explicit port and ssl mode\nsonar.jdbc.url=jdbc:postgresql://db.internal:5432/sonarqube?sslmode=require","handlingStrategy":"retry","validationCode":"// verify connectivity from the server host before startup\npsql \"postgresql://$USER:$PASS@$DB_HOST:$DB_PORT/$DB\" -c 'select 1' || echo 'check sonar.jdbc.* settings'","typeGuard":null,"tryCatchPattern":"try {\n  checkConnection();\n} catch (IllegalStateException e) {\n  // inspect SQLException cause: refused vs auth vs ssl, then fix sonar.jdbc.* and restart\n}","preventionTips":["Include explicit port and required TLS options in sonar.jdbc.url.","Align server-side access rules (pg_hba.conf, SQL Server TCP/IP) with the app host.","Monitor DB availability with health checks so outages are caught before startup.","Rotate credentials via secrets management to avoid stale passwords."],"tags":["database","jdbc","connectivity","sonarqube","configuration"],"backgroundTag":"connection-refused","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}