# How DBX Handles MySQL Connection Modes: Normal, Bare, and OceanBase Oracle

> Learn how DBX intelligently handles Normal, Bare, and OceanBase Oracle MySQL connection modes by automatically detecting and routing operations for seamless integration.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: deep-dive
- Published: 2026-07-04

---

**DBX automatically selects between Normal, Bare, and OceanBase Oracle MySQL connection modes based on the driver profile and runtime server detection, routing metadata operations to the appropriate driver implementation via the `dispatch_mysql!` macro.**

DBX is a high-performance database client that abstracts multiple database protocols behind a unified interface. It supports three distinct MySQL-related connection modes—**Normal**, **Bare**, and **OceanBase Oracle**—each optimized for specific MySQL-compatible engines. The mode determines which driver implementation handles metadata operations and which session-level SQL statements execute on connect.

## The Three MySQL Connection Modes

DBX defines the `MysqlMode` enum in [`crates/dbx-core/src/connection.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/connection.rs) to distinguish between protocol variants. The mode is stored alongside the connection pool and evaluated at runtime to dispatch metadata calls correctly.

### Normal Mode

**Normal mode** (`MysqlMode::Normal`) is the default behavior for standard MySQL connections. When you configure a vanilla MySQL profile without special flags, DBX uses the standard MySQL driver (`db::mysql`) for all metadata operations, including listing databases, schemas, and tables.

```rust
// crates/dbx-core/src/connection.rs
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum MysqlMode {
    Normal,
    Bare,
    OceanBaseOracle,
}

```

This mode respects full MySQL protocol semantics, including display-width handling and MySQL-specific metadata queries.

### Bare Mode

**Bare mode** (`MysqlMode::Bare`) targets MySQL-compatible engines that expose a stripped-down protocol, such as **Doris**, **StarRocks**, or **Manticore Search**. When the driver profile indicates a bare-compatible engine, DBX creates the pool with the `PoolKind::Mysql(p, MysqlMode::Bare)` variant.

In this mode, the driver skips MySQL-specific behaviors like display-width handling and uses generic protocol implementations. This prevents compatibility errors when connecting to engines that speak MySQL wire protocol but lack full MySQL metadata conventions.

### OceanBase Oracle Mode

**OceanBase Oracle mode** (`MysqlMode::OceanBaseOracle`) activates when connecting to OceanBase servers running in Oracle compatibility mode. When DBX detects `ob_compatibility_mode = 'oracle'` on the server, it switches from the standard MySQL driver to the OceanBase-Oracle driver (`db::ob_oracle`).

This mode is critical because OceanBase in Oracle mode expects Oracle-style SQL syntax for metadata queries—such as `SELECT COMMENTS FROM ALL_TAB_COMMENTS`—and follows Oracle's schema-filtering rules rather than MySQL's. DBX handles this translation automatically without requiring manual configuration changes.

## Runtime Detection and Driver Dispatch

DBX determines the appropriate mode during connection initialization and maintains it throughout the session lifecycle.

### Automatic OceanBase Oracle Detection

When a connection profile specifies `oceanbase`, DBX executes a detection query to determine the server's compatibility mode. In [`crates/dbx-core/src/connection.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/connection.rs), the `detect_ob_oracle_mode` function queries `SHOW VARIABLES LIKE 'ob_compatibility_mode'`.

```rust
// crates/dbx-core/src/connection.rs
async fn detect_ob_oracle_mode(config: &ConnectionConfig, pool: &db::mysql::MySqlPool) -> MysqlMode {
    let profile = config.driver_profile.as_deref().unwrap_or("").to_lowercase();
    if !profile.contains("oceanbase") {
        return MysqlMode::Normal;
    }
    // Query execution determines if server runs in Oracle mode
    if val.to_lowercase() == "oracle" { 
        MysqlMode::OceanBaseOracle 
    } else { 
        MysqlMode::Normal 
    }
}

```

If the returned value is `"oracle"`, the function returns `MysqlMode::OceanBaseOracle`, causing subsequent metadata calls to use the Oracle-compatible driver.

### The dispatch_mysql! Macro

The `dispatch_mysql!` macro in [`crates/dbx-core/src/schema.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/schema.rs) routes metadata calls to the correct implementation based on the active mode:

```rust
// crates/dbx-core/src/schema.rs
macro_rules! dispatch_mysql {
    ($p:expr, $mode:expr, $mysql:path, $ob:path $(, $arg:expr)*) => {
        if *$mode == MysqlMode::OceanBaseOracle {
            $ob($p $(, $arg)*).await
        } else {
            $mysql($p $(, $arg)*).await
        }
    };
}

```

This macro is invoked throughout the metadata layer. For example, when listing schemas, DBX automatically selects the appropriate driver:

```rust
// crates/dbx-core/src/schema.rs
match pool {
    PoolKind::Mysql(p, mode) => dispatch_mysql!(p, mode,
        db::mysql::list_schemas, db::ob_oracle::list_schemas),
    // ...
}

```

## Session Configuration and Usage Examples

DBX provides specific session setup for OceanBase connections, including timeout configuration and driver profile selection.

### Creating Connections in Different Modes

To create a standard MySQL connection in **Normal mode**, omit the driver profile or leave it empty:

```rust
use dbx_core::models::connection::{ConnectionConfig, DatabaseType};

let config = ConnectionConfig {
    id: "conn1".into(),
    name: "MySQL".into(),
    db_type: DatabaseType::Mysql,
    driver_profile: None,               // Normal mode
    host: "127.0.0.1".into(),
    port: 3306,
    username: "root".into(),
    password: "secret".into(),
    database: Some("mydb".into()),
    ..Default::default()
};

```

For **Bare mode** with Doris or StarRocks, set the driver profile to trigger the bare pool flag:

```rust
let mut cfg = config.clone();
cfg.driver_profile = Some("doris".into());   // triggers uses_bare_mysql_pool

```

For **OceanBase** with automatic Oracle detection, use the oceanbase profile:

```rust
let mut cfg = config.clone();
cfg.driver_profile = Some("oceanbase".into());
// DBX will run SHOW VARIABLES LIKE 'ob_compatibility_mode'
// – if the result is "oracle" → MysqlMode::OceanBaseOracle

```

### OceanBase-Specific Session Setup

When configured with a query timeout, DBX automatically sends `SET ob_query_timeout` for OceanBase connections. The `oceanbase_mysql_setup_queries` function in [`crates/dbx-core/src/connection.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/connection.rs) generates these session statements:

```rust
// crates/dbx-core/src/connection.rs
fn oceanbase_mysql_setup_queries(config: &ConnectionConfig) -> Vec<String> {
    if !is_oceanbase_mysql_config(config) || config.query_timeout_secs == 0 {
        return Vec::new();
    }
    let timeout_us = config.query_timeout_secs.saturating_mul(1_000_000);
    vec![format!("SET ob_query_timeout = {timeout_us}")]
}

```

This ensures Oracle-compatible OceanBase connections respect the configured timeout without manual intervention.

### Desktop Client Configuration

In the DBX desktop application, users can select the connection mode explicitly via the connection dialog. The Vue component in [`apps/desktop/src/components/connection/ConnectionDialog.vue`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/connection/ConnectionDialog.vue) exposes both OceanBase variants:

```vue
<option :value="'oceanbase'">OceanBase</option>
<option :value="'oceanbase-oracle'">OceanBase Oracle Mode</option>

```

Selecting "OceanBase Oracle Mode" bypasses auto-detection and forces the Oracle-compatible driver immediately.

## Summary

- **Normal mode** provides standard MySQL protocol support for vanilla MySQL servers.
- **Bare mode** strips MySQL-specific behaviors for compatibility with Doris, StarRocks, and similar engines.
- **OceanBase Oracle mode** switches to Oracle-style metadata queries when connecting to OceanBase servers running in Oracle compatibility mode.
- The `dispatch_mysql!` macro in [`crates/dbx-core/src/schema.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/schema.rs) routes metadata calls to the correct driver implementation based on the active `MysqlMode`.
- Automatic detection occurs via `SHOW VARIABLES LIKE 'ob_compatibility_mode'` in [`crates/dbx-core/src/connection.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/connection.rs), with manual override available in the desktop UI.

## Frequently Asked Questions

### What is the difference between Bare mode and Normal mode in DBX?

**Bare mode** disables MySQL-specific protocol behaviors such as display-width handling, making it suitable for MySQL-compatible engines like Doris and StarRocks that speak the wire protocol but lack full MySQL metadata conventions. **Normal mode** uses the standard MySQL driver with complete protocol support for vanilla MySQL servers.

### How does DBX automatically detect OceanBase Oracle compatibility?

DBX runs `SHOW VARIABLES LIKE 'ob_compatibility_mode'` immediately after establishing the connection. If the server returns `"oracle"`, the `detect_ob_oracle_mode` function in [`crates/dbx-core/src/connection.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/connection.rs) switches the session to `MysqlMode::OceanBaseOracle`, ensuring subsequent metadata queries use Oracle-style SQL syntax.

### Can I force OceanBase Oracle mode without relying on auto-detection?

Yes. In the DBX desktop client, select **"OceanBase Oracle Mode"** from the connection dialog dropdown instead of the standard "OceanBase" option. This sets the driver profile to `oceanbase-oracle`, which bypasses the automatic detection logic and immediately uses the Oracle-compatible driver.

### Which MySQL-compatible databases should use Bare mode?

Use **Bare mode** when connecting to **Doris**, **StarRocks**, **Manticore Search**, or any other engine that implements the MySQL wire protocol but does not fully support MySQL's information schema or display-width attributes. Set the driver profile to the specific engine name (e.g., `"doris"`) to trigger this mode automatically.