DBeaver Administrator & Developer Guide

This guide is the in-depth, source-based reference for administrators, architects, and developers who deploy, operate, customize, or contribute to DBeaver Community Edition — the universal database manager built on the Eclipse Rich Client Platform. It complements the User Guide (which covers day-to-day usage) by focusing on architecture, configuration internals, security, build/deployment, and the plugin model.

DBeaver is a desktop application, not a server, so "administration" here means: standardizing deployments, managing drivers and workspaces, hardening credential and network handling, and extending the platform. Developers will find a complete map of the codebase, its extension points, and how to build it.

Table of Contents

1. Executive Summary
2. Architecture
3. Repository & Module Structure
4. Extension Points & the Plugin Model
5. System Requirements
6. Configuration Reference
7. The Workspace
8. Security
9. Build & Packaging
10. Deployment & Operations
11. Single-Instance Control Server
12. Internationalization
13. Logging & Diagnostics
14. Testing Strategy
15. Code Patterns & Conventions
16. Extending DBeaver
17. Troubleshooting (Operational)
18. Potential Improvements & Tech Notes
19. Contributing
20. Quick Reference

1. Executive Summary

DBeaver's central design idea is a uniform model over heterogeneous databases: every engine is a plugin that contributes drivers and maps its catalog into a shared object model (DBP* interfaces). The application, the navigator, SQL tooling, ER diagrams, and the data grid all operate against that abstraction, which is why behavior is consistent across dozens of very different databases.

The codebase is large (~9,500 files, ~12.7 MB of source across ~500 high-signal source folders). It is organized as a classic Eclipse plugin/feature/product reactor.

Note

This repository builds the Community Edition. It declares a parent POM (com.dbeaver.common.main) from a separate dbeaver-common repository, and several drivers are "extended in pro" — those enhancements live in commercial editions outside this tree.

2. Architecture

2.1 Layered overview

┌──────────────────────────────────────────────────────────────┐
│  Products & Features (Tycho)                                   │
│  org.jkiss.dbeaver.ce / msstore / standalone / ide / debug ... │
├──────────────────────────────────────────────────────────────┤
│  UI layer (SWT/JFace, E4 workbench)                            │
│  ui, ui.navigator, ui.editors.sql, ui.editors.data,           │
│  ui.editors.erd, ui.dashboard, ui.ai, data.transfer.ui ...    │
├──────────────────────────────────────────────────────────────┤
│  Application / runtime                                         │
│  core, ui.app.standalone, ui.app.eclipse, headless, launcher  │
├──────────────────────────────────────────────────────────────┤
│  Registry & services                                          │
│  registry (DataSourceProviderRegistry, drivers), tasks,       │
│  model.sm (secrets), model.cli, net.ssh(.jsch/.sshj)          │
├──────────────────────────────────────────────────────────────┤
│  Model (the abstraction layer)                                │
│  model, model.sql, model.jdbc, model.sql.jdbc, model.navigator│
│  model.erd, model.dashboard, model.ai, model.lsm, model.lsp   │
├──────────────────────────────────────────────────────────────┤
│  Per-database extensions (ext.*)                              │
│  ext.postgresql, ext.mysql, ext.oracle, ext.mssql, ext.db2,   │
│  ext.snowflake, ext.clickhouse, ext.sqlite, ... (40+ engines) │
├──────────────────────────────────────────────────────────────┤
│  OSGi / Eclipse Equinox runtime + bundled JRE + JDBC drivers  │
└──────────────────────────────────────────────────────────────┘

2.2 OSGi and the Eclipse RCP foundation

DBeaver runs on the Equinox OSGi runtime. Every plugin is an OSGi bundle with a MANIFEST.MF declaring its symbolic name, version, dependencies (Require-Bundle/Import-Package), and exported packages. Bundles are started lazily; DBeaver logs each bundle activation to stderr (unless quiet mode is on) via an OSGi EventHook registered by CoreApplicationActivator.

The UI is the E4 workbench. The runtime model lives in workbench.xmi under the workspace (.metadata/.plugins/org.eclipse.e4.workbench/workbench.xmi). DBeaver post-processes this model:

• WorkbenchPatcher rewrites part icons in workbench.xmi to match the icons declared by contributed view/editor extensions, and detects when contributed view placeholders are missing (signaling that a perspective reset is advisable).
• A PatchClassLoaderHook participates in Equinox class/resource loading.
• An awt.injector helper library adds --add-exports java.desktop/java.awt.peer=ALL-UNNAMED to integrate AWT peers where needed.

2.3 Application entry points

2.4 The model abstraction (DBP*)

The model layer defines DBeaver's vocabulary as interfaces, prefixed DBP (DBeaver Platform), DBC (connection/execution), DBS (structure), DBA (administration/auth), DBR (runtime), etc. Key types you will encounter throughout the code:

Access to the running platform is centralized: DBWorkbench.getPlatform() returns the platform, from which you reach the workspace, the DataSourceProviderRegistry, and other services. This is the seam used by both the GUI and the CLI.

2.5 Data source provider registry

DataSourceProviderRegistry (singleton) holds all DataSourceProviderDescriptors contributed by ext.* plugins. Each descriptor exposes its drivers (DBPDriver), which carry categories, embedded/download flags, replacement info, and the JDBC library references. This registry is what the New Connection wizard, the database-driver-list CLI command, and metadata loading all consult.

3. Repository & Module Structure

The repository is a Maven/Tycho reactor with three top-level modules plus tests.

dbeaver/
├── pom.xml                 # reactor root (groupId org.jkiss.dbeaver)
├── plugins/                # OSGi bundles (the bulk of the code)
├── features/               # Eclipse features (groupings of plugins)
├── product/                # product definitions, repositories, packaging
└── test/                   # test bundles (desktop profile)

3.1 Plugin families (plugins/org.jkiss.dbeaver.*)

Note

The ext.* split (ext.foo + ext.foo.ui) keeps the database model independent of the desktop UI, so engines can be used in headless contexts. The ext.foo.ui.config packages hold connection-page UI and config wizards.

3.2 Feature modules (features/)

Features group plugins for packaging and update sites:

org.jkiss.dbeaver.app.base.feature, app.local.feature, ce.feature, db.feature, db.ui.feature, debug.feature, ext.office.feature, git.feature, ide.feature, msstore.feature, rcp.feature, runtime.feature, standalone.feature, ui.feature, ui.extra.feature, ui.test.feature, test.base.feature, test.feature.

3.3 Product modules (product/)

community, community-msstore, aggregate, repositories (per-feature update sites: ce, debug, git, office), snap-build (Linux Snap), testing (the CE standalone product, version 24.3.1-SNAPSHOT).

4. Extension Points & the Plugin Model

DBeaver is extended both through Eclipse extension points (declared in plugin.xml) and DBeaver-specific registries.

4.1 DBeaver extension points (selected)

It also consumes standard Eclipse extension points (org.eclipse.ui.views, editors, perspectiveExtensions, commands, handlers, preference pages, etc.).

4.2 The command-line extension point

org.jkiss.dbeaver.commandLine accepts two element types, loaded at class-init time of ApplicationCommandLine:

• parameter → a CLICommandDescriptor wrapping a picocli command class. A descriptor may declare replacedHandler (to supersede another command), exclusiveMode, and forceNewInstance.
• transformer → a CLITransformerDescriptor that mutates the picocli CommandSpec. A transformer with no command class is global (applies to the whole command tree); otherwise it targets a specific command.

The top-level command uses picocli's RunAll execution strategy, a custom CLIHelpFactory, and an ExceptionHandler that surfaces execution exceptions. Commands implement CLIAbstractCommand/CLIAbstractSubcommand (Callable<Void>), obtain a CLIContext, and can run mixins implementing CLIInitializer.

Tip

To add a CLI command in a plugin: implement a picocli @Command extending CLIAbstractSubcommand, then contribute it via org.jkiss.dbeaver.commandLine as a parameter. It is automatically wired into the top-level command tree.

4.3 Preferences

Preferences flow through DBPPreferenceStore. Plugins ship a BundlePreferenceStore and an AbstractPreferenceInitializer that seeds defaults. For example, the data-transfer plugin's initializer sets defaults like name-case mapping, replace mapping, max type length, and "save local settings." A non-persistent SimplePreferenceStore is used in headless contexts (e.g. the CLI translateSQL handler).

5. System Requirements

5.1 Runtime

5.2 Build-time

6. Configuration Reference

DBeaver stores configuration in the workspace, not in a single global config file. The most operationally relevant settings:

6.1 Launcher arguments

These are the supported command-line arguments (also documented for users in the User Guide):

# Example hardened launch: pinned JVM, custom trust store, 4 GB heap, fixed workspace
dbeaver -vm /opt/corp-jdk/bin -data /var/dbeaver/ws \
  -vmargs -Xmx4096m -Djavax.net.ssl.trustStore=/etc/ssl/corp.jks

6.2 Connection configuration

A connection (DBPConnectionConfiguration) carries:

• URL (or host/port/server/database resolved into a URL)
• Auth model id plus user/password
• Connection properties (raw JDBC properties)
• Provider properties (DBeaver/provider-specific)
• Auth properties (auth-model-specific)
• Network handlers (SSH, proxy, SSL)

Connections live per project in the workspace and are managed by each project's DataSourceRegistry.

6.3 Driver configuration

Drivers are defined by providers but can be customized in the Driver Manager: add/override JAR files, change the default URL template, set default properties, and choose download sources. The key.storage.path build property (default /etc/) governs where signing/key material is expected for signed builds.

6.4 Preference scopes

• Default preferences — seeded by each plugin's preference initializer.
• Workspace/instance preferences — your changes, stored in the workspace.
• Some preferences are exposed in Preferences dialogs; others are internal defaults.

7. The Workspace

7.1 Location and layout

The default workspace is the DBeaverData folder in the user's home directory; override it with -data <path>. The workspace contains:

<workspace>/
├── .metadata/                     # Eclipse runtime metadata
│   └── .plugins/org.eclipse.e4.workbench/workbench.xmi   # UI model (patched by WorkbenchPatcher)
│   └── dbeaver-instance.properties # single-instance control registry (see §11)
├── <project>/                     # one folder per project
│   ├── connections (data sources)
│   ├── scripts (.sql)
│   ├── ER diagrams
│   └── bookmarks
└── secure credentials store        # saved passwords/keys

DBPWorkspace.METADATA_FOLDER identifies the metadata directory; GeneralUtils.getMetadataFolder() resolves it at runtime.

7.2 Multi-workspace and portability

Because everything is under one folder, a workspace is portable: copy the -data directory to move connections and scripts (subject to credential-store portability and OS keystore differences). Use distinct -data paths to run isolated DBeaver environments side by side.

Tip

For shared lab machines, give each user a -data under their home and avoid a shared workspace — the single-instance server and credential store assume per-user ownership.

7.3 Resetting

DBeaver offers a guided reset (separate scopes for user preferences and workspace configuration) with apply-and-restart, rather than requiring you to delete the workspace by hand.

8. Security

Security in DBeaver centers on credential storage, network protection, and the local control server.

8.1 Credential storage

• Saved passwords and SSH secrets go into the workspace's secure credentials store (managed by the model.sm / secret-manager subsystem and auth model implementations under model.auth / model.impl.auth).
• Every secret-bearing config (DB password, SSH password/key passphrase) has a save flag. When unchecked, DBeaver prompts at connect time and never persists the secret.

Important

On shared or untrusted machines, configure connections to not save passwords. This keeps secrets out of the workspace entirely.

8.2 Authentication models

Connections specify an auth model id. Beyond native user/password, providers contribute models such as tokens, IAM, and browser/SSO flows (e.g. Snowflake, BigQuery). Auth-model-specific values are stored as auth properties separate from generic connection properties.

8.3 SSH tunneling

The net.ssh subsystem supports four auth configurations, modeled as a sealed interface (SSHAuthConfiguration):

Host config is SSHHostConfiguration(username, hostname, port, auth); forwarding is SSHPortForwardConfiguration(localHost, localPort, remoteHost, remotePort). Two implementations (JSch, SSHJ) are selectable per connection.

Note

SSH host/user/forward values are masked in toString()/logs via SecurityUtils.mask(...). Logs will show masked endpoints even though the real values are used at runtime — this is intentional, not a misconfiguration.

8.4 Transport encryption & proxies

The connection Network tab provides SSL/TLS (certificates, modes) and SOCKS/HTTP proxy support for routing connections.

8.5 The single-instance control server

DBeaver runs a small HTTP control server for single-instance behavior (see §11). Its security properties:

• Loopback only — a request filter rejects any non-loopback address.
• Bearer token — a freshly generated 32-character password (SecurityUtils.generatePassword(32)) guards every request (BearerRequestHandler).
• The port/token/start-time are written to dbeaver-instance.properties in the workspace metadata, with stale PID entries garbage-collected and writes guarded by a FileMutex and atomic file moves.

Caution

Because the control server is loopback-only and token-protected, it is not a network exposure. Do not attempt to bind it to external interfaces — DBeaver does not support that and the filter will reject remote callers.

8.6 Handling untrusted databases

Treat JDBC drivers and database servers as code you are trusting. Only download drivers from sources you trust, and prefer SSH tunnels/SSL when reaching databases over untrusted networks.

9. Build & Packaging

DBeaver builds with Maven + Tycho.

9.1 Reactor

The root pom.xml (org.jkiss.dbeaver:dbeaver:1.0.0-SNAPSHOT, packaging pom) aggregates modules plugins, features, product, and — under the desktop profile (active unless -Dheadless-platform is set) — test.

Key build plugins:

9.2 Building

# Full desktop build (from the dbeaver checkout, with dbeaver-common alongside)
mvn clean verify

# Headless build (no UI/products/tests)
mvn clean verify -Dheadless-platform

Important

The build requires the sibling dbeaver-common repository (the parent POM at ../dbeaver-common/pom.xml). Check out both repositories side by side before building.

9.3 Product output

The tycho-p2-director-plugin materializes the org.jkiss.dbeaver.core.product, archiving per-OS formats: zip for win32, tar.gz for linux/macosx/solaris. macOS uses a DBeaver.app root folder; Windows/Linux use a dbeaver root folder. The CE archive is named dbeaver-ce-${dbeaver-version}. A separate Snap build exists for Linux, and an MSStore distribution for the Microsoft Store.

10. Deployment & Operations

DBeaver is a per-user desktop app, so "deployment" is largely about standardization.

10.1 Standardized rollout

• Distribute the official archive/installer for each OS/arch (or the Snap/MSStore build).
• Pin a JVM with -vm if you need corporate CA certs or a controlled Java version.
• Pre-seed drivers by hosting JDBC JARs internally and configuring driver locations, so analysts don't download from the public internet.
• Templatize launches (heap, trust store, workspace path) via a wrapper script using -data/-vm/-vmargs.

10.2 Driver management at scale

Because drivers download on first use, in locked-down environments you should:

1. Pre-download driver JARs and place them on an internal mirror or local path.
2. Configure each driver's library location in the Driver Manager (or distribute a workspace/driver config).
3. Disable or restrict outbound driver downloads if your policy requires it.

Use the database-driver-list CLI command to enumerate the exact drivers (and their download/embedded/pro flags) a given build supports:

dbeaver database-driver-list /tmp/drivers && cat /tmp/drivers/database.drivers.json

10.3 Backups

• Workspace: back up the -data directory to preserve connections, scripts, and diagrams.
• Database backups: use native tool tasks (tasks.native) wrapping pg_dump/mysqldump/etc. Schedule them via task export + OS scheduler.

Warning

Native dump/restore tools run as external processes and do not traverse DBeaver's in-app SSH tunnel. For databases behind a bastion, run the tool where it can reach the database, or point it at a separately established local tunnel port (see User Guide / issue #40242).

10.4 Unattended execution

Export configured tasks and invoke them from the command line through your OS scheduler for nightly exports, scripted maintenance, or SQL-script runs. Combine with @export for file output without UI interaction.

11. Single-Instance Control Server

DBeaver enforces single-instance behavior with a lightweight local REST server (ApplicationInstanceServer implementing ApplicationInstanceController).

11.1 How it works

1. On startup, the server binds an ephemeral port on localhost, generates a 32-char bearer token, and records {port, password, startedAt} for the current PID into dbeaver-instance.properties (in the workspace metadata folder).
2. The registry is read/written under a FileMutex lock with a 5-second timeout, using atomic file moves; entries for dead/recycled PIDs are garbage-collected.
3. A second launch detects the running instance and forwards its command line (e.g. handleCommandLine(args)), so dbeaver -f file.sql opens in the existing window.

11.2 Controller API

The controller exposes handleCommandLine(args), ping(payload), getVersion(), and getThreadDump() — the last is useful for diagnostics (capturing a stack dump of the running instance).

11.3 Operational notes

• The config file name is dbeaver-instance.properties (ApplicationInstanceController.CONFIG_PROP_FILE).
• If single-instance handoff misbehaves (e.g. after a crash left a stale lock), the stale-PID GC normally self-heals on next launch; otherwise remove the .lock/.tmp siblings of the properties file in the workspace metadata.
• The -reuseWorkspace argument relates to instance/workspace reuse behavior.

12. Internationalization

DBeaver is fully internationalized through Eclipse NLS message bundles. Each UI bundle has a *Messages class (e.g. ResultSetMessages, DTMessages, CoreApplicationMessages) backed by .properties files. Translators add locale files; the -nl <locale> launcher argument forces a UI language. The community actively contributes translations (for example open request #40877 for Traditional Chinese).

Note

When adding user-facing strings in a contribution, add a field to the relevant *Messages class and the default .properties bundle — do not hard-code display text.

13. Logging & Diagnostics

• Logging facade: org.jkiss.dbeaver.Log (Log.getLog(Class)), with a quiet mode check (Log.isQuietMode()). An SLF4J binding bundle (org.jkiss.dbeaver.slf4j) integrates third-party logging.
• Bundle activation tracing: unless quiet, each started bundle prints > Start <name> [<symbolicName> <version>] to stderr.
• Thread dumps: obtainable via the instance controller (getThreadDump()), helpful when the UI hangs.
• Diagnostic info collection: the app provides a "collect diagnostic info" action (see CoreApplicationMessages) to gather logs/state for support.
• Query Manager (QM): data-transfer and query execution can be logged via QM (enable QM logging option), giving an audit trail of executed statements.

Logs live under the workspace .metadata directory (standard Eclipse log location).

14. Testing Strategy

Tests are Tycho-based and run headless.

• The test/ reactor (tests POM) aggregates per-area test bundles: test.platform, plus engine tests (ext.altibase.test, ext.clickhouse.test, ext.firebird.test, ext.generic.test, ext.greenplum.test, ext.hana.test, ext.mysql.test, ext.oracle.test, ext.postgresql.test, ext.snowflake.test, ext.sqlite.test) and model tests (model.lsm.test, model.navigator.test, model.ai.test, model.sql.test, data.transfer.test).
• Execution uses tycho-surefire-plugin with useUIHarness=false/useUIThread=false, including **/*Test.java, running against the headless application/product (org.jkiss.dbeaver.headless.application / .product). The org.jkiss.dbeaver.headless bundle is auto-activated at start level 4.

# Run tests (desktop profile)
mvn clean verify

Tip

Because tests run against the headless platform, new model/logic should be testable without UI. Keep database-engine-specific logic in ext.X (model) bundles, not ext.X.ui, so it can be unit-tested headlessly.

15. Code Patterns & Conventions

Patterns observed throughout the codebase — follow them in contributions:

• Nullness annotations everywhere: @NotNull / @Nullable (org.jkiss.code) on parameters, fields, and returns.
• Interface-first model: depend on DBP*/DBS*/DBC* interfaces, not concrete implementations; resolve services via DBWorkbench.getPlatform().
• Registry/descriptor pattern: capabilities are contributed via extension points and wrapped in *Descriptor classes read at class-init.
• Records & sealed types for value objects (e.g. SSHAuthConfiguration sealed interface with Password/KeyFile/KeyData/Agent records).
• Progress monitors: long operations take a DBRProgressMonitor and are cancellable.
• Atomic file I/O: config/state writes use temp-file-plus-atomic-move and file mutexes (see the instance server).
• NLS for all UI text; //$NON-NLS-1$ markers on intentional non-translatable literals.
• Apache 2.0 license header on every source file (Copyright (C) 2010-<year> DBeaver Corp and others).
• Layered bundles: model vs. UI separation (ext.X vs ext.X.ui) so model code is UI-free and headless-testable.

16. Extending DBeaver

16.1 Add a database

Create an ext.<engine> bundle (model) and optionally ext.<engine>.ui (connection UI/config). Contribute a dataSourceProvider with one or more drivers (JDBC library coordinates, default URL template, properties, auth models). Map the engine's catalog onto the DBS* structure interfaces. Use ext.generic as the closest template for JDBC-compliant engines.

16.2 Add a CLI command

Implement a picocli @Command extending CLIAbstractSubcommand; contribute it via org.jkiss.dbeaver.commandLine (parameter). Optionally add a transformer to adjust the command spec globally or per-command. (See §4.2.)

16.3 Add a data-transfer format

Contribute a stream processor (producer/consumer/processor) so it appears in the Data Transfer wizard and is usable from @export.

16.4 Add an AI provider

Register an engine through the model.ai / ui.ai extension points; supply request/response handling and credentials configuration.

16.5 Running inside Eclipse

The ui.app.eclipse bundle lets DBeaver run as a plugin within an Eclipse IDE — useful if you want DBeaver views/editors alongside Java development.

17. Troubleshooting (Operational)

Issue: App won't start after upgrade

Run dbeaver -clean to clear OSGi/runtime caches. Ensure the new version was installed into a clean folder.

Issue: Stale single-instance lock after a crash

The PID-based GC usually clears it on next launch. If not, delete the .lock/.tmp siblings of dbeaver-instance.properties in <workspace>/.metadata.

Issue: Views misplaced after upgrade

WorkbenchPatcher detects missing contributed views; accept the perspective-reset prompt or run Window → Reset Perspective.

Issue: Driver download blocked by network policy

Pre-stage JDBC JARs internally and set driver library locations in the Driver Manager. Use database-driver-list to inventory required drivers.

Issue: SSH tunnel fails to negotiate

Switch the SSH implementation (JSch ↔ SSHJ) in the connection's SSH settings — they support different key-exchange/cipher sets.

Issue: Native restore over SSH fails

Native tools bypass the in-app tunnel; run them where the DB is reachable or against a separately opened local tunnel port (issue #40242).

Issue: Connections share the wrong session/credentials

Connections identical in host/port/user/database can share a pooled connection (issue #40842). Differentiate the connection definitions.

Issue: High memory use on large exports

Increase heap via -vmargs -Xmx<size> and enable extract in batches with a sensible segment size and thread count.

18. Potential Improvements & Tech Notes

Observations from the source (forward-looking notes, not defects):

• Mixed compiler targets: the standalone awt.injector helper library pins Java 11 (maven.compiler.source/target = 11) while the main reactor uses the parent's ${java.version}. Worth confirming the helper still needs the older target during JDK upgrades.
• Two SSH stacks (JSch + SSHJ) increase maintenance surface but provide valuable fallback for diverse SSH servers. JSch is comparatively dormant upstream; SSHJ is the more actively maintained dependency to favor for new work.
• Open community issues at this commit worth tracking for QA: CSV import delimiter/decimal handling (#40446, #35020), manual-commit behavior (#41173), SQL-editor file/content tracking (#41220, #40741), Informix autocomplete with global search (#40111), and XML export edge cases with empty/labeled columns (#40902).
• Driver download dependency: the first-use download model is convenient but adds an external dependency at connect time. A pre-seed/mirror story (above) is recommended for locked-down fleets.

19. Contributing

• License: Apache 2.0. New files must carry the standard header.
• Repository: https://github.com/dbeaver/dbeaver — issues and PRs welcome.
• Issue tracker: https://github.com/dbeaver/dbeaver/issues for bugs, feature requests, and support.
• Code style: there is a docs/codestyle area in the repo; follow nullness annotations, NLS conventions, and the model/UI separation described in §15.
• Build before submitting: check out dbeaver-common alongside, then mvn clean verify. Add headless tests under the appropriate test/ bundle.
• Translations: contribute locale .properties files for the *Messages bundles.

20. Quick Reference

20.1 Build commands

20.2 Key paths

20.3 Module map (top level)

20.4 Instance controller API

20.5 Key technologies