[npm-image]: https://img.shields.io/npm/v/oceanbase.svg
[npm-url]: https://npmjs.com/package/oceanbase
[node-version-image]: https://img.shields.io/node/v/oceanbase.svg
[node-version-url]: https://nodejs.org/en/download
[downloads-image]: https://img.shields.io/npm/dm/oceanbase.svg
[downloads-url]: https://npmjs.com/package/oceanbase
[license-url]: https://github.com/sidorares/node-mysql2/blob/master/License
[license-image]: https://img.shields.io/npm/l/oceanbase.svg?maxAge=2592000
[node-mysql]: https://github.com/mysqljs/mysql
[mysqljs]: https://github.com/mysqljs
[mysql-native]: https://github.com/sidorares/nodejs-mysql-native
[sidorares]: https://github.com/sidorares
[TooTallNate]: https://gist.github.com/TooTallNate
[starttls.js]: https://gist.github.com/TooTallNate/848444
[node-mariasql]: https://github.com/mscdex/node-mariasql
[contributors]: https://github.com/sidorares/node-mysql2/graphs/contributors
[contributing]: https://github.com/sidorares/node-mysql2/blob/master/Contributing.md
[docs-base]: https://sidorares.github.io/node-mysql2/docs
[docs-base-zh-CN]: https://sidorares.github.io/node-mysql2/zh-CN/docs
[docs-base-pt-BR]: https://sidorares.github.io/node-mysql2/pt-BR/docs
[docs-prepared-statements]: https://sidorares.github.io/node-mysql2/docs/documentation/prepared-statements
[docs-mysql-server]: https://sidorares.github.io/node-mysql2/docs/documentation/mysql-server
[docs-promise-wrapper]: https://sidorares.github.io/node-mysql2/docs/documentation/promise-wrapper
[docs-authentication-switch]: https://sidorares.github.io/node-mysql2/docs/documentation/authentication-switch
[docs-streams]: https://sidorares.github.io/node-mysql2/docs/documentation/extras
[docs-typescript-docs]: https://sidorares.github.io/node-mysql2/docs/documentation/typescript-examples
[docs-qs-pooling]: https://sidorares.github.io/node-mysql2/docs#using-connection-pools
[docs-qs-first-query]: https://sidorares.github.io/node-mysql2/docs#first-query
[docs-qs-using-prepared-statements]: https://sidorares.github.io/node-mysql2/docs#using-prepared-statements
[docs-examples]: https://sidorares.github.io/node-mysql2/docs/examples
[docs-faq]: https://sidorares.github.io/node-mysql2/docs/faq
[docs-documentation]: https://sidorares.github.io/node-mysql2/docs/documentation
[docs-contributing]: https://sidorares.github.io/node-mysql2/docs/contributing/website
[coverage]: https://img.shields.io/codecov/c/github/sidorares/node-mysql2
[coverage-url]: https://app.codecov.io/github/sidorares/node-mysql2
[ci-url]: https://github.com/sidorares/node-mysql2/actions/workflows/ci-coverage.yml?query=branch%3Amaster
[ci-image]: https://img.shields.io/github/actions/workflow/status/sidorares/node-mysql2/ci-coverage.yml?event=push&style=flat&label=CI&branch=master

OceanBase Driver for Node.js

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![GitHub Workflow Status (with event)][ci-image]][ci-url]
[![Codecov][coverage]][coverage-url]
[![License][license-image]][license-url]

> High-performance OceanBase database client driver built on top of [MySQL2][node-mysql]. 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][docs-documentation].

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][node-mysql] 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][node-mysql], and you can directly refer to the [MySQL2 official documentation][docs-documentation] for usage.

Key Features

$3

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

$3

- ⚡ Faster / Better Performance - Optimized performance
- 📝 [Prepared Statements][docs-prepared-statements] - Support for prepared statements, improving performance and security
- 📊 MySQL Binary Log Protocol - Support for binary log parsing
- 🖥️ [MySQL Server][docs-mysql-server] - Can create MySQL-compatible servers
- 🌐 Extended support for Encoding and Collation - Support for multiple character sets and collations
- 🔄 [Promise Wrapper][docs-promise-wrapper] - Native Promise support
- 🗜️ Compression - Support for connection compression
- 🔒 SSL and [Authentication Switch][docs-authentication-switch] - Support for SSL connections and multiple authentication methods
- 🌊 [Custom Streams][docs-streams] - Support for custom data streams
- 💧 [Connection Pooling][docs-qs-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.

``bash npm install --save oceanbase`

`Quick Start`

`$3`

`javascript 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); });`

`$3`

`javascript 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); });`

`$3`

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:

`javascript 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 });`

`$3`

`javascript 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); });`

`$3`

`javascript 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][node-mysql]. You can refer to the following MySQL2 official documentation:

- [Quickstart][docs-base] - [First Query][docs-qs-first-query], [Using Prepared Statements][docs-qs-using-prepared-statements], [Using Connection Pools][docs-qs-pooling] and more. - [Documentation][docs-documentation] - [Examples][docs-examples] - [FAQ][docs-faq]

`$3`

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

`javascript { 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).

`$3`

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.

OceanBase Driver for Node.js

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][node-mysql] project, extending support for OceanBase database while maintaining all MySQL2 functionality.

- 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][node-mysql], and you can directly refer to the [MySQL2 official documentation][docs-documentation] for usage.

Key Features

$3

Installation

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

``bash npm install --save oceanbase`

`Quick Start`

`$3`

`javascript 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); });`

`$3`

`javascript const oceanbase = require('oceanbase');

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

`$3`

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:

`javascript const oceanbase = require('oceanbase');

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

`$3`

`javascript 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); });`

`$3`

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

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][node-mysql]. You can refer to the following MySQL2 official documentation:

`$3`

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

`javascript { 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).

`$3`

OceanBase supports multi-tenant architecture with cluster and tenant concepts. The driver automatically formats usernames when tenant and/or cluster options are 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.