# 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](#1-executive-summary)
2. [Architecture](#2-architecture)
3. [Repository & Module Structure](#3-repository--module-structure)
4. [Extension Points & the Plugin Model](#4-extension-points--the-plugin-model)
5. [System Requirements](#5-system-requirements)
6. [Configuration Reference](#6-configuration-reference)
7. [The Workspace](#7-the-workspace)
8. [Security](#8-security)
9. [Build & Packaging](#9-build--packaging)
10. [Deployment & Operations](#10-deployment--operations)
11. [Single-Instance Control Server](#11-single-instance-control-server)
12. [Internationalization](#12-internationalization)
13. [Logging & Diagnostics](#13-logging--diagnostics)
14. [Testing Strategy](#14-testing-strategy)
15. [Code Patterns & Conventions](#15-code-patterns--conventions)
16. [Extending DBeaver](#16-extending-dbeaver)
17. [Troubleshooting (Operational)](#17-troubleshooting-operational)
18. [Potential Improvements & Tech Notes](#18-potential-improvements--tech-notes)
19. [Contributing](#19-contributing)
20. [Quick Reference](#20-quick-reference)

---

## 1. Executive Summary

| Aspect | Detail |
|--------|--------|
| **Product** | DBeaver — Universal Database Manager (Community Edition) |
| **Vendor** | DBeaver Corp and others (`dbeaver.io`) |
| **License** | Apache License 2.0 |
| **Language** | Java |
| **Platform** | Eclipse Rich Client Platform (RCP) + OSGi (Equinox) + E4 workbench |
| **UI toolkit** | SWT/JFace (native widgets per OS) |
| **Build system** | Apache Maven with Eclipse **Tycho** |
| **Distribution version (in-dev at this commit)** | `24.3.1-SNAPSHOT` |
| **Target platforms** | Windows (`x86_64`,`aarch64`), Linux GTK (`x86_64`,`aarch64`), macOS Cocoa (`x86_64`,`aarch64`) |
| **CLI framework** | picocli (extensible via extension point) |
| **SSH libraries** | JSch and SSHJ (two interchangeable implementations) |
| **Source** | <https://github.com/dbeaver/dbeaver> |

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

```text
┌──────────────────────────────────────────────────────────────┐
│  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

| Entry | Bundle | Purpose |
|-------|--------|---------|
| Standalone desktop app | `org.jkiss.dbeaver.ui.app.standalone` | The CE desktop application and its CLI handlers. |
| Eclipse plugin app | `org.jkiss.dbeaver.ui.app.eclipse` | DBeaver running as a plugin inside an Eclipse IDE. |
| Headless app | `org.jkiss.dbeaver.headless` | `org.jkiss.dbeaver.headless.application` — used for tests and headless operations (no UI harness). |
| Native launcher | `org.jkiss.dbeaver.launcher` | Native launch bootstrap. |

### 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:

| Interface | Role |
|-----------|------|
| `DBPDataSourceContainer` | A saved connection (configuration + lifecycle). |
| `DBPDataSource` | A live data source (active session(s)). |
| `DBPConnectionConfiguration` | Host, port, URL, database, server, auth model, properties. |
| `DBPDriver` / `DBPDriverLibrary` | A database driver and its JDBC library files. |
| `DBPProject` / `DBPWorkspace` | Project and workspace containers. |
| `DBRProgressMonitor` | Cancellable progress for long operations. |
| `DBPPreferenceStore` | Hierarchical preferences. |

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 `DataSourceProviderDescriptor`s 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.

```text
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.*`)

| Family | Representative bundles | Responsibility |
|--------|------------------------|----------------|
| **Model** | `model`, `model.sql`, `model.jdbc`, `model.sql.jdbc`, `model.navigator`, `model.erd`, `model.dashboard`, `model.event`, `model.nio`, `model.rcp`, `model.sm`, `model.cli`, `model.ai`, `model.lsm`, `model.lsp` | The abstraction layer: connections, SQL parsing/semantics, JDBC mapping, navigator model, secrets, CLI model, AI model, SQL language services. |
| **Registry** | `registry` | Data source providers, drivers, settings, task registries. |
| **Core/App** | `core`, `ui.app.standalone`, `ui.app.eclipse`, `ui.app.devtools`, `ui.app.msstore`, `headless`, `launcher` | Application bootstrap, core UI services, CLI handlers. |
| **UI** | `ui`, `ui.navigator`, `ui.forms`, `ui.charts`, `ui.statistics`, `ui.search`, `ui.dashboard`, `ui.ai`, `ui.config.*`, `ui.swt.{windows,linux,macos}` | The SWT/JFace presentation layer and OS-specific bits. |
| **Editors** | `ui.editors.sql`, `ui.editors.data`, `ui.editors.entity`, `ui.editors.erd`, `ui.editors.base`, `ui.editors.hex`, `ui.editors.json`, `ui.editors.xml`, `ui.editors.image`, `ui.editors.acl`, `ui.editors.locks`, `ui.editors.session`, `ui.editors.sql.terminal` | SQL editor, data grid, object editors, and specialized value editors. |
| **Tools** | `data.transfer`(+`.ui`), `data.office`(+`.ui`), `data.gis`(+`.view`), `tasks.ui`, `tasks.native`(+`.ui`), `tasks.sql.ui`, `cmp.simple`(+`.ui`), `team.git.ui` | Data transfer, office/GIS rendering, tasks, native tools, compare, Git. |
| **Networking** | `net.ssh`, `net.ssh.jsch`, `net.ssh.sshj`, `net.ssh.ui` | SSH tunneling (two implementations + UI). |
| **Debug** | `debug.core`, `debug.ui`, `ext.postgresql.debug.*` | Procedure debugging (e.g. PostgreSQL/pgSQL). |
| **Database extensions** | `ext.postgresql`, `ext.mysql`, `ext.oracle`, `ext.mssql`, `ext.db2`(+`.i`,`.zos`), `ext.snowflake`, `ext.clickhouse`, `ext.sqlite`, `ext.exasol`, `ext.vertica`, `ext.bigquery`, `ext.athena`, `ext.hive`, `ext.trino`, `ext.duckdb`, `ext.firebird`, `ext.h2`, `ext.hsqldb`, `ext.derby`, `ext.greenplum`, `ext.netezza`, `ext.teradata`, `ext.cubrid`, `ext.dameng`, `ext.kingbase`, `ext.gaussdb`, `ext.oceanbase`, `ext.tidb`, `ext.starrocks`, `ext.databricks`, `ext.databend`, `ext.spanner`, `ext.iotdb`, `ext.phoenix`, `ext.informix`, `ext.hana`, `ext.altibase`, `ext.ocient`, `ext.denodo`, `ext.gbase8s`, `ext.generic`, `ext.wmi`, … | Per-engine model + UI. Most come as a pair: `ext.X` (model) and `ext.X.ui` (UI/config). |
| **Infra** | `slf4j`, `osgi.test.runner` | SLF4J binding and test runner. |

> [!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)

| Extension point | Contributed by | Purpose |
|-----------------|----------------|---------|
| `org.jkiss.dbeaver.dataSourceProvider` | `ext.*` | Register a database provider and its drivers. |
| `org.jkiss.dbeaver.commandLine` | core/app + plugins | Register CLI **commands** (`parameter`) and **transformers** (see below). |
| `org.jkiss.dbeaver.task` / task registries | `tasks.*`, tools | Register task types (data transfer, SQL script, native tools). |
| Data transfer producers/consumers/processors | `data.transfer*`, `data.office`, `data.gis` | Register transfer endpoints and formats. |
| SSH tunnel implementations | `net.ssh.jsch`, `net.ssh.sshj` | Provide selectable SSH clients. |
| AI engines | `model.ai`, `ui.ai` | Register AI providers for the assistant. |

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

| Requirement | Detail |
|-------------|--------|
| **OS** | Windows, Linux (GTK), macOS — 64-bit (`x86_64` or `aarch64`). |
| **Java** | A modern JDK. Official desktop builds **bundle a JRE**; you only need your own Java if you launch with `-vm`. |
| **Memory** | Defaults suffice for typical use; raise the heap with `-vmargs -Xmx<size>` for very large result sets or exports. |
| **Disk** | Space for the app, the bundled JRE, downloaded JDBC drivers, and your workspace. |
| **Network** | Outbound to your databases; outbound to driver download sites on first connection; outbound to your AI provider only if the assistant is enabled. |

### 5.2 Build-time

| Requirement | Detail |
|-------------|--------|
| **Java** | JDK matching the `${java.version}` property from the parent `dbeaver-common` POM. |
| **Maven** | With the Tycho extension (declared in the build). |
| **Parent POM** | `com.dbeaver.common.main` `2.7.0-SNAPSHOT` from a sibling `dbeaver-common` checkout (`../dbeaver-common/pom.xml`). |
| **Target platform** | Provided via Tycho `target-platform-configuration` (Eclipse p2). |

---

## 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):

| Argument | Effect | Admin relevance |
|----------|--------|-----------------|
| `-data <path>` | Workspace location | Standardize a workspace path across machines; place workspaces on fast local disk. |
| `-vm <path>` | Java VM to use | Pin a vetted JVM (e.g. with corporate CA certs). |
| `-vmargs <args>` | JVM options (must be last) | Set heap, proxies, trust stores, system properties. |
| `-nl <locale>` | UI locale | Force a locale for shared kiosks. |
| `-nosplash` | Skip splash | Scripted launches. |
| `-clean` | Clear runtime/OSGi caches | First remedy after upgrades. |
| `-reuseWorkspace` | Reuse running instance | Avoids spawning a second instance. |

```bash
# 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:

```text
<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`):

| Configuration | Fields |
|---------------|--------|
| `Password` | password, `savePassword` |
| `KeyFile` | key file path, optional passphrase, `savePassword` |
| `KeyData` | inline key data, optional passphrase, `savePassword` |
| `Agent` | (delegates to the SSH agent) |

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](#11-single-instance-control-server)). 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:

| Plugin | Role |
|--------|------|
| `tycho-maven-plugin` (extensions) | Enables the Tycho lifecycle for OSGi artifacts. |
| `target-platform-configuration` | Declares the 6 OS/arch environments and `pomDependencies=consider`. |
| `tycho-compiler-plugin` | Compiles with `source`/`target`/`compilerVersion` = `${java.version}`, `useProjectSettings=false`. |
| `tycho-packaging-plugin` | Stamps manifests with `Built-By`/`Created-By=dbeaver.io` and a build timestamp. |
| `tycho-p2-director-plugin` | Materializes products into per-OS archives. |
| `tycho-p2-repository-plugin` | Generates (or, for testing, suppresses) p2 repositories. |

### 9.2 Building

```bash
# 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:

```bash
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](https://github.com/dbeaver/dbeaver/issues/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](https://github.com/dbeaver/dbeaver/issues/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.

```bash
# 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](#42-the-command-line-extension-point).)

### 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](https://github.com/dbeaver/dbeaver/issues/40242)).

### Issue: Connections share the wrong session/credentials

Connections identical in host/port/user/database can share a pooled connection (issue [#40842](https://github.com/dbeaver/dbeaver/issues/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](https://github.com/dbeaver/dbeaver/issues/40446), [#35020](https://github.com/dbeaver/dbeaver/issues/35020)), manual-commit behavior ([#41173](https://github.com/dbeaver/dbeaver/issues/41173)), SQL-editor file/content tracking ([#41220](https://github.com/dbeaver/dbeaver/issues/41220), [#40741](https://github.com/dbeaver/dbeaver/issues/40741)), Informix autocomplete with global search ([#40111](https://github.com/dbeaver/dbeaver/issues/40111)), and XML export edge cases with empty/labeled columns ([#40902](https://github.com/dbeaver/dbeaver/issues/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](#15-code-patterns--conventions).
- **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

| Command | Purpose |
|---------|---------|
| `mvn clean verify` | Full desktop build + tests |
| `mvn clean verify -Dheadless-platform` | Headless build (no UI/products/tests) |

### 20.2 Key paths

| Path | Contents |
|------|----------|
| `<home>/DBeaverData` (or `-data <path>`) | Workspace: projects, scripts, prefs, credentials |
| `<workspace>/.metadata` | Eclipse runtime metadata, logs |
| `<workspace>/.metadata/dbeaver-instance.properties` | Single-instance control registry |
| `<workspace>/.metadata/.plugins/org.eclipse.e4.workbench/workbench.xmi` | UI model (icon-patched) |

### 20.3 Module map (top level)

| Module | Contents |
|--------|----------|
| `plugins/` | OSGi bundles (model, registry, ui, editors, ext.*, net.ssh, tasks, …) |
| `features/` | Eclipse features (ce, db, db.ui, debug, office, git, ide, msstore, …) |
| `product/` | Products (community, msstore), repositories, snap-build, testing |
| `test/` | Headless test bundles |

### 20.4 Instance controller API

| Method | Purpose |
|--------|---------|
| `handleCommandLine(args)` | Forward a launch to the running instance |
| `ping(payload)` | Liveness check |
| `getVersion()` | Running product version |
| `getThreadDump()` | Stack dump for diagnostics |

### 20.5 Key technologies

| Tech | Used for |
|------|----------|
| Eclipse RCP / E4 / Equinox OSGi | Application framework, plugin model, UI workbench |
| SWT / JFace | Native UI widgets |
| Maven + Tycho | Build & p2 packaging |
| picocli | Command-line parsing (extensible) |
| JSch / SSHJ | SSH tunneling |
| JDBC | Database connectivity (per-engine drivers) |
| SLF4J | Logging facade binding |

---

_Generated June 2026 from dbeaver/dbeaver at 763486c. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._