DBeaver 26.2.3 配置与 CLI 参数详解

DBeaver 26.2.3 配置体系与命令行速查：dbeaver.ini 全文逐项解读（JVM 内存修改 ps 验证）、工作区/驱动缓存/secure 目录结构、全部启动参数与 -con 连接规格键位、auth-models 等子命令实测回显，含 headless 报错等真实排障。

DBeaver数据库客户端DBeaver2026/10/20

DBeaver 26.2.3 配置与 CLI 参数详解

目标：系统拆解 DBeaver Community 26.2.3 的配置体系（dbeaver.ini、全局数据目录、工作区）与命令行参数（启动参数、-con 连接规格、子命令），每项配置与参数均给出 Ubuntu 22.04 实测回显或实测结论，可作为日常调参与排障的速查手册。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • 软件版本：DBeaver Community 26.2.3（构建号 26.2.3.202610181708），deb 安装（/usr/bin/dbeaver → /usr/share/dbeaver-ce/dbeaver）
  • 运行时：发行包内置 Temurin JRE 25.0.4.1+1
  • 实测方式：命令行参数均在本机逐条执行并记录回显；连接类参数配合 PostgreSQL 16.15 / MySQL 8.0.46 目标库实测（实战细节见《DBeaver 26.2.3 数据库连接与操作实战》）

二、配置体系概览

DBeaver 的配置分三层，先建立全景再逐层拆解：

层位置内容生效方式
安装层/usr/share/dbeaver-ce/（deb/tar）程序本体、dbeaver.ini（JVM/启动参数）、plugins/改后重启
全局层~/.local/share/DBeaverData/工作区指针、驱动缓存、密钥环、产品配置重启生效
工作区层~/.local/share/DBeaverData/workspace6/连接、项目、SQL 脚本、运行日志、实例锁改后重启/重新打开

全局数据目录实测结构（find ~/.local/share/DBeaverData -maxdepth 3 节选，去除瞬态文件）：

/root/.local/share/DBeaverData
/root/.local/share/DBeaverData/drivers
/root/.local/share/DBeaverData/drivers/maven
/root/.local/share/DBeaverData/drivers/maven/maven-central
/root/.local/share/DBeaverData/secure
/root/.local/share/DBeaverData/secure/secure_storage
/root/.local/share/DBeaverData/settings
/root/.local/share/DBeaverData/settings/product-config.json
/root/.local/share/DBeaverData/workspace6
/root/.local/share/DBeaverData/workspace6/.metadata
/root/.local/share/DBeaverData/workspace6/.metadata/.lock
/root/.local/share/DBeaverData/workspace6/.metadata/.log
/root/.local/share/DBeaverData/workspace6/.metadata/dbeaver-instance.properties
/root/.local/share/DBeaverData/workspace6/.metadata/dbeaver-workspace.properties
/root/.local/share/DBeaverData/workspace6/General
/root/.local/share/DBeaverData/workspace6/General/.dbeaver
/root/.local/share/DBeaverData/workspace6/General/.project

逐项说明：

  • drivers/maven/maven-central/：按 Maven 坐标组织的 JDBC 驱动缓存（首次连接自动下载，实测 PostgreSQL 42.7.13、MySQL Connector/J 8.2.0 均落在这里）；离线迁移直接拷贝该目录；
  • secure/secure_storage：密钥环，保存的连接口令加密存放于此（不在 data-sources.json 明文中）；
  • settings/product-config.json：产品级配置（更新渠道、AI 设置等）；
  • workspace6/.metadata/：工作区运行态——.log 主日志（连接报错都在这）、.lock 工作区互斥锁、dbeaver-instance.properties（单实例通信注册）、dbeaver-debug-*.log 崩溃/调试转储；
  • workspace6/General/：默认项目——.dbeaver/data-sources.json（连接配置）、SQL 脚本目录（Scripts）；.project 为 Eclipse 工程标记。

💡 说明：备份/迁移只盯 ~/.local/share/DBeaverData/ 一个目录即可（连接、脚本、驱动、口令全在内）；「重置 DBeaver」= 关闭程序后删除该目录（会丢全部连接与脚本，请先备份）。多工作区并存用 -data 参数指定其他路径（见五、5.4）。

三、dbeaver.ini 详解（JVM 与启动参数）

dbeaver.ini 是 Eclipse 体系的启动配置文件，deb 安装位于 /usr/share/dbeaver-ce/dbeaver.ini，tar 包位于解压目录内。本环境实测全文：

-startup
plugins/org.eclipse.equinox.launcher_1.7.0.v20250519-0528.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.2.1300.v20250728-0841
-data
@noDefault
-vmargs
-Xms64m
-Xmx1024m
--add-modules=ALL-SYSTEM
--add-opens=java.base/java.io=ALL-UNNAMED
--add-opens=java.base/java.lang=ALL-UNNAMED
--add-opens=java.base/java.lang.reflect=ALL-UNNAMED
--add-opens=java.base/java.lang.ref=ALL-UNNAMED
--add-opens=java.base/java.net=ALL-UNNAMED
--add-opens=java.base/java.nio=ALL-UNNAMED
--add-opens=java.base/java.nio.charset=ALL-UNNAMED
--add-opens=java.base/java.text=ALL-UNNAMED
--add-opens=java.base/java.time=ALL-UNNAMED
--add-opens=java.base/java.util=ALL-UNNAMED
--add-opens=java.base/jdk.internal.ref=ALL-UNNAMED
--add-opens=java.base/sun.net.dns=ALL-UNNAMED
--add-opens=java.base/sun.net.util=ALL-UNNAMED
--add-opens=java.base/sun.net.spi=ALL-UNNAMED
--add-opens=java.desktop/javax.swing=ALL-UNNAMED
--add-opens=java.logging/java.util.logging=ALL-UNNAMED
-Dorg.eclipse.swt.browser.DefaultType=webkit

逐项说明：

配置项说明
-startup / --launcher.libraryEclipse 启动器插件 jar 与平台原生库路径（升级版本号会变，勿手改）
-data @noDefault不在 ini 中硬编码默认工作区，由程序按平台默认位置解析（~/.local/share/DBeaverData/workspace6），也可被命令行 -data 覆盖
-vmargs之后的行全部作为 JVM 参数传递
-Xms64m / -Xmx1024m初始堆 64 MiB、最大堆 1024 MiB——多连接/大结果集卡顿的主调点
--add-modules=ALL-SYSTEM + 一组 --add-opensJDK 17+ 模块封装下的反射开放清单（Eclipse/SWT 依赖），删掉会启动失败
-Dorg.eclipse.swt.browser.DefaultType=webkit内嵌浏览器用 WebKitGTK（Linux 上欢迎页/登录页需要 libwebkit2gtk 运行库）

JVM 内存调整实测（最常用的改动）：把最大堆从 1024m 调到 768m 验证生效路径——

sudo sed -i "s/^-Xmx1024m$/-Xmx768m/" /usr/share/dbeaver-ce/dbeaver.ini
grep -n "Xmx" /usr/share/dbeaver-ce/dbeaver.ini

实测回显：

35:-Xmx768m

启动 DBeaver 并连接一个 PostgreSQL 库后，用进程命令行复核实际生效值（实测回显）：

ps -ef | grep "[j]ava" | grep -o "\-Xm[sx][0-9]*m" | sort -u

-Xms64m
-Xmx768m

⚠️ 注意：ini 文件每行一个参数，不能合并写；-vmargs 之后的行才归 JVM 管，写在其前面会被当作启动器参数而失效。改完必须重启 DBeaver。堆上限按机器内存量力而行，1 GiB 默认值够日常使用；超大结果集导出可适度调大，但不建议超过物理内存的四分之一。

四、全局偏好与常见设置落点

常用设置在 GUI（Window → Preferences）中修改后，实际落盘位置如下（工作区 .metadata/.plugins/ 下的 Eclipse 偏好存储）：

GUI 设置落盘位置说明
连接列表/口令General/.dbeaver/data-sources.json + secure/secure_storage连接结构明文、口令加密
连接行为（自动提交/空闲断开）data-sources.json 的 connection-types 段auto-commit、close-connections-period 等（实测实录见《DBeaver 26.2.3 数据库连接与操作实战》第七章）
驱动（本地 jar/Maven 坐标）drivers/ + 驱动定义（工作区 .dbeaver/database-drivers.json，有自定义时生成）Driver Manager 的修改点
SQL 编辑器（格式化/补全）工作区偏好存储（.metadata/.plugins/org.jkiss.dbeaver.*）可用 GUI 的 Export Preferences 导出成 .epf
主日志workspace6/.metadata/.log排障第一现场，连接失败/驱动错误都在这

五、CLI 启动参数详解

5.1 帮助与版本

dbeaver --help（完整输出，实测）：

DBeaver 26.2.3
Usage: dbeaver [-hqv] [-bringToFront=(boolean)] [-closeTabs=(boolean)] [--debug-logs=(boolean)] [-disconnectAll=
               (boolean)] [-dump=(boolean)] [-newInstance=(boolean)] [-nosplash=(boolean)] [-reuseWorkspace=(boolean)]
               [-stop=(boolean)] [-data=<data(string)>] [-nl=<nl(string)>] [--output-log=<outputLog(string)>]
               [-vars=<variablesFile(string)>] [-f=<filesToOpen>[,<filesToOpen>...](string[])]...
               [-con=<connectionSpecs>...(string[])]... =[<filesToOpenParams>...](string[]) [COMMAND]
DBeaver commands
      =[<filesToOpenParams>...](string[])
                             Open files
      -bringToFront=(boolean)
                             Bring DBeaver window on top of other applications
      -closeTabs=(boolean)   Close all open editors
      -con, -connect, -ds-spec, --datasource-specification=<connectionSpecs>...(string[])
                             Connects to a specified database
      -data=<data(string)>   Workspace location
      --debug-logs=(boolean) Enable debug logging
      -disconnectAll=(boolean)
                             Disconnect from all databases
      -dump=(boolean)        Print instance thread dump
  -f, -file=<filesToOpen>[,<filesToOpen>...](string[])
                             Open a file
  -h, -help, --help=(boolean)
                             Show this help message and exit
      -newInstance=(boolean) Force creating new application instance (do not try to activate already running)
      -nl=<nl(string)>       Default locale
      -nosplash=(boolean)    Hide splash screen on start
      --output-log=<outputLog(string)>
                             Status/log output format
  -q, -quiet=(boolean)       Run quietly (do not print logs)
      -reuseWorkspace=(boolean)
                             Force workspace reuse (do not show warnings)
      -stop, -quit=(boolean) Stop DBeaver running instance
  -v, -V, --version=(boolean)
                             Print version information and exit
      -vars, -variablesFile=<variablesFile(string)>
                             Uses a specified configuration file for variable resolving
  auth-models                                                 List available database authentication models
  network-handlers                                            List available database network handlers
  completion                                                  Generate bash/zsh completion script for dbeaver
  translateSQL, -translateSQL, -translate-sql-script          Translate SQL script from one dialect to another
  database-driver-list, -database-driver-list, -databaseList  Show list of supported database drivers in json format.
  link-project, -link-project, --link-project                 Link an existing external folder into the workspace as a
                                                                project (contents are not copied)
  unlink-project, -unlink-project, --unlink-project, unlink   Unlink a project from the workspace (files are kept on
                                                                disk)

版本号查询（实测）：

dbeaver -v

DBeaver 26.2.3.202610181708

5.2 实例控制参数（针对运行中的实例）

DBeaver 默认单实例运行：已有实例在跑时，再执行任何 dbeaver 命令会把参数转发给该实例（而不是再开一个）。以下控制参数都依赖这一机制：

参数说明实测结论
-stop（别名 -quit）退出运行中的实例实测执行后 java 进程退出（pgrep -c java → 0）；若命令与实例不在同一工作区则不生效，需带相同 -data
-disconnectAll断开所有数据库连接实测执行后 PostgreSQL 服务端 pg_stat_activity 中 DBeaver 会话清零
-closeTabs关闭所有已打开的编辑器标签实测转发给运行实例后静默完成（无控制台输出）
-bringToFront把 DBeaver 窗口置顶实测转发后窗口前置，无控制台输出
-dump打印实例线程转储实测输出线程快照（JVM jcmd 原生格式），卡死排障利器，实测输出节选：56 SWTResourceTracker: 后跟该线程的 java.base@25.0.4.1/... 完整调用栈
-newInstance强制新开实例（不转发）与 -data 搭配实现多工作区并行

5.3 启动行为参数

参数说明实测结论
-nosplash启动不显示 splash 启动画面无界面依赖场景（脚本带参启动）建议常带
-q（-quiet）静默运行，不打印日志与 -nosplash 常搭配使用
--debug-logs打开调试日志开启后工作区 .metadata/ 生成 dbeaver-debug-<时间戳>.log（实测目录中可见多个该类文件）
--output-log=<format>启动过程日志的输出格式，取值 text 或 json传文件路径实测报错：Invalid --output-log value '/root/ol.txt'. Expected 'text' or 'json'；text 格式即默认控制台输出形态（> Start DBeaver Application Standalone [...] 逐行插件启动日志）
-nl=<locale>界面默认语言区域（如 -nl=zh）对新启动实例生效；转发给运行实例不改变既有界面语言
-reuseWorkspace强制复用工作区（跳过锁定警告）工作区异常退出后二次启动弹「workspace in use」时使用
-data=<path>指定工作区位置实测 dbeaver -data /root/ws-alt 后工作区直接落在 /root/ws-alt/（.metadata、General 等结构与默认一致）；备份/多工作区可用

5.4 连接与文件参数

-con（别名 -connect/-ds-spec/--datasource-specification）——命令行连接。 规格串内用 | 分隔键值对。常用键（官方文档口径 + 本文实测验证）：

键说明实测
driver=<驱动短名>数据库类型（postgresql、mysql、sqlite 等，短名可用 auth-models/GUI 驱动列表核对）✅
host=/port=/database=/user=/password=基础连接五要素✅（database= 正确；db= 会被静默忽略导致 FATAL: database "root" does not exist）
url=<完整 JDBC URL>URL 直连形态，JDBC 属性可挂在 URL 上✅（MySQL 公钥问题实测靠它解决：jdbc:mysql://10.89.61.5:3306/appdb?allowPublicKeyRetrieval=true&useSSL=false）
name=<名称>连接显示名✅（不影响持久化）
authProp.<键>=<值>认证模型参数JDBC 属性不能用此前缀传（实测 authProp.allowPublicKeyRetrieval=true 不生效）
savePassword=true保存口令配合持久连接使用；-con 临时连接实测不落盘
folder=<文件夹>归入连接树文件夹官方文档口径

实测可用的连接命令示例（临时连接，连接树显示 Ext: PostgreSQL - appdb）：

dbeaver -nosplash -con "driver=postgresql|host=10.89.61.4|port=5432|database=appdb|user=root|password=q1w2e3r4"

⚠️ 两条实测硬结论：① -con 创建的是临时连接，重启后消失、不写入 data-sources.json（带 name=、savePassword=true 也一样，实测 grep -c "PG-App" data-sources.json → 0）；② --output-log 等启动参数只对新实例生效，转发给已运行实例的控制台命令无回显。完整连接实战见《DBeaver 26.2.3 数据库连接与操作实战》。

-f（-file）与位置参数——打开文件。 打开 SQL 脚本等文件进编辑器，可同时用 -con 绑定连接（实测一步完成「开编辑器 + 加载脚本 + 连库」）：

dbeaver -f /root/staff-insert.sql -con "driver=postgresql|host=10.89.61.4|port=5432|database=appdb|user=root|password=q1w2e3r4"

多个文件用逗号或重复 -f；无 -f 时直接把文件路径作为位置参数写在命令尾部（filesToOpen）。

-vars——变量解析配置文件。 为带变量的连接/脚本指定变量取值文件（官方文档口径；配合项目变量使用，本文未展开实测）。

六、CLI 子命令详解

--help 尾部的 [COMMAND] 区列出了 7 个子命令。实测行为如下：

6.1 auth-models（无界面可跑）

列出可用认证模型（含每模型的参数），headless 可执行（实测）：

dbeaver auth-models

实测回显（节选）：

Auth Model ID: google_bigquery, Name: Google Cloud Auth, Description: BigQuery internal authentication
Parameters:
  - userName = User name
  - userPassword = User password

Auth Model ID: clickhouse_cloud_sso, Name: ClickHouse Cloud SSO, Description: Browser based single sign-on to ClickHouse Cloud
Parameters:

Auth Model ID: sqlserver_windows, Name: Windows Authentication, Description: Windows integrated authentication
Parameters:
  - userName = User name
  - userPassword = User password

用途：-con 里 auth=<模型ID> 键、GUI 连接设置的 Authentication 下拉框，取值以此列表为准。

6.2 network-handlers（无界面可跑）

列出可用网络处理器（SSL/SSH 隧道/代理等）及其参数（实测节选）：

dbeaver network-handlers

Available network handlers:
Network Handler ID: clickhouse-ssl, Name: SSL, Parameters:
  - ssl.method = Method, possible values: CERTIFICATES
  - ssl.ca.cert.value = CA Certificate
  ...
Network Handler ID: ssh_tunnel, Name: SSH, Parameters:

用途：SSH 隧道、SSL、SOCKS 代理等非默认网络形态，GUI 的连接设置 SSL/SSH 标签页对应这些处理器；配置值在 data-sources.json 连接条目的 tunnel 段。

6.3 completion

生成 shell 补全脚本（picocli 4.7.7 生成器，实测产物为合法 bash 脚本，文件头节选）：

dbeaver completion

#!/usr/bin/env bash
#
# dbeaver Bash Completion
# =======================
#
# Bash completion support for the `dbeaver` command,
# generated by [picocli](https://picocli.info/) version 4.7.7.
#

落地方式：dbeaver completion > /etc/bash_completion.d/dbeaver 后重新进 shell 即可补全参数。

6.4 translateSQL

把 SQL 脚本从一种方言翻译成另一种（translateSQL/-translateSQL/-translate-sql-script 三个名字等价）。实测要点：该子命令必须紧跟在子命令名之后按其参数格式书写，把文件参数放在主命令位置会报错（实测原文）：

Error processing command line as client: Parameter(s) postgresql,/opt/data/quzuo/tmp/dbeaver/t-out.sql cannot be specified after 'translateSQL'

即报错信息也提示了正确形态：方言与脚本参数要写在 translateSQL 子命令自身之后，如 dbeaver translateSQL <方言参数> <脚本文件>。

6.5 database-driver-list

以 JSON 输出内置驱动清单（database-driver-list/-database-driver-list/-databaseList）。实测注意：该子命令需要图形环境——headless 执行报 org.eclipse.swt.SWTError: No more handles [gtk_init_check() failed]（见七、Q1）；有显示环境的桌面会话中执行即可得到驱动 JSON 列表。若只想确认驱动能力，用 GUI 的 Database → Driver Manager 更直观。

把磁盘上已有目录以「外部项目」形式挂进/摘出工作区（内容不复制）。适合多机共享同一份项目目录（如放网盘/仓库的连接与脚本）。取值形态：dbeaver link-project <目录路径>。本文未做多机场景实测，使用前建议先在测试工作区（-data 另指）验证。

七、常见问题（FAQ）

Q1：headless（SSH 纯终端）执行 dbeaver auth-models 可以、执行 database-driver-list 却报 SWTError: No more handles [gtk_init_check() failed]？

auth-models/network-handlers 是纯模型列表命令，不需要 SWT；database-driver-list 的实现路径要初始化图形环境。给命令配上显示（桌面会话、ssh -X 或 Xvfb 虚拟显示）即可。这也再次说明：DBeaver 主体是 GUI 程序，CLI 只是「带参启动」。

Q2：--output-log=/root/ol.txt 报 Invalid --output-log value？

--output-log 的值是格式名（text/json），不是文件路径（实测报错原文见 5.3 节）。要留存启动日志请配合 shell 重定向：dbeaver -nosplash 2>&1 | tee startup.log。

Q3：dbeaver -stop 执行了但实例还在？

-stop 只作用于同一工作区的实例。实例若以 -data <其他路径> 启动，需用相同 -data 再执行 -stop。终极兜底：找到对应 java 进程 kill <pid>（工作区锁会随进程退出释放；异常残留可用 -reuseWorkspace 越过锁定警告）。

Q4：改了 dbeaver.ini 启动失败/参数不生效？

三个常见坑（均实测确认）：① 每行一个参数，不能合并；② JVM 参数必须写在 -vmargs 之后；③ --add-opens 系列是 SWT/Eclipse 在 JDK 17+ 上的硬依赖，逐项保留，只动 -Xms/-Xmx/-D 类参数。改完用 ps -ef | grep [j]ava 复核生效值（实测方法见三、3.2）。

Q5：工作区日志在哪？连接报错先看什么？

~/.local/share/DBeaverData/workspace6/.metadata/.log 是主日志（Eclipse !ENTRY/!MESSAGE/!STACK 格式），连接失败、驱动加载错误的第一现场都在这里（本文引用的 FATAL: database "root" does not exist、Public Key Retrieval is not allowed 均实测出自该文件）。

八、参考链接