Native vs JDBC Agents in DBX: Understanding the Key Differences

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 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.

Installation and Build Process

The installation flow differs based on agent type, though both ultimately reside in the ~/.dbx/agents/drivers/<db-type>/ directory.

Building Native Agents

To build a native Go agent, navigate to the specific driver directory and compile the executable:

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

# Build the JAR with Gradle

cd agents/drivers/oracle-legacy
./gradlew shadowJar   # produces build/libs/<module>-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. The critical difference lies in the executable specification:

• Native agents: The 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 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.
• Build native agents with go build, JDBC agents with ./gradlew shadowJar.
• Installation paths follow the pattern ~/.dbx/agents/drivers/<db-type>/ 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 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/<db-type>/ directory. Ensure only one type is present per directory, or specify the preferred agent in your configuration according to the 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}