{"record":{"id":"1131b5b6cf425556","repo":"hibernate/hibernate-orm","slug":"error-accessing-user-provided-connection-via-jdbcc","errorCode":null,"errorMessage":"Error accessing user-provided Connection via JdbcConnectionAccessProvidedConnectionImpl","messagePattern":"Error accessing user-provided Connection via JdbcConnectionAccessProvidedConnectionImpl","errorType":"exception","errorClass":"SchemaManagementException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/tool/schema/internal/DdlTransactionIsolatorProvidedConnectionImpl.java","lineNumber":52,"sourceCode":"\t}\n\n\t@Override\n\tpublic Connection getIsolatedConnection() {\n\t\treturn getIsolatedConnection(true);\n\t}\n\n\t@Override\n\tpublic Connection getIsolatedConnection(boolean autocommit) {\n\t\ttry {\n\t\t\tConnection connection = jdbcContext.getJdbcConnectionAccess().obtainConnection();\n\t\t\tif ( connection.getAutoCommit() != autocommit ) {\n\t\t\t\tthrow new SchemaManagementException( \"User-provided Connection via JdbcConnectionAccessProvidedConnectionImpl has wrong auto-commit mode\" );\n\t\t\t}\n\t\t\treturn connection;\n\t\t}\n\t\tcatch (SQLException e) {\n\t\t\t// should never happen\n\t\t\tthrow new SchemaManagementException( \"Error accessing user-provided Connection via JdbcConnectionAccessProvidedConnectionImpl\", e );\n\t\t}\n\t}\n\n\t@Override\n\tpublic void release() {\n\t\tfinal var connectionAccess = jdbcContext.getJdbcConnectionAccess();\n\t\tif( !( connectionAccess instanceof JdbcConnectionAccessProvidedConnectionImpl ) ) {\n\t\t\tthrow new IllegalStateException(\n\t\t\t\t\"DdlTransactionIsolatorProvidedConnectionImpl should always use a JdbcConnectionAccessProvidedConnectionImpl\"\n\t\t\t);\n\t\t}\n\t\ttry {\n\t\t\t// While passing the connection to the releaseConnection method might be suitable for other `JdbcConnectionAccess` implementations,\n\t\t\t// it has no meaning for JdbcConnectionAccessProvidedConnectionImpl because, in this case, the connection is wrapped\n\t\t\t// and we don't have access to it upon releasing via the DdlTransactionIsolatorProvidedConnectionImpl.\n\t\t\tconnectionAccess.releaseConnection( null );\n\t\t}\n\t\tcatch (SQLException exception) {","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/tool/schema/internal/DdlTransactionIsolatorProvidedConnectionImpl.java#L34-L70","documentation":"The user-supplied-connection isolator caught an SQLException while obtaining the connection for schema management (jdbcContext.getJdbcConnectionAccess().obtainConnection()); it is rethrown as this SchemaManagementException with the SQLException as the cause. The real failure is an ordinary connectivity problem - unreachable database, rejected credentials, missing driver, pool timeout - surfacing through the schema tool.","triggerScenarios":"Schema tooling executing with a provided connection where obtainConnection() throws: database down or not yet ready (CI containers), wrong JDBC URL after config refactors, authentication failure after credential rotation, connection pool exhausted/timeout, or 'No suitable driver' when the JDBC driver is missing from the classpath.","commonSituations":"CI pipeline starting schema export before the database container passes its healthcheck; rotated DB credentials not propagated; fat-jar packaging dropping the driver; HikariCP connectionTimeout during heavy parallel migrations.","solutions":["Unwrap and read the cause (SQLException) - it names the actual problem (URL, auth, timeout, driver).","Verify basic connectivity with a plain DriverManager.getConnection(url, user, pass) probe in the same environment.","Add a database readiness check (container healthcheck / wait-for-it) before the schema step runs.","Confirm the JDBC driver artifact is on the runtime classpath and the URL matches the driver scheme."],"exampleFix":"// before: schema export runs before the database is reachable\nnew SchemaUpdate(metadata, registry).execute(EnumSet.of(TargetType.DATABASE), ...);\n\n// after: probe first, fail with a clear message, then run schema tooling\ntry (Connection c = DriverManager.getConnection(url, user, pass)) {\n    // database is reachable\n} catch (SQLException e) {\n    throw new IllegalStateException(\"Database not ready for schema management\", e);\n}\nnew SchemaUpdate(metadata, registry).execute(EnumSet.of(TargetType.DATABASE), ...);","handlingStrategy":"try-catch","validationCode":"// Probe connectivity before any schema tooling runs\ntry (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {\n    // reachable - proceed\n} catch (SQLException e) {\n    throw new IllegalStateException(\"Database not reachable at \" + jdbcUrl + \" - aborting schema management\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    new SchemaExport(metadata).execute(targets, Action.CREATE, metadata, registry);\n} catch (SchemaManagementException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Error accessing user-provided Connection\")) {\n        Throwable cause = e.getCause(); // the SQLException: URL/auth/driver/timeout\n        // surface cause to ops dashboards; retry only after a readiness check passes\n    }\n    throw e;\n}","preventionTips":["Gate schema steps on a database healthcheck (container depends_on with health condition)","Verify JDBC URL and credentials with a startup probe independent of Hibernate","Keep the JDBC driver on the runtime classpath and fail builds that silently drop it"],"tags":["hibernate","schema-management","connection","jdbc","connectivity"],"backgroundTag":"database-connection-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}