jd-opensource/joyagent-jdgenie · error · JdbcBizException

数据库联通测试失败:

Error message

数据库联通测试失败:

What it means

JdbcDataProvider.queryForTest() attempts to open a physical JDBC connection using the request's connection config (with retries forced to 1) and wraps any failure in JdbcBizException '数据库联通测试失败:<cause>'. It is a connectivity smoke-test: any connection-level error (bad host, credentials, driver, timeout) surfaces here.

Solutions

1. Read the appended cause message and fix the underlying connection issue (host, port, username, password, database name)
2. Verify network reachability (telnet/nc to host:port) and firewall/security-group rules
3. Confirm the JDBC driver dependency for the target database is on the classpath and the URL driver class matches
4. Increase connectTimeout/socketTimeout appropriately and retry after confirming the DB is up

Example fix

// before
JdbcConnectionConfig cfg = new JdbcConnectionConfig();
cfg.setUrl("jdbc:mysql://localhost:3306/mydb");
cfg.setUsername("root");
// password missing
provider.queryForTest(request);
// after
JdbcConnectionConfig cfg = new JdbcConnectionConfig();
cfg.setUrl("jdbc:mysql://localhost:3306/mydb");
cfg.setUsername("root");
cfg.setPassword("correct-password");
cfg.setConnectTimeoutMs(5000);
provider.queryForTest(request);

JdbcConnectionConfig c = request.getJdbcConnectionConfig();
if (c == null || isBlank(c.getUrl()) || isBlank(c.getUsername()) || isBlank(c.getPassword()))
    throw new IllegalArgumentException("url, username and password are required");
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(hostFrom(c.getUrl()), portFrom(c.getUrl())), 3000);
} catch (IOException e) {
    throw new IllegalStateException("Host unreachable: " + hostFrom(c.getUrl()), e);
}

try {
    boolean ok = provider.queryForTest(request);
} catch (JdbcBizException e) {
    log.warn("DB connectivity test failed: {}", e.getMessage());
    return TestResult.fail("Cannot reach database: " + rootCauseMessage(e));
}

When it happens

Trigger: Calling queryForTest(request) where JdbcConnectionFactory.getConnection(config) or connection.getConnection() throws — wrong host/port, unreachable network, bad username/password, unknown database, missing driver class, or connect timeout.

Common situations: User entering wrong credentials or host in a 'test connection' UI; DB firewall blocking the host; database down; JDBC URL typos; driver jar not on classpath; SSL requirement mismatch.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Failed listing database in catalog
• Failed getting table
• 重试获取数据库链接失败
• Could not find any jdbc dialect factories that implement
• Could not find any jdbc dialect factory that can handled

AI-assisted analysis of jd-opensource/joyagent-jdgenie@2417e0b8b6 (2026-09-08). Data as JSON: /api/errors/799931d1dac5c21e. Report an issue: GitHub.

Appendix: source

Thrown at genie-backend/src/main/java/com/jd/genie/data/provider/jdbc/JdbcDataProvider.java:98

                queryResult.setDataList(result);
                queryResult.setDataSize((long) result.size());
                queryResult.setQuerySql(request.getSql());
                queryResult.setQueryEndTime(System.currentTimeMillis());
                return queryResult;
            }

        }
    }

    @Override
    public boolean queryForTest(JdbcQueryRequest request) {
        boolean success = false;
        request.getJdbcConnectionConfig().setMaxRetryTimes(1);
        try (Connection connection = JdbcConnectionFactory.getConnection(request.getJdbcConnectionConfig()).getConnection()) {
            success = true;
        } catch (Exception e) {
            log.warn("An error occurred while querying for test: {}", e.getMessage(), e);
            throw new JdbcBizException("数据库联通测试失败:" + e.getMessage());
        }
        return success;
    }

}

View on GitHub (pinned to 2417e0b8b6)