# Native vs JDBC Agents in DBX: Understanding the Key Differences > Explore native vs JDBC agents in DBX. Understand how Go/Rust agents connect directly versus JDBC agents using a JVM. Learn key differences to optimize your database integrations. - Repository: [skyler/dbx](https://github.com/t8y2/dbx) - Tags: deep-dive - Published: 2026-07-10 --- **Native (Go/Rust) agents are self-contained executables that communicate directly with databases using native drivers, while JDBC agents are Java processes that rely on JDBC drivers and require a JVM, with both types connecting to the DBX UI via JSON-RPC 2.0.** The `t8y2/dbx` repository implements a dual-agent architecture to support database connections. Understanding the difference between native agents and JDBC agents is essential for optimizing performance and resource usage in your database workflows. ## Implementation and Runtime Architecture DBX agents run as separate processes that communicate with the main application through stdin/stdout using JSON-RPC 2.0. However, their underlying implementations differ significantly. ### Native Go/Rust Agents Native agents compile to single binary executables (`agent`) written in **Go** or **Rust**. These agents utilize native database drivers—such as `go-ora` for Oracle or Xugu's Go driver—to communicate directly with the database server. Because they are compiled binaries, native agents require **no Java Runtime Environment** and start immediately without virtual machine initialization overhead. According to the [`agents/README.md`](https://github.com/t8y2/dbx/blob/main/agents/README.md) in the `t8y2/dbx` source code, native agents are selected when a mature, license-compatible native driver exists, and they serve as the default fallback for supported databases. ### JDBC Java Agents JDBC agents are **Java JAR files** (`agent.jar`) built with Gradle that wrap standard JDBC drivers (e.g., Oracle JDBC, PostgreSQL JDBC). These agents require a Java Runtime Environment to execute. When you use a JDBC agent, DBX automatically installs **JRE 21** specifically for Java agents if not already present. The JVM starts even when the agent is idle, creating higher baseline memory usage compared to native alternatives. ## Performance and Resource Characteristics **Memory footprint** represents the most visible difference between the two agent types. Native agents maintain a small memory footprint and fast startup because only the native driver loads into memory. Conversely, JDBC agents incur the overhead of JVM initialization and runtime management regardless of actual database activity. **Startup latency** also favors native implementations. Since native agents skip the JVM boot sequence, they connect to databases faster, making them preferable for connection pooling scenarios implemented in [`crates/dbx-core/src/agent_driver.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/agent_driver.rs). ## Installation and Build Process The installation flow differs based on agent type, though both ultimately reside in the `~/.dbx/agents/drivers//` directory. ### Building Native Agents To build a native Go agent, navigate to the specific driver directory and compile the executable: ```bash # Build the native executable cd agents/drivers/oracle-go go build -o agent . # Install for DBX mkdir -p ~/.dbx/agents/drivers/oracle cp agent ~/.dbx/agents/drivers/oracle/agent chmod +x ~/.dbx/agents/drivers/oracle/agent ``` This process produces a self-contained binary that DBX spawns directly when establishing Oracle connections. ### Building JDBC Agents JDBC agents require Gradle to build a shadow JAR containing all dependencies: ```bash # Build the JAR with Gradle cd agents/drivers/oracle-legacy ./gradlew shadowJar # produces build/libs/-all.jar # Install for DBX mkdir -p ~/.dbx/agents/drivers/oracle-legacy cp build/libs/*-all.jar ~/.dbx/agents/drivers/oracle-legacy/agent.jar ``` DBX launches these JAR files as separate Java processes, handling the JVM invocation automatically. ## Agent Registration and Discovery Both agent types register through the same JSON-RPC contract and appear in [`agents/versions.json`](https://github.com/t8y2/dbx/blob/main/agents/versions.json). The critical difference lies in the executable specification: - **Native agents**: The [`versions.json`](https://github.com/t8y2/dbx/blob/main/versions.json) entry points to an executable binary file named `agent` - **JDBC agents**: The entry points to `agent.jar`, triggering DBX to invoke the Java runtime The core Rust code in [`crates/dbx-core/src/agent_driver.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/agent_driver.rs) handles both types uniformly after spawn, creating driver pools regardless of the underlying implementation language. ## When to Use Each Agent Type **Choose native agents** when available for your database type. The `t8y2/dbx` source explicitly recommends native agents for Oracle (via `go-ora`) and XuguDB, as these implementations avoid JVM overhead while maintaining full protocol compatibility. **Choose JDBC agents** when no stable native driver exists or when the native implementation lacks specific features required for your database version. Most legacy database support in DBX utilizes JDBC agents due to the maturity of Java database connectivity libraries. ## Summary - **Native agents** are Go/Rust binaries using direct database drivers with minimal memory footprint and no JRE dependency. - **JDBC agents** are Java JARs requiring JRE 21 and JVM overhead, used when native drivers are unavailable. - Both communicate via JSON-RPC 2.0 through stdin/stdout, with registration handled identically in [`agents/versions.json`](https://github.com/t8y2/dbx/blob/main/agents/versions.json). - Build native agents with `go build`, JDBC agents with `./gradlew shadowJar`. - Installation paths follow the pattern `~/.dbx/agents/drivers//` with `agent` (native) or `agent.jar` (JDBC). ## Frequently Asked Questions ### Do native agents and JDBC agents use the same communication protocol? Yes, both agent types implement the identical JSON-RPC 2.0 protocol over stdin/stdout. The DBX core in [`crates/dbx-core/src/agent_driver.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/agent_driver.rs) treats them interchangeably after process spawn, meaning you can switch between agent types for the same database without changing connection logic. ### Why does DBX install JRE 21 automatically? DBX installs JRE 21 specifically to support JDBC agents because they require a Java Runtime Environment to execute. Native agents do not trigger this installation since they run as compiled binaries without virtual machine dependencies. ### Can I switch between native and JDBC agents for the same database? Yes, provided both implementations exist for your database type. Simply place the desired agent executable (`agent`) or JAR (`agent.jar`) in the respective `~/.dbx/agents/drivers//` directory. Ensure only one type is present per directory, or specify the preferred agent in your configuration according to the [`agents/README.md`](https://github.com/t8y2/dbx/blob/main/agents/README.md) guidelines. ### Which agent type provides better performance? Native agents generally provide better performance due to lower startup latency and reduced memory consumption. They avoid JVM initialization overhead and run closer to the operating system level. However, JDBC agents may offer better compatibility for edge-case database features or legacy systems where mature native drivers do not exist.