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(linux): make transparent floating windows opt-in

t8y26cd2dc1c9d9e
diff --git a/apps/desktop/src/lib/__tests__/app/startupLinuxFloatingFrame.spec.ts b/apps/desktop/src/lib/__tests__/app/startupLinuxFloatingFrame.spec.ts
new file mode 100644
index 0000000000..dc7e0e794a
--- /dev/null
+++ b/apps/desktop/src/lib/__tests__/app/startupLinuxFloatingFrame.spec.ts
@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it, vi } from "vitest";
+
+const indexHtml = readFileSync(fileURLToPath(new URL("../../../../index.html", import.meta.url)), "utf8");
+const floatingFrameScript = [...indexHtml.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/g)].map((match) => match[1]).find((script) => script.includes("window.__DBX_LINUX_FLOATING__"));
+
+if (!floatingFrameScript) throw new Error("Linux floating frame script not found");
+
+describe("startup Linux floating frame", () => {
+ it.each([undefined, false])("keeps opaque windows opaque when the native floating frame flag is %s", (flag) => {
+ const addClass = vi.fn();
+
+ Function("document", "window", floatingFrameScript)({ documentElement: { classList: { add: addClass } } }, { __DBX_LINUX_FLOATING__: flag });
+
+ expect(addClass).not.toHaveBeenCalled();
+ });
+
+ it("draws the floating frame when the native window explicitly opts into transparency", () => {
+ const addClass = vi.fn();
+
+ Function("document", "window", floatingFrameScript)({ documentElement: { classList: { add: addClass } } }, { __DBX_LINUX_FLOATING__: true });
+
+ expect(addClass).toHaveBeenCalledOnce();
+ expect(addClass).toHaveBeenCalledWith("dbx-linux-floating");
+ });
+});
diff --git a/docs/content/docs/faq.cn.mdx b/docs/content/docs/faq.cn.mdx
index 7c36187a50..ead94a147d 100644
--- a/docs/content/docs/faq.cn.mdx
+++ b/docs/content/docs/faq.cn.mdx
@@ -33,6 +33,20 @@ description: DBX 常见问题:连接数据保存在哪里、如何备份、如
<p>升级已有安装前,请先阅读[数据安全升级与迁移说明](/cn/docs/data-security-migration)。</p>
</Accordions>
+## Linux 窗口闪烁或内容消失
+
+Linux 主窗口默认使用不透明背景,避免部分 KDE、显卡驱动与 WebKitGTK 的透明窗口合成兼容问题。不会因此关闭 GPU 加速或改变 Wayland/X11 后端。
+
+如果确认当前环境支持透明窗口,可以显式启用带圆角、阴影的浮动边框:
+
+```bash
+DBX_LINUX_FLOATING_FRAME=1 dbx
+```
+
+只有环境变量值为 `1` 且系统已开启窗口合成时才启用。若启用后出现闪烁、内容消失或必须缩放窗口才能重绘,请完全退出 DBX(包括托盘),移除该环境变量或使用 `DBX_LINUX_FLOATING_FRAME=0 dbx` 重新启动。AppImage 用户请将 `dbx` 替换为实际的 AppImage 文件路径。
+
+如果默认的不透明窗口仍有问题,请在反馈中提供 DBX 版本、安装方式、KDE/Plasma 版本、Wayland/X11 会话类型、显卡及驱动信息,以及系统 WebKitGTK 版本。
+
## PostgreSQL / openGauss 中文乱码
如果数据库声明为 `LATIN1`,但历史文本实际保存的是 GB18030 字节,可以在 **编辑连接 → 连接 → URL 参数** 中填写:
diff --git a/docs/content/docs/faq.mdx b/docs/content/docs/faq.mdx
index a896b6d56c..864d7049ad 100644
--- a/docs/content/docs/faq.mdx
+++ b/docs/content/docs/faq.mdx
@@ -33,6 +33,20 @@ description: Frequently asked questions about DBX, including where connection da
<p>See the [Data Security Upgrade and Migration guide](/en/docs/data-security-migration) before upgrading an existing installation.</p>
</Accordions>
+## Linux Window Flickering or Missing Content
+
+The Linux main window uses an opaque background by default to avoid transparent-window compositing compatibility problems with some KDE, graphics driver and WebKitGTK combinations. This does not disable GPU acceleration or change the Wayland/X11 backend.
+
+If your environment supports transparent windows, you can explicitly enable the floating frame with rounded corners and a shadow:
+
+```bash
+DBX_LINUX_FLOATING_FRAME=1 dbx
+```
+
+The frame is enabled only when the variable is exactly `1` and a compositing manager is available. If enabling it causes flickering, missing content or redraws only after resizing, quit DBX completely, including its tray process, and remove the variable or restart with `DBX_LINUX_FLOATING_FRAME=0 dbx`. For AppImage installations, replace `dbx` with the actual AppImage path.
+
+If the default opaque window still has problems, include the DBX version, installation format, KDE/Plasma version, Wayland/X11 session type, graphics hardware and driver details, and system WebKitGTK version in your report.
+
## Garbled PostgreSQL / openGauss text
For a database declared as `LATIN1` whose legacy text actually contains GB18030 bytes, enter the following in **Edit connection → Connection → URL parameters**:
diff --git a/src-tauri/src/commands/window_controls.rs b/src-tauri/src/commands/window_controls.rs
index 68e785d6cf..95c5503167 100644
--- a/src-tauri/src/commands/window_controls.rs
+++ b/src-tauri/src/commands/window_controls.rs
@@ -180,7 +180,7 @@ mod tests {
base_window.as_object_mut().unwrap().remove(key);
}
assert_eq!(linux_window["create"], Value::Bool(false));
- assert_eq!(linux_window["transparent"], Value::Bool(true));
+ assert_eq!(linux_window["transparent"], Value::Bool(false));
for key in ["create", "transparent"] {
linux_window.as_object_mut().unwrap().remove(key);
}
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 95d6d65843..39a41565f6 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -175,16 +175,24 @@ pub(crate) fn linux_compositing_available() -> bool {
gtk::gdk::Screen::default().is_some_and(|screen| screen.is_composited())
}
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
+fn should_enable_linux_floating_frame(compositing: bool, opt_in: Option<&std::ffi::OsStr>) -> bool {
+ compositing && opt_in == Some(std::ffi::OsStr::new("1"))
+}
+
/// The Linux config declares the main window with `create: false` so its transparency can
-/// depend on the compositor, which is only known at runtime.
+/// be explicitly opted into at runtime when a compositor is available.
#[cfg(target_os = "linux")]
fn create_linux_main_window(app: &tauri::App) -> tauri::Result<()> {
let Some(config) = app.config().app.windows.iter().find(|window| window.label == "main").cloned() else {
return Ok(());
};
let compositing = linux_compositing_available();
- let mut builder = tauri::WebviewWindowBuilder::from_config(app.handle(), &config)?.transparent(compositing);
- if compositing {
+ let opt_in = std::env::var_os("DBX_LINUX_FLOATING_FRAME");
+ let floating_frame = should_enable_linux_floating_frame(compositing, opt_in.as_deref());
+ log::info!("[WINDOW] Linux main window compositing={compositing}; floating_frame={floating_frame}");
+ let mut builder = tauri::WebviewWindowBuilder::from_config(app.handle(), &config)?.transparent(floating_frame);
+ if floating_frame {
// Read by index.html before first paint to draw the rounded, shadowed frame.
builder = builder.initialization_script("window.__DBX_LINUX_FLOATING__ = true;");
}
@@ -1053,15 +1061,34 @@ mod tests {
linux_drm_render_devices_from_paths, linux_nvidia_driver_from_state, linux_pci_id_from_sysfs_value,
linux_selected_drm_render_device, linux_uses_native_wayland, linux_webkit_environment_override,
linux_webkit_rendering_workarounds, native_window_decorations_override, should_confirm_app_exit_request,
- should_enable_single_instance, should_fallback_to_native_quit, should_hide_window_before_exit,
- should_hide_window_on_close, should_setup_desktop_tray, should_show_main_window_after_setup,
- should_show_main_window_before_setup_tasks, startup_data_dir_mode, tray_menu_labels_for_locale,
- uses_application_level_icon, LinuxDrmRenderDevice, LinuxNvidiaDriver,
+ should_enable_linux_floating_frame, should_enable_single_instance, should_fallback_to_native_quit,
+ should_hide_window_before_exit, should_hide_window_on_close, should_setup_desktop_tray,
+ should_show_main_window_after_setup, should_show_main_window_before_setup_tasks, startup_data_dir_mode,
+ tray_menu_labels_for_locale, uses_application_level_icon, LinuxDrmRenderDevice, LinuxNvidiaDriver,
};
use crate::data_dir::DataDirMode;
use std::ffi::OsStr;
use std::path::{Path, PathBuf};
+ #[test]
+ fn linux_floating_frame_is_disabled_by_default() {
+ assert!(!should_enable_linux_floating_frame(true, None));
+ assert!(!should_enable_linux_floating_frame(false, None));
+ }
+
+ #[test]
+ fn linux_floating_frame_requires_explicit_opt_in() {
+ assert!(should_enable_linux_floating_frame(true, Some(OsStr::new("1"))));
+ for value in ["", "0", "false", "true", "auto", "yes", "01"] {
+ assert!(!should_enable_linux_floating_frame(true, Some(OsStr::new(value))));
+ }
+ }
+
+ #[test]
+ fn linux_floating_frame_requires_compositing_even_when_opted_in() {
+ assert!(!should_enable_linux_floating_frame(false, Some(OsStr::new("1"))));
+ }
+
#[test]
fn tray_menu_labels_follow_locale() {
assert_eq!(tray_menu_labels_for_locale("zh-CN"), ("显示 DBX", "退出 DBX"));
diff --git a/src-tauri/tauri.linux.conf.json b/src-tauri/tauri.linux.conf.json
index b03ce03b15..8f338150e6 100644
--- a/src-tauri/tauri.linux.conf.json
+++ b/src-tauri/tauri.linux.conf.json
@@ -10,7 +10,7 @@
"resizable": true,
"fullscreen": false,
"visible": false,
- "transparent": true,
+ "transparent": false,
"hiddenTitle": true,
"acceptFirstMouse": true,
"create": false