AGENTS.md

1# DBeaver – AI Agent Instructions
2 
3## What is DBeaver?
4 
5DBeaver Community Edition (CE) is a free, open-source, multi-platform database management tool written in **Java**. It supports 100+ database drivers out of the box and is built on **Eclipse RCP** with an **OSGi** plugin architecture. The commercial product shares the same model layer as DBeaver CE and the browser-based [CloudBeaver](https://github.com/dbeaver/cloudbeaver).
6 
7---
8 
9## Repository Layout
10 
11```
12dbeaver/
13├── plugins/          # OSGi bundles (source code)
14│   ├── org.jkiss.dbeaver.model/          # Core API interfaces (no UI, no JDBC)
15│   ├── org.jkiss.dbeaver.model.jdbc/     # JDBC base implementations
16│   ├── org.jkiss.dbeaver.model.sql/      # SQL model (dialect, LSM parser glue)
17│   ├── org.jkiss.dbeaver.model.lsm/      # ANTLR4-based SQL parser
18│   ├── org.jkiss.dbeaver.core/           # Desktop RCP application core
19│   ├── org.jkiss.dbeaver.registry/       # Driver/connection registry
20│   ├── org.jkiss.dbeaver.ext.{db}/       # Per-DB model plugin (no UI deps)
21│   ├── org.jkiss.dbeaver.ext.{db}.ui/    # Per-DB UI plugin
22│   ├── org.jkiss.dbeaver.ui.*/           # Shared UI components
23│   └── org.jkiss.dbeaver.osgi.test.runner/ # OSGi JUnit 5 test harness
24├── test/             # OSGi test plugins (eclipse-test-plugin packaging)
25│   ├── org.jkiss.dbeaver.ext.{db}.test/
26│   └── org.jkiss.dbeaver.model.sql.test/
27├── features/         # Eclipse feature descriptors
28├── product/          # Product configurations & aggregator POMs
29│   └── aggregate/    # Top-level Maven build entry point
30├── docs/
31│   ├── codestyle/eclipse-formatter-profile.xml
32│   ├── license_header.txt
33│   └── devel.txt     # Branch/process overview
34├── pom.xml           # Root Tycho Maven POM
35└── project.deps      # External dependency repo names (e.g. "dbeaver-common")
36```
37 
38The build depends on a sibling repository called **`dbeaver-common`** (must be checked out at `../dbeaver-common`).
39 
40---
41 
42## Technology Stack
43 
44| Layer | Technology |
45|-------|-----------|
46| Language | Java 21 |
47| Plugin system | OSGi / Eclipse Equinox |
48| UI framework | Eclipse RCP (SWT + JFace) |
49| Build system | Apache Maven + Eclipse Tycho |
50| DB connectivity | JDBC; optional ODBC/NoSQL in EE |
51| SQL parsing | JSQLParser, ANTLR4 (LSM module) |
52| Testing | JUnit 5, Mockito, custom OSGi test runner |
53 
54---
55 
56## Build System
57 
58DBeaver uses **Eclipse Tycho** (Maven plugin for OSGi). Each plugin is packaged as `eclipse-plugin`; test plugins as `eclipse-test-plugin`.
59 
60### Building
61 
62```bash
63# Full build from the aggregator
64mvn package -f product/aggregate/pom.xml -Pproduct-dbeaver-ce,product-dbeaver-eclipse-ce
65 
66# Build only a single plugin (fast iteration)
67mvn package -f plugins/org.jkiss.dbeaver.ext.mysql/pom.xml
68```
69 
70> **CI** runs the same command via the reusable workflow in `.github/workflows/push-pr-devel.yml`.
71 
72### Plugin packaging rules
73 
74- Every plugin has a `META-INF/MANIFEST.MF` (bundle metadata) and a `pom.xml` with `<packaging>eclipse-plugin</packaging>`.
75- Dependencies between plugins are declared in `MANIFEST.MF` under `Require-Bundle:`, **not** in `pom.xml`.
76- `plugin.xml` declares Eclipse extension points and extensions.
77- All source is under `src/` (no `src/main/java`).
78 
79---
80 
81## Code Conventions
82 
83### Package and class naming
84 
85| Prefix | Meaning | Example |
86|--------|---------|---------|
87| `DBP*` | Platform-level capability | `DBPDataSource`, `DBPObject` |
88| `DBS*` | Database structure/metadata | `DBSObject`, `DBSTable`, `DBSSchema` |
89| `DBC*` | Connectivity (execution context) | `DBCSession`, `DBCException` |
90| `DBD*` | Data values/formatting | `DBDValueHandler`, `DBDDataFilter` |
91| `DBR*` | Runtime (progress, jobs) | `DBRProgressMonitor`, `DBRRunnableWithProgress` |
92| `JDBC*`| JDBC-specific implementations | `JDBCDataSource`, `JDBCSQLDialect` |
93 
94All production code lives in the `org.jkiss.dbeaver.*` namespace.
95 
96### License header
97 
98Every Java file **must** begin with:
99 
100```java
101/*
102 * DBeaver - Universal Database Manager
103 * Copyright (C) 2010-<year> DBeaver Corp and others
104 *
105 * Licensed under the Apache License, Version 2.0 (the "License");
106 * ...
107 */
108```
109 
110See `docs/license_header.txt` for the canonical template.
111 
112### Annotations
113 
114- Use `@NotNull` and `@Nullable` from `org.jkiss.code` on all method parameters and return types where applicable.
115- Expose object properties to the UI via `@Property` (from `org.jkiss.dbeaver.model.meta`) on getter methods.
116- Mark associations (child collections) with `@Association`.
117- Use `@ForTest` on members that exist solely for unit-testing access.
118 
119### Logging
120 
121```java
122private static final Log log = Log.getLog(MyClass.class);
123// ...
124log.debug("...");
125log.warn("...", exception);
126log.error("...", exception);
127```
128 
129`Log` is `org.jkiss.dbeaver.Log`. Do **not** use `System.out/err` or SLF4J directly.
130 
131### Exception handling
132 
133- `DBException` (and its subclasses like `DBCException`, `DBDatabaseException`) are the standard checked exceptions for database errors.
134- Wrap JDBC `SQLException` in `DBException` when surfacing to upper layers.
135- Use `DBWorkbench.getPlatform()` to access platform services (not static singletons passed around).
136 
137### Progress monitoring
138 
139Long-running operations always accept a `DBRProgressMonitor`:
140 
141```java
142public void doSomething(DBRProgressMonitor monitor) throws DBException {
143    monitor.beginTask("Loading...", 100);
144    try {
145        // work
146        monitor.worked(50);
147    } finally {
148        monitor.done();
149    }
150}
151```
152 
153Use `VoidProgressMonitor.INSTANCE` in tests when a real monitor is not needed.
154 
155### NLS / Localization
156 
157- Each plugin that has user-visible strings has a `*Messages.java` + `*Messages.properties` (and locale variants).
158- Reference strings as `Messages.MY_STRING_KEY`.
159- `plugin.xml` uses `%key` references to the `plugin.properties` file.
160 
161---
162 
163## Architecture Patterns
164 
165### Model / UI separation
166 
167Plugins are split into pure-model (`ext.mysql`) and UI (`ext.mysql.ui`) bundles. Model plugins **must not** import SWT, JFace, or Eclipse workbench packages. This separation allows the model layer to be reused in server-side products (CloudBeaver).
168 
169### Extension-point driven design
170 
171Features are contributed via Eclipse extension points declared in `plugin.xml`. Key extension points:
172 
173| Extension point ID | Purpose |
174|-------------------|---------|
175| `org.jkiss.dbeaver.dataSourceProvider` | Register a new database driver/provider |
176| `org.jkiss.dbeaver.navigator` (via tree config in plugin.xml) | Define the navigator tree structure for a database |
177| `org.jkiss.dbeaver.service` | Register a service implementation |
178| `org.jkiss.dbeaver.dataFormatter` | Register a data formatter |
179| `org.jkiss.dbeaver.dataTypeProvider` | Register value handler for a SQL type |
180 
181### Adding a new database driver
182 
183> **Note**: For many drivers, updating `plugin.xml` alone is enough — you only need to implement Java classes when the existing JDBC infrastructure does not cover your use case.
184 
1851. Create `plugins/org.jkiss.dbeaver.ext.{db}/` with `META-INF/MANIFEST.MF`, `plugin.xml`, and a `pom.xml` (`eclipse-plugin`).
1862. Add an optionally-UI sibling `plugins/org.jkiss.dbeaver.ext.{db}.ui/`.
1873. Implement `DBPDataSourceProvider<YourDataSource>` → register it in `plugin.xml` under `org.jkiss.dbeaver.dataSourceProvider`.
1884. Implement `JDBCDataSource` (from `org.jkiss.dbeaver.model.jdbc`) for JDBC-based drivers.
1895. Implement `SQLDialect` (or extend `JDBCSQLDialect`) for SQL syntax specifics.
1906. Add the new plugin to `plugins/pom.xml` `<modules>` list.
1917. Add a test plugin `test/org.jkiss.dbeaver.ext.{db}.test/` and register it in `test/pom.xml`.
192 
193### JDBCUtils and result set reading
194 
195The utility class `org.jkiss.dbeaver.model.impl.jdbc.JDBCUtils` (in `org.jkiss.dbeaver.model.jdbc` bundle) contains `safeGet*` helpers for reading from `ResultSet`/`JDBCResultSet` without checked exceptions:
196 
197```java
198String name = JDBCUtils.safeGetString(dbResult, "table_name");
199long oid = JDBCUtils.safeGetLong(dbResult, "oid");
200```
201 
202---
203 
204## Testing
205 
206### Test structure
207 
208- Test plugins are in the `test/` directory.
209- Each test plugin mirrors a production plugin: `test/org.jkiss.dbeaver.ext.postgresql.test/`.
210- Tests extend `DBeaverUnitTest` (from `org.jkiss.dbeaver.osgi.test.runner`) or use `@RunWithApplication`/`@RunWithProduct` annotations for integration tests that need a running OSGi container.
211 
212### Running tests
213 
214Tests are run by Maven Tycho as part of the standard build. There is no separate test-only Maven command; tests execute during `mvn package` (or `mvn verify`) when the `desktop` profile is active (it is active by default when `!headless-platform`).
215 
216### Writing tests
217 
218```java
219import org.jkiss.junit.DBeaverUnitTest;
220import org.junit.jupiter.api.Test;
221import static org.junit.jupiter.api.Assertions.*;
222 
223public class MyFeatureTest extends DBeaverUnitTest {
224 
225    @Test
226    public void shouldDoSomething() {
227        // given
228        var query = new SQLQuery(null, "SELECT 1");
229        // then
230        assertFalse(query.isDropDangerous());
231    }
232}
233```
234 
235Use Mockito for mocking. Common mocks: `DBRProgressMonitor`, `DBPDataSourceContainer`, `DBPDataSource`.
236 
237---
238 
239## Branches and Git Workflow
240 
241- **`devel`** — the main development branch; all PRs must target this branch.
242- **`master`** — inactive branch; do not use or commit to it.
243- **Release branches** — exist for each release; never commit to them directly.
244- Pull requests that only fix typos, formatting, or trivial refactoring are generally **not accepted** per the contributor guide.
245- **Naming convention**: issues, commit messages, and PR titles should follow the format `org/repo#issueNumber title` (e.g., `dbeaver/dbeaver#12345 Fix NPE in PostgreSQL dialect`).
246- **Branch naming**: branches should follow the format `org/project#issueNumber-issueTitle` (e.g., `dbeaver/dbeaver#12345-fix-npe-postgresql`).
247- **Linking PRs to issues**: always link a pull request to its corresponding GitHub issue. Use the GitHub UI "Development" link on the PR sidebar when possible; if a direct link is not available, add `Closes org/project#issueNumber` in the PR description (e.g., `Closes dbeaver/dbeaver#12345`).
248- **AI-generated PRs**: large pull requests that are entirely AI-generated are strongly discouraged. Keep AI-assisted contributions focused and small, and ensure each change is understood and reviewed by a human contributor.
249- **AI tools disclosure**: if AI tools were used to generate code, mention it in the PR description. Example: *This PR was generated with AI (GitHub Copilot)*.
250 
251---
252 
253## Common Pitfalls / Known Issues
254 
2551. **Build requires sibling `dbeaver-common`**: The root `pom.xml` references `../dbeaver-common/pom.xml` as its parent. Clone `dbeaver-common` alongside this repo before building.
2562. **No `src/main/java`**: Sources live directly under `src/` (Tycho convention for OSGi plugins). Do not create Maven standard directory layout.
2573. **Dependencies in `MANIFEST.MF`, not `pom.xml`**: Adding a dependency means editing `Require-Bundle:` in `META-INF/MANIFEST.MF`. Maven `<dependencies>` are only for Maven-only artifacts resolved via P2 (`pomDependencies=consider`).
2584. **UI thread safety**: All SWT/UI updates must run on the display thread. Use `UIUtils.asyncExec(Runnable)` or `UIUtils.syncExec(Runnable)` (from `org.jkiss.dbeaver.ui`).
2595. **`@Property` on getters only**: The `@Property` annotation is processed reflectively at runtime; it must be placed on the getter method, not the field.
2606. **Java 21 required**: The target platform requires `JavaSE-21`. Do not use preview features.
261 
262---
263 
264## Key Files Quick Reference
265 
266| File | Purpose |
267|------|---------|
268| `pom.xml` (root) | Tycho build configuration, Java version, target platforms |
269| `plugins/pom.xml` | Aggregator listing all plugin modules |
270| `test/pom.xml` | Aggregator listing all test modules |
271| `product/aggregate/pom.xml` | Top-level build entry point used by CI |
272| `plugins/org.jkiss.dbeaver.model/META-INF/MANIFEST.MF` | Core API bundle exports |
273| `docs/license_header.txt` | Required license header for Java files |
274| `docs/devel.txt` | Brief contributor workflow notes |
275| `.github/workflows/push-pr-devel.yml` | CI: build on PR and push to `devel` |
276 
277## Code Contribution Guide
278 
279For detailed contribution instructions, see the [Code contribution guide](https://github.com/dbeaver/dbeaver/wiki/Contribute-your-code).
280