OceanBase Driver for Node.js

High-performance OceanBase database client driver built on top of MySQL2. Fully compatible with MySQL protocol, with additional support for OceanBase Oracle tenant protocol. Supports prepared statements, non-utf8 encodings, binary log protocol, compression, SSL and much more.

Table of Contents

• About This Driver
• Key Features
• Installation
• Quick Start
• Documentation
• Acknowledgements
• Contributing

About This Driver

This driver is built on top of the MySQL2 project, extending support for OceanBase database while maintaining all MySQL2 functionality.

OceanBase is a distributed relational database that is fully compatible with MySQL protocol. This driver extends the MySQL protocol with additional support for OceanBase Oracle tenant protocol, enabling you to:

• Connect to OceanBase MySQL tenants using MySQL mode
• Connect to OceanBase Oracle tenants using Oracle mode
• Seamlessly migrate existing MySQL2 code without API changes

This driver is fully API compatible with MySQL2, and you can directly refer to the MySQL2 official documentation for usage.

Key Features

OceanBase-Specific Features

• ✅ OceanBase MySQL Tenant Support - Fully compatible with MySQL protocol
• ✅ OceanBase Oracle Tenant Support - Enable Oracle compatibility mode via mode: 'oracle' option
• ✅ Dual Mode Support - Single driver supports both MySQL and Oracle modes

MySQL2 Original Features

• ⚡ Faster / Better Performance - Optimized performance
• 📝 Prepared Statements - Support for prepared statements, improving performance and security
• 📊 MySQL Binary Log Protocol - Support for binary log parsing
• 🖥️ MySQL Server - Can create MySQL-compatible servers
• 🌐 Extended support for Encoding and Collation - Support for multiple character sets and collations
• 🔄 Promise Wrapper - Native Promise support
• 🗜️ Compression - Support for connection compression
• 🔒 SSL and Authentication Switch - Support for SSL connections and multiple authentication methods
• 🌊 Custom Streams - Support for custom data streams
• 💧 Connection Pooling - Built-in connection pool management

Installation

This driver is free from native bindings and can be installed on Linux, Mac OS or Windows without any issues.

npm install --save oceanbase

Quick Start

Connecting to OceanBase MySQL Tenant

const oceanbase = require('oceanbase');

const connection = oceanbase.createConnection({
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'test'
});

connection.query('SELECT * FROM users', (err, results) => {
  if (err) throw err;
  console.log(results);
});

Connecting to OceanBase Oracle Tenant

const oceanbase = require('oceanbase');

// Use mode: 'oracle' option to enable Oracle mode
const connection = oceanbase.createConnection({
  host: 'localhost',
  user: 'oracle_user',
  password: 'password',
  database: 'oracle_db',
  mode: 'oracle'  // Key: Enable Oracle tenant mode
});

connection.query('SELECT * FROM users', (err, results) => {
  if (err) throw err;
  console.log(results);
});

Connecting with Tenant and Cluster

OceanBase supports cluster and tenant fields. When connecting, you can specify tenant and cluster options, and the driver will automatically format the username as username@tenant#cluster:

const oceanbase = require('oceanbase');

// Using tenant and cluster options
const connection = oceanbase.createConnection({
  host: 'localhost',
  user: 'myuser',
  password: 'password',
  database: 'mydb',
  tenant: 'mytenant',    // Tenant name
  cluster: 'mycluster'   // Cluster name
  // Username will be automatically formatted as: myuser@mytenant#mycluster
});

// You can also use URL query parameters
const connection2 = oceanbase.createConnection({
  uri: 'mysql://myuser:password@localhost:3306/mydb?tenant=mytenant&cluster=mycluster'
});

// If username already contains @ or #, it will be used as-is
const connection3 = oceanbase.createConnection({
  host: 'localhost',
  user: 'myuser@mytenant#mycluster',  // Already formatted
  password: 'password',
  database: 'mydb'
  // tenant and cluster options will be ignored if username is already formatted
});

Using Connection Pool (Oracle Mode)

const oceanbase = require('oceanbase');

const pool = oceanbase.createPool({
  host: 'localhost',
  user: 'oracle_user',
  password: 'password',
  database: 'oracle_db',
  mode: 'oracle'  // Oracle tenant mode
});

pool.query('SELECT * FROM users', (err, results) => {
  if (err) throw err;
  console.log(results);
});

Using Promise API

const oceanbase = require('oceanbase/promise');

async function queryData() {
  const connection = await oceanbase.createConnection({
    host: 'localhost',
    user: 'root',
    password: 'password',
    database: 'test',
    mode: 'oracle'  // Optional: Oracle mode
  });

  const [rows] = await connection.execute('SELECT * FROM users WHERE id = ?', [1]);
  console.log(rows);
  
  await connection.end();
}

Documentation

This driver's usage documentation is fully compatible with MySQL2. You can refer to the following MySQL2 official documentation:

• Quickstart
  • First Query, Using Prepared Statements, Using Connection Pools and more.
• Documentation
• Examples
• FAQ

Oracle Mode Notes

When connecting to OceanBase Oracle tenants, you need to add the mode: 'oracle' option to your connection configuration:

{
  host: 'your-host',
  user: 'your-user',
  password: 'your-password',
  database: 'your-database',
  mode: 'oracle'  // Enable Oracle tenant mode
}

When mode is not specified or set to mode: 'mysql', the standard MySQL protocol will be used (suitable for MySQL tenants).

Tenant and Cluster Configuration

OceanBase supports multi-tenant architecture with cluster and tenant concepts. The driver automatically formats usernames when tenant and/or cluster options are provided:

• tenant (optional): The tenant name. When provided, username will be formatted as username@tenant
• cluster (optional): The cluster name. When provided, username will be formatted as username@tenant#cluster (if tenant is also provided) or username#cluster (if only cluster is provided)

Note: If the username already contains @ or # characters, the driver will use it as-is and ignore the tenant and cluster options to avoid duplicate formatting.