# How to Use DBX JDBC Agent Drivers with Hive: A Complete Implementation Guide

> Learn how to use DBX JDBC agent drivers with Hive using the dedicated HiveAgent class. This guide simplifies Hive database access with JSON-RPC and automatic schema handling.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: how-to-guide
- Published: 2026-07-02

---

**TLDR: DBX provides a dedicated `HiveAgent` class that wraps the official Apache Hive JDBC driver to expose Hive databases over a JSON-RPC interface, automatically handling URL construction, schema selection with backtick quoting, and metadata extraction.**

The t8y2/dbx repository includes a specialized Hive JDBC agent that eliminates boilerplate when connecting to Apache Hive. Instead of manually managing driver classes and connection strings, the `HiveAgent` provides a standardized JSON-RPC wrapper around the native `org.apache.hive.jdbc.HiveDriver`, enabling programmatic database operations through simple JSON requests.

## How the Hive Agent Works

The `HiveAgent` class in [`agents/drivers/hive/src/main/java/com/dbx/agent/hive/HiveAgent.java`](https://github.com/t8y2/dbx/blob/main/agents/drivers/hive/src/main/java/com/dbx/agent/hive/HiveAgent.java) serves as a thin but crucial abstraction layer over the generic DBX JDBC plugin. It implements Hive-specific behaviors while inheriting connection management and driver registration from the base `DbxJdbcPlugin`.

### Driver Class and URL Construction

According to the source code, the agent identifies the correct driver class through the `driverClass()` method (lines 25-27), which returns `"org.apache.hive.jdbc.HiveDriver"`. When establishing connections, `buildJdbcUrl()` (lines 72-74) constructs the standard Hive JDBC URL format:

```java
jdbc:hive2://host:port/database

```

This ensures compatibility with HiveServer2 deployments while allowing the generic plugin to recognize Hive URLs via the `jdbc:hive2:` prefix and apply the appropriate *use-catalog* quirk automatically.

### Schema Handling and Metadata Extraction

The agent handles Hive's specific SQL dialect requirements. The `setSchemaSQL()` method (lines 100-103) generates `USE \`schema\`` statements with backtick quoting for safe identifier handling, protecting against reserved word conflicts.

For metadata operations, the agent maps standard JDBC metadata calls to Hive-native commands:

- `listDatabases()` (lines 35-46) executes `SHOW DATABASES`
- `listTables()` (lines 58-71) executes `SHOW TABLES`
- `getColumns()` (lines 74-82) executes `DESCRIBE` commands

These implementations fall back to standard JDBC metadata when native commands are unavailable, providing robust compatibility across Hive versions.

## Configuring the Hive JDBC Connection

Before running queries, you must provide a connection descriptor JSON that specifies the Hive driver location and connection parameters. The `DbxJdbcPlugin.registerDrivers()` method loads driver JARs from the paths specified in `jdbc_driver_paths`, or uses the ServiceLoader if the driver class is omitted.

```json
{
  "jdbc_driver_paths": ["/path/to/hive-jdbc-uber.jar"],
  "jdbc_driver_class": "org.apache.hive.jdbc.HiveDriver",
  "connection_string": "jdbc:hive2://hive-host:10000/default",
  "username": "hive_user",
  "password": "hive_password"
}

```

Specifying `jdbc_driver_class` explicitly prevents the ServiceLoader scan overhead, though the plugin can discover the driver automatically if the class is available on the classpath.

## Running the Hive Agent

The Hive agent operates as a standalone JSON-RPC server over STDIN/STDOUT, making it language-agnostic and suitable for containerized deployments.

### Starting the Agent Process

From the repository root, launch the agent with the appropriate classpath:

```bash
java -cp "$(mvn -q dependency:build-classpath -Dmdep.outputFile=cp.txt && cat cp.txt):agents/drivers/hive/target/classes" \
     com.dbx.agent.hive.HiveAgent

```

This initializes a `JsonRpcServer` instance (defined in [`agents/common/src/main/java/com/dbx/agent/JsonRpcServer.java`](https://github.com/t8y2/dbx/blob/main/agents/common/src/main/java/com/dbx/agent/JsonRpcServer.java)) that listens for line-delimited JSON requests. The `HiveAgent.main()` method (lines 216-219) handles server initialization and request routing.

### Driver Registration and Quirks

When the plugin processes a connection request, it recognizes Hive URLs and applies the *use-catalog* quirk defined in [`plugins/jdbc/src/main/java/app/dbx/jdbc/DbxJdbcPlugin.java`](https://github.com/t8y2/dbx/blob/main/plugins/jdbc/src/main/java/app/dbx/jdbc/DbxJdbcPlugin.java) (lines 98-104). This ensures that `USE <catalog>` statements are sent when a catalog is supplied, maintaining proper database context for Hive connections.

## Querying Hive via JSON-RPC

Once the agent is running, clients send JSON-RPC requests to execute operations. The plugin handles driver registration, connection opening via `DriverManager.getConnection()`, and execution context application.

### Listing Databases and Tables

To retrieve metadata, send requests specifying the connection parameters and target schema:

```bash
cat <<EOF | java -cp "$(cat cp.txt):plugins/jdbc/target/classes" app.dbx.jdbc.DbxJdbcPlugin
{
  "id": 1,
  "method": "listTables",
  "params": {
    "connection": {
      "jdbc_driver_paths": ["/path/to/hive-jdbc-uber.jar"],
      "connection_string": "jdbc:hive2://hive-host:10000/default",
      "username": "hive_user",
      "password": "hive_password"
    },
    "schema": "sales"
  }
}
EOF

```

Under the hood, the agent executes `USE sales; SHOW TABLES;` and returns a structured JSON response containing the table list.

### Executing SQL Queries

For ad-hoc queries, use the `executeQuery` method:

```bash
cat <<EOF | java -cp "$(cat cp.txt):plugins/jdbc/target/classes" app.dbx.jdbc.DbxJdbcPlugin
{
  "id": 2,
  "method": "executeQuery",
  "params": {
    "connection": {
      "jdbc_driver_paths": ["/path/to/hive-jdbc-uber.jar"],
      "connection_string": "jdbc:hive2://hive-host:10000/default",
      "username": "hive_user",
      "password": "hive_password"
    },
    "sql": "SELECT product_id, sum(amount) AS total FROM sales.orders GROUP BY product_id LIMIT 10"
  }
}
EOF

```

The response includes `columns`, `rows`, `execution_time_ms`, and a `truncated` flag if results exceed the internal row limit of 10,000 rows.

## Programmatic Integration

For Java applications, interact with the agent through `ProcessBuilder` to spawn the plugin and communicate via JSON-RPC:

```java
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.nio.file.Files;
import java.nio.file.Paths;

public class HiveClient {
    private static final ObjectMapper MAPPER = new ObjectMapper();

    public static void main(String[] args) throws Exception {
        String connJson = Files.readString(Paths.get("conn.json"));
        ObjectNode request = MAPPER.createObjectNode();
        request.put("id", 1);
        request.put("method", "listColumns");
        request.set("params", MAPPER.createObjectNode()
                .set("connection", MAPPER.readTree(connJson))
                .put("schema", "sales")
                .put("table", "orders"));

        Process proc = new ProcessBuilder(
                "java",
                "-cp", "plugins/jdbc/target/classes",
                "app.dbx.jdbc.DbxJdbcPlugin")
                .redirectError(ProcessBuilder.Redirect.INHERIT)
                .start();

        proc.getOutputStream().write((MAPPER.writeValueAsString(request) + "\n").getBytes());
        proc.getOutputStream().flush();

        String response = new String(proc.getInputStream().readAllBytes());
        System.out.println("Response: " + response);
    }
}

```

This approach allows any language capable of spawning processes and parsing JSON to leverage the full Hive JDBC functionality without direct driver dependencies.

## Summary

- The `HiveAgent` class in [`agents/drivers/hive/src/main/java/com/dbx/agent/hive/HiveAgent.java`](https://github.com/t8y2/dbx/blob/main/agents/drivers/hive/src/main/java/com/dbx/agent/hive/HiveAgent.java) wraps `org.apache.hive.jdbc.HiveDriver` to provide Hive-specific behaviors including URL construction and metadata extraction.
- Connection configuration requires a JSON descriptor specifying `jdbc_driver_paths`, `connection_string`, and credentials.
- The agent runs as a JSON-RPC server over STDIN/STDOUT, initialized via `com.dbx.agent.hive.HiveAgent`.
- Hive-specific quirks like `USE <catalog>` statements are automatically applied by `DbxJdbcPlugin` (lines 98-104) when it detects `jdbc:hive2:` URLs.
- Metadata operations use native Hive commands (`SHOW DATABASES`, `SHOW TABLES`, `DESCRIBE`) for optimal performance.
- Clients communicate via line-delimited JSON-RPC requests, making the agent accessible from any programming language.

## Frequently Asked Questions

### How does DBX handle Hive driver registration?

The `DbxJdbcPlugin.registerDrivers()` method loads Hive driver JARs specified in the `jdbc_driver_paths` array of the connection JSON. If `jdbc_driver_class` is explicitly set to `org.apache.hive.jdbc.HiveDriver`, the plugin uses that class directly; otherwise, it falls back to the ServiceLoader mechanism. The `HiveAgentTest` class (lines 5-10) verifies that the Hive driver and its Thrift protocol classes are present on the classpath before operations begin.

### What is the correct JDBC URL format for Hive connections?

The `HiveAgent.buildJdbcUrl()` method (lines 72-74) constructs URLs following the `jdbc:hive2://host:port/database` pattern. This format triggers the *use-catalog* quirk in [`DbxJdbcPlugin.java`](https://github.com/t8y2/dbx/blob/main/DbxJdbcPlugin.java) (lines 98-104), which ensures proper catalog context through `USE <catalog>` statements when connecting to specific databases.

### How does the Hive agent handle schema selection?

When switching schemas, the `HiveAgent.setSchemaSQL()` method (lines 100-103) generates `USE \`schema\`` statements with backtick quoting. This protects against SQL injection and reserved word conflicts while adhering to Hive's specific syntax requirements for identifier quotation.

### Can I use the Hive agent with languages other than Java?

Yes. The `HiveAgent` exposes functionality through a `JsonRpcServer` that communicates over STDIN/STDOUT using line-delimited JSON-RPC messages. Any language capable of spawning processes, writing JSON to stdin, and reading JSON from stdout can operate the agent, as demonstrated by the Bash examples using `cat` and `java` commands to send requests and receive responses.