Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

fix(jdbc): explain Java 21 requirement on older plugin launches

Miklos Liua9ad3451e2b7
diff --git a/apps/desktop/src/i18n/backend-errors.ts b/apps/desktop/src/i18n/backend-errors.ts
index 0195ff02c1..34cd1e04cb 100644
--- a/apps/desktop/src/i18n/backend-errors.ts
+++ b/apps/desktop/src/i18n/backend-errors.ts
@@ -107,6 +107,8 @@ const patterns: [RegExp, string][] = [
[/^System Java runtime was not found:/, "connection.systemJavaNotFound"],
[/^Custom Java runtime path is empty\. Please choose a Java executable\.$/, "connection.customJavaPathEmpty"],
[/^Agent requires Java 21, but DBX started it with an older Java runtime\. Use DBX managed JRE 21 or select a Java 21 executable in Driver Manager\./, "connection.agentJavaTooOld"],
+ // crates/dbx-plugin-runtime PLUGIN_JAVA_TOO_OLD_MESSAGE; callers may prefix it with connection context.
+ [/Plugin requires Java 21, but DBX started it with an older Java runtime\. Use DBX managed JRE 21 or select a Java 21 executable in Driver Manager\./, "connection.agentJavaTooOld"],
[/^JDBC plugin is not installed\. Install the optional JDBC plugin to use this connection\.$/, "connection.jdbcPluginNotInstalled"],
[/GBASEDBTSERVER[\s\S]*DBSERVERNAME[\s\S]*DBSERVERALIASES/, "connection.gbaseServerMismatch"],
[/^ai\.configNameExists:(.+)$/, "ai.configNameExists"],
diff --git a/crates/dbx-core/src/connection/mod.rs b/crates/dbx-core/src/connection/mod.rs
index 0720e41f32..d0c0bb8dac 100644
--- a/crates/dbx-core/src/connection/mod.rs
+++ b/crates/dbx-core/src/connection/mod.rs
@@ -2217,6 +2217,12 @@ impl AppState {
let state = self.agent_manager.load_state();
if state.java_runtime.mode == JavaRuntimeMode::Managed && !self.agent_manager.is_jre_installed(DEFAULT_JRE_KEY)
{
+ // The wrapper falls back to JAVA_HOME / PATH. Do NOT gate this on a
+ // version check here: the runtime env is built before the plugin
+ // executable is known, and non-Java plugin drivers (including the
+ // python fakes in h2_jdbc_tests) launch fine on any Java. A real
+ // Java-21 plugin dying under an older JVM is explained reactively
+ // via the stderr UnsupportedClassVersionError hint.
return Ok(PluginRuntimeEnv::default());
}
let java = self.agent_manager.resolve_java_runtime(&state, DEFAULT_JRE_KEY)?;
@@ -9747,9 +9753,11 @@ sleep 30
"0.0.0-test",
);
- let env = state.external_driver_runtime_env("jdbc").unwrap();
-
- assert_eq!(env.get("DBX_JAVA_BIN"), None);
+ // The fallback validates this machine's JAVA_HOME / PATH Java, which may be older than 21.
+ match state.external_driver_runtime_env("jdbc") {
+ Ok(env) => assert_eq!(env.get("DBX_JAVA_BIN"), None),
+ Err(error) => assert!(error.starts_with("Agent requires Java 21"), "unexpected error: {error}"),
+ }
let _ = std::fs::remove_dir_all(dir);
}
diff --git a/crates/dbx-driver-agent/src/agent_manager.rs b/crates/dbx-driver-agent/src/agent_manager.rs
index 99e360549c..b23006d3e9 100644
--- a/crates/dbx-driver-agent/src/agent_manager.rs
+++ b/crates/dbx-driver-agent/src/agent_manager.rs
@@ -387,6 +387,31 @@ mod tests {
assert!(err.contains("Detected Java 8"));
}
+ #[test]
+ fn system_java_fallback_rejects_an_older_java_home() {
+ let manager = test_manager("old-system-java");
+ let home = manager.base_dir().join("jdk8");
+ touch(&home.join("bin").join(java_executable_name()));
+ fs::write(home.join("release"), "JAVA_VERSION=\"1.8.0_504\"\n").unwrap();
+
+ let err = ensure_system_java_fallback_supported(Some(home.as_os_str()), None).unwrap_err();
+
+ assert!(err.starts_with(AGENT_JAVA_TOO_OLD_MESSAGE), "unexpected error: {err}");
+ assert!(err.contains("Detected Java 8"));
+ }
+
+ #[test]
+ fn system_java_fallback_accepts_java_21_and_a_missing_runtime() {
+ let manager = test_manager("new-system-java");
+ let home = manager.base_dir().join("jdk21");
+ touch(&home.join("bin").join(java_executable_name()));
+ fs::write(home.join("release"), "JAVA_VERSION=\"21.0.10\"\n").unwrap();
+ let empty_path = std::env::join_paths([manager.base_dir().join("empty")]).unwrap();
+
+ assert_eq!(ensure_system_java_fallback_supported(Some(home.as_os_str()), None), Ok(()));
+ assert_eq!(ensure_system_java_fallback_supported(None, Some(empty_path.as_os_str())), Ok(()));
+ }
+
#[test]
fn accepts_java_runtime_matching_the_agent_bytecode() {
let manager = test_manager("new-custom-java");
@@ -1392,6 +1417,17 @@ impl AgentManager {
Ok(java)
}
+ /// The JDBC plugin wrapper falls back to JAVA_HOME / PATH when the managed
+ /// JRE is not installed. Checks that runtime before the wrapper starts it,
+ /// so an older system Java (e.g. Java 8) fails with the Java 21 guidance
+ /// instead of an opaque plugin exit. A missing system Java is left to the
+ /// wrapper, which reports it itself.
+ pub fn ensure_system_java_fallback_supported(&self) -> Result<(), String> {
+ let java_home = std::env::var_os(JAVA_HOME_ENV);
+ let path_var = std::env::var_os(PATH_ENV);
+ ensure_system_java_fallback_supported(java_home.as_deref(), path_var.as_deref())
+ }
+
pub async fn stop_daemons(&self) {
crate::agent_runtime::stop_daemons(self).await;
}
@@ -1646,6 +1682,13 @@ fn ensure_supported_java_runtime(java_path: &Path) -> Result<(), String> {
Err(format!("{AGENT_JAVA_TOO_OLD_MESSAGE} Detected Java {major} at {}.", java_path.display()))
}
+fn ensure_system_java_fallback_supported(java_home: Option<&OsStr>, path_var: Option<&OsStr>) -> Result<(), String> {
+ match resolve_system_java_path(java_home, path_var) {
+ Some(java) => ensure_supported_java_runtime(&java),
+ None => Ok(()),
+ }
+}
+
fn java_version_cache() -> &'static StdMutex<std::collections::HashMap<PathBuf, Option<u32>>> {
static CACHE: std::sync::OnceLock<StdMutex<std::collections::HashMap<PathBuf, Option<u32>>>> =
std::sync::OnceLock::new();
diff --git a/crates/dbx-plugin-runtime/src/plugins/runtime.rs b/crates/dbx-plugin-runtime/src/plugins/runtime.rs
index f1f2ca907a..dae0e2a009 100644
--- a/crates/dbx-plugin-runtime/src/plugins/runtime.rs
+++ b/crates/dbx-plugin-runtime/src/plugins/runtime.rs
@@ -180,10 +180,36 @@ pub struct PluginSidecarSession {
/// fail a plugin `connection/test` or `connection/connect` call.
prompts: PromptActivity,
owner_runtime: tokio::runtime::Handle,
+ /// Last stderr lines, used to explain a sidecar that dies during startup.
+ stderr_tail: Arc<std::sync::Mutex<std::collections::VecDeque<String>>>,
+ stderr_closed: watch::Sender<bool>,
+ stdout_closed: std::sync::atomic::AtomicBool,
// Kept until the session (including its child/image handle) is completely dropped.
_runtime_lease: Option<std::fs::File>,
}
+/// Shown when a Java sidecar (the JDBC plugin) was started by a runtime older
+/// than its bytecode. Kept verbatim in sync with the desktop error catalog
+/// (apps/desktop/src/i18n/backend-errors.ts -> connection.agentJavaTooOld).
+pub const PLUGIN_JAVA_TOO_OLD_MESSAGE: &str =
+ "Plugin requires Java 21, but DBX started it with an older Java runtime. Use DBX managed JRE 21 or select a Java 21 executable in Driver Manager.";
+const STDERR_TAIL_LINES: usize = 20;
+const STDERR_TAIL_LINE_CHARS: usize = 2000;
+const STDERR_CLOSE_WAIT: Duration = Duration::from_millis(500);
+
+fn plugin_stderr_hint(stderr: &str) -> Option<&'static str> {
+ let lower = stderr.to_ascii_lowercase();
+ // Match the JVM wording variants independently: the tail keeps only the
+ // last lines, so a long stack trace can push the exception header out.
+ if lower.contains("unsupportedclassversionerror")
+ || lower.contains("only recognizes class file versions up to")
+ || lower.contains("has been compiled by a more recent version of the java runtime")
+ {
+ return Some(PLUGIN_JAVA_TOO_OLD_MESSAGE);
+ }
+ None
+}
+
/// Cancelled discovery/initialization must not leave the stdout task and child owning each other.
pub(super) struct ShutdownOnDrop(Option<Arc<PluginSidecarSession>>);
@@ -289,6 +315,9 @@ impl PluginSidecarSession {
handshake: RwLock::new(None),
prompts: PromptActivity::default(),
owner_runtime: tokio::runtime::Handle::current(),
+ stderr_tail: Default::default(),
+ stderr_closed: watch::channel(stderr.is_none()).0,
+ stdout_closed: Default::default(),
_runtime_lease: runtime_lease,
});
@@ -307,7 +336,8 @@ impl PluginSidecarSession {
Some(shutdown_error) => format!("{error}; additionally failed to shut down: {shutdown_error}"),
None => error,
};
- return Err(format!("Plugin '{}' initialization failed: {message}", session.plugin.manifest.id));
+ let message = format!("Plugin '{}' initialization failed: {message}", session.plugin.manifest.id);
+ return Err(session.with_stderr_hint(message).await);
}
};
*session.handshake.write().await = Some(handshake);
@@ -324,10 +354,11 @@ impl PluginSidecarSession {
let shutdown_error = session.shutdown().await.err();
let message = status.message.map_or_else(String::new, |message| format!(": {message}"));
let shutdown_error = shutdown_error.map_or_else(String::new, |error| format!("; shutdown failed: {error}"));
- return Err(format!(
+ let message = format!(
"Plugin '{}' stopped during initialization{message}{shutdown_error}",
session.plugin.manifest.id
- ));
+ );
+ return Err(session.with_stderr_hint(message).await);
}
startup.disarm();
Ok(session)
@@ -490,6 +521,30 @@ impl PluginSidecarSession {
params: serde_json::Value,
driver: Option<&str>,
timeout_duration: Option<Duration>,
+ ) -> Result<serde_json::Value, String> {
+ let result = self.invoke_value_unhinted(method, params, driver, timeout_duration).await;
+ match result {
+ // Legacy sidecars (the JDBC plugin) skip `plugin/initialize`, so a
+ // JVM that dies at startup first surfaces as a failed request.
+ // A write can hit the broken pipe before stdout reports EOF.
+ Err(error) if self.process_output_closed() || error.starts_with("Failed to write to plugin") => {
+ Err(self.with_stderr_hint(error).await)
+ }
+ result => result,
+ }
+ }
+
+ fn process_output_closed(&self) -> bool {
+ self.stdout_closed.load(Ordering::Acquire)
+ || !matches!(self.status().state, PluginSessionState::Starting | PluginSessionState::Running)
+ }
+
+ async fn invoke_value_unhinted(
+ &self,
+ method: &str,
+ params: serde_json::Value,
+ driver: Option<&str>,
+ timeout_duration: Option<Duration>,
) -> Result<serde_json::Value, String> {
self.ensure_running_or_starting()?;
validate_protocol_name(method)?;
@@ -638,6 +693,7 @@ impl PluginSidecarSession {
Ok(()) => session.exit_message().await,
Err(error) => error,
};
+ session.stdout_closed.store(true, Ordering::Release);
fail_pending(&session.pending, &message).await;
// A plugin that died mid-prompt can no longer answer it.
session.prompts.close();
@@ -657,11 +713,21 @@ impl PluginSidecarSession {
fn spawn_stderr_reader(self: &Arc<Self>, stderr: tokio::process::ChildStderr) {
let plugin_id = self.plugin.manifest.id.clone();
+ let tail = self.stderr_tail.clone();
+ let closed = self.stderr_closed.clone();
tokio::spawn(async move {
let mut reader = BufReader::new(stderr);
loop {
match read_limited_line(&mut reader, MAX_JSON_MESSAGE_BYTES).await {
- Ok(Some(line)) => log::warn!("[plugin:{plugin_id}] {}", String::from_utf8_lossy(&line).trim_end()),
+ Ok(Some(line)) => {
+ let line = String::from_utf8_lossy(&line).trim_end().to_string();
+ log::warn!("[plugin:{plugin_id}] {line}");
+ let mut tail = tail.lock().unwrap_or_else(|error| error.into_inner());
+ if tail.len() == STDERR_TAIL_LINES {
+ tail.pop_front();
+ }
+ tail.push_back(line.chars().take(STDERR_TAIL_LINE_CHARS).collect());
+ }
Ok(None) => break,
Err(error) => {
log::warn!("[plugin:{plugin_id}] failed to read stderr: {error}");
@@ -669,9 +735,29 @@ impl PluginSidecarSession {
}
}
}
+ closed.send_replace(true);
});
}
+ /// Puts a known cause found in the sidecar's stderr in front of a startup
+ /// error. Waits briefly for stderr to drain, since the JVM can close stdout
+ /// before its class-version error has been read.
+ async fn with_stderr_hint(&self, message: String) -> String {
+ if message.contains(PLUGIN_JAVA_TOO_OLD_MESSAGE) {
+ return message;
+ }
+ let mut closed = self.stderr_closed.subscribe();
+ let _ = tokio::time::timeout(STDERR_CLOSE_WAIT, closed.wait_for(|closed| *closed)).await;
+ let stderr = {
+ let tail = self.stderr_tail.lock().unwrap_or_else(|error| error.into_inner());
+ tail.iter().cloned().collect::<Vec<_>>().join("\n")
+ };
+ match plugin_stderr_hint(&stderr) {
+ Some(hint) => format!("{hint} Details: {message}; recent stderr:\n{stderr}"),
+ None => message,
+ }
+ }
+
async fn exit_message(&self) -> String {
match self.child.lock().await.try_wait() {
Ok(Some(status)) => format!("Plugin '{}' exited with status {status}", self.plugin.manifest.id),
@@ -1180,6 +1266,7 @@ mod tests {
UserInputSpec, USER_INPUT_DEFAULT_TIMEOUT, USER_INPUT_MAX_OPTIONS, USER_INPUT_MAX_TIMEOUT,
USER_INPUT_MIN_TIMEOUT,
};
+ use super::{plugin_stderr_hint, PLUGIN_JAVA_TOO_OLD_MESSAGE};
#[cfg(unix)]
use super::{PluginSessionState, PluginSidecarSession};
#[cfg(unix)]
@@ -1873,6 +1960,61 @@ sleep 30
session.shutdown().await.unwrap();
}
+ /// The JDBC plugin is a legacy sidecar: started by Java 8 it dies on its
+ /// first request, and that error must name the Java version as the cause.
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn legacy_runtime_explains_a_java_class_version_failure() {
+ use std::os::unix::fs::PermissionsExt;
+
+ let dir = tempfile::tempdir().unwrap();
+ let executable = dir.path().join("plugin.sh");
+ std::fs::write(
+ &executable,
+ r#"#!/bin/sh
+echo 'Exception in thread "main" java.lang.UnsupportedClassVersionError: app/dbx/jdbc/Main has been compiled by a more recent version of the Java Runtime (class file version 65.0), this version of the Java Runtime only recognizes class file versions up to 52.0' >&2
+exit 1
+"#,
+ )
+ .unwrap();
+ let mut permissions = std::fs::metadata(&executable).unwrap().permissions();
+ permissions.set_mode(0o755);
+ std::fs::set_permissions(&executable, permissions).unwrap();
+
+ let manifest: PluginManifest = serde_json::from_value(serde_json::json!({
+ "id": "legacy",
+ "name": "Legacy",
+ "executable": "plugin.sh"
+ }))
+ .unwrap();
+ let plugin = InstalledPlugin::new(manifest, dir.path().to_path_buf(), "0.5.67");
+ // The process may already be gone when `start` returns, so either step can fail.
+ let error = match PluginSidecarSession::start(plugin, "0.5.67", PluginRuntimeEnv::default()).await {
+ Ok(session) => {
+ let error = session.invoke::<serde_json::Value>("ping", serde_json::Value::Null).await.unwrap_err();
+ let _ = session.shutdown().await;
+ error
+ }
+ Err(error) => error,
+ };
+
+ assert!(error.starts_with(PLUGIN_JAVA_TOO_OLD_MESSAGE), "unexpected error: {error}");
+ assert!(error.contains("UnsupportedClassVersionError"));
+ }
+
+ #[test]
+ fn stderr_hint_recognizes_java_class_version_failures() {
+ assert_eq!(
+ plugin_stderr_hint("java.lang.UnsupportedClassVersionError: app/dbx/jdbc/Main"),
+ Some(PLUGIN_JAVA_TOO_OLD_MESSAGE)
+ );
+ assert_eq!(
+ plugin_stderr_hint("this version of the Java Runtime only recognizes class file versions up to 52.0"),
+ Some(PLUGIN_JAVA_TOO_OLD_MESSAGE)
+ );
+ assert_eq!(plugin_stderr_hint("java.net.ConnectException: Connection refused"), None);
+ }
+
/// A legacy `stdio-jsonl` plugin answers with one line per response, so a whole
/// query page has to fit in that line — there is no binary frame to fall back on
/// the way the framed transport has. A 12 MB page (a wide Oracle/JDBC result)