{"record":{"id":"d7f0bdc9c4aad37b","repo":"apache/seatunnel","slug":"connect-database-failed","errorCode":"CONNECT_DATABASE_FAILED","errorMessage":"open() failed.","messagePattern":"open\\(\\) failed\\.","errorType":"error_code","errorClass":"JdbcConnectorException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/JdbcInputFormat.java","lineNumber":121,"sourceCode":"\n    /**\n     * Connects to the source database and executes the query\n     *\n     * @param inputSplit which is ignored if this InputFormat is executed as a non-parallel source,\n     *     a \"hook\" to the query parameters otherwise (using its <i>parameterId</i>)\n     * @throws IOException if there's an error during the execution of the query\n     */\n    public void open(JdbcSourceSplit inputSplit) throws IOException {\n        try {\n            splitTableSchema = tables.get(inputSplit.getTablePath()).getTableSchema();\n            splitTableId = inputSplit.getTablePath().toString();\n\n            statement = chunkSplitter.generateSplitStatement(inputSplit, splitTableSchema);\n            resultSet = statement.executeQuery();\n            hasNext = resultSet.next();\n        } catch (SQLException se) {\n            cleanupAfterOpenFailure(se);\n            throw new JdbcConnectorException(\n                    JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED,\n                    \"open() failed.\" + se.getMessage(),\n                    se);\n        } catch (RuntimeException runtimeException) {\n            cleanupAfterOpenFailure(runtimeException);\n            throw runtimeException;\n        }\n    }\n\n    private void cleanupAfterOpenFailure(Throwable openException) {\n        boolean shouldDiscardConnection = statement == null;\n        try {\n            close();\n        } catch (IOException cleanupException) {\n            openException.addSuppressed(cleanupException);\n            shouldDiscardConnection = true;\n        } finally {\n            if (shouldDiscardConnection) {","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/JdbcInputFormat.java#L103-L139","documentation":"JdbcInputFormat.open executes the split's generated SELECT statement (statement.executeQuery) and any SQLException aborts the reader with JdbcConnectorException CONNECT_DATABASE_FAILED. It first runs cleanupAfterOpenFailure to release the statement/resultSet, then fails the task. The thrown message appends the driver's SQLException text.","triggerScenarios":"Any SQLException while opening the split query: connection dropped after establishment, split statement generation produced invalid SQL (e.g. stale snapshot boundaries), insufficient privileges, or the referenced table/columns no longer exist.","commonSituations":"Database restarted or firewall dropped the idle connection between connection establishment and query execution, table dropped by another job between split enumeration and read, missing SELECT grant, dialect generating unsupported SQL for a specific split (e.g. limit/offset syntax).","solutions":["Check the wrapped SQLException message for the root cause (connection reset vs syntax vs permission)","Verify the source table still exists and the configured user has SELECT privileges","Test the same query manually with the JDBC driver against the database","Check network stability/firewall idle timeouts; consider connection validation and reconnect settings","If triggered during restore (testRestoreOnlyAssignReturnedSplits path), confirm checkpoint/restore data still matches the current table schema"],"exampleFix":"// before\nurl = \"jdbc:mysql://db:3306/mydb\" // user lacks SELECT on public.users\n// after\nGRANT SELECT ON mydb.public_users TO 'seatunnel'@'%';","handlingStrategy":"retry","validationCode":"// pre-flight: verify connectivity and query before the job\ntry (Connection c = DriverManager.getConnection(url, user, pass);\n     Statement s = c.createStatement()) {\n    s.executeQuery(\"SELECT 1 FROM \" + tablePath + \" LIMIT 1\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    source.open(split);\n} catch (JdbcConnectorException e) {\n    if (e.getErrorCode() == JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED) {\n        // retry with backoff after checking DB health\n        retry(() -> source.open(split));\n    } else {\n        throw e;\n    }\n}","preventionTips":["Pre-flight SELECT 1 and a sample query before job submission","Enable connection keepalive / validation queries in the JDBC url","Grant SELECT to the SeaTunnel user up front","Check DB uptime/maintenance windows before long-running reads"],"tags":["jdbc","connection","sql"],"backgroundTag":"connection-refused","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}