oceanbase 0.0.1

package/License

@@ -0,0 +1,19 @@
+Copyright (c) 2016 Andrey Sidorov (sidorares@yandex.ru) and contributors
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in
+ all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ THE SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+[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](#about-this-driver)
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [Acknowledgements](#acknowledgements)
+- [Contributing](#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
+
+### 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][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
+
+### Connecting to OceanBase MySQL Tenant
+
+```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);
+});
+```
+
+### Connecting to OceanBase Oracle Tenant
+
+```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);
+});
+```
+
+### 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`:
+
+```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
+});
+```
+
+### Using Connection Pool (Oracle Mode)
+
+```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);
+});
+```
+
+### Using Promise API
+
+```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]
+
+### Oracle Mode Notes
+
+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).
+
+### 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.
+
+

package/index.d.ts

@@ -0,0 +1 @@
+export * from './typings/mysql/index.js';

package/index.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const SqlString = require('sqlstring');
+
+const ConnectionConfig = require('./lib/connection_config.js');
+const parserCache = require('./lib/parsers/parser_cache.js');
+
+const Connection = require('./lib/connection.js');
+
+exports.createConnection = require('./lib/create_connection.js');
+exports.connect = exports.createConnection;
+exports.Connection = Connection;
+exports.ConnectionConfig = ConnectionConfig;
+
+const Pool = require('./lib/pool.js');
+const PoolCluster = require('./lib/pool_cluster.js');
+const createPool = require('./lib/create_pool.js');
+const createPoolCluster = require('./lib/create_pool_cluster.js');
+
+exports.createPool = createPool;
+
+exports.createPoolCluster = createPoolCluster;
+
+exports.createQuery = Connection.createQuery;
+
+exports.Pool = Pool;
+
+exports.PoolCluster = PoolCluster;
+
+exports.createServer = function (handler) {
+  const Server = require('./lib/server.js');
+  const s = new Server();
+  if (handler) {
+    s.on('connection', handler);
+  }
+  return s;
+};
+
+exports.PoolConnection = require('./lib/pool_connection.js');
+exports.authPlugins = require('./lib/auth_plugins');
+exports.escape = SqlString.escape;
+exports.escapeId = SqlString.escapeId;
+exports.format = SqlString.format;
+exports.raw = SqlString.raw;
+
+exports.__defineGetter__(
+  'createConnectionPromise',
+  () => require('./promise.js').createConnection
+);
+
+exports.__defineGetter__(
+  'createPoolPromise',
+  () => require('./promise.js').createPool
+);
+
+exports.__defineGetter__(
+  'createPoolClusterPromise',
+  () => require('./promise.js').createPoolCluster
+);
+
+exports.__defineGetter__('Types', () => require('./lib/constants/types.js'));
+
+exports.__defineGetter__('Charsets', () =>
+  require('./lib/constants/charsets.js')
+);
+
+exports.__defineGetter__('CharsetToEncoding', () =>
+  require('./lib/constants/charset_encodings.js')
+);
+
+exports.setMaxParserCache = function (max) {
+  parserCache.setMaxCache(max);
+};
+
+exports.clearParserCache = function () {
+  parserCache.clearCache();
+};

package/lib/auth_41.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/*
+4.1 authentication: (http://bazaar.launchpad.net/~mysql/mysql-server/5.5/view/head:/sql/password.c)
+
+  SERVER:  public_seed=create_random_string()
+           send(public_seed)
+
+  CLIENT:  recv(public_seed)
+           hash_stage1=sha1("password")
+           hash_stage2=sha1(hash_stage1)
+           reply=xor(hash_stage1, sha1(public_seed,hash_stage2)
+
+           // this three steps are done in scramble()
+
+           send(reply)
+
+
+  SERVER:  recv(reply)
+           hash_stage1=xor(reply, sha1(public_seed,hash_stage2))
+           candidate_hash2=sha1(hash_stage1)
+           check(candidate_hash2==hash_stage2)
+
+server stores sha1(sha1(password)) ( hash_stag2)
+*/
+
+const crypto = require('crypto');
+
+function sha1(msg, msg1, msg2) {
+  const hash = crypto.createHash('sha1');
+  hash.update(msg);
+  if (msg1) {
+    hash.update(msg1);
+  }
+
+  if (msg2) {
+    hash.update(msg2);
+  }
+
+  return hash.digest();
+}
+
+function xor(a, b) {
+  const result = Buffer.allocUnsafe(a.length);
+  for (let i = 0; i < a.length; i++) {
+    result[i] = a[i] ^ b[i];
+  }
+  return result;
+}
+
+exports.xor = xor;
+
+function token(password, scramble1, scramble2) {
+  if (!password) {
+    return Buffer.alloc(0);
+  }
+  const stage1 = sha1(password);
+  return exports.calculateTokenFromPasswordSha(stage1, scramble1, scramble2);
+}
+
+exports.calculateTokenFromPasswordSha = function (
+  passwordSha,
+  scramble1,
+  scramble2
+) {
+  // we use AUTH 41 here, and we need only the bytes we just need.
+  const authPluginData1 = scramble1.slice(0, 8);
+  const authPluginData2 = scramble2.slice(0, 12);
+  const stage2 = sha1(passwordSha);
+  const stage3 = sha1(authPluginData1, authPluginData2, stage2);
+  return xor(stage3, passwordSha);
+};
+
+exports.calculateToken = token;
+
+exports.verifyToken = function (publicSeed1, publicSeed2, token, doubleSha) {
+  const hashStage1 = xor(token, sha1(publicSeed1, publicSeed2, doubleSha));
+  const candidateHash2 = sha1(hashStage1);
+  return candidateHash2.compare(doubleSha) === 0;
+};
+
+exports.doubleSha1 = function (password) {
+  return sha1(sha1(password));
+};
+
+function xorRotating(a, seed) {
+  const result = Buffer.allocUnsafe(a.length);
+  const seedLen = seed.length;
+
+  for (let i = 0; i < a.length; i++) {
+    result[i] = a[i] ^ seed[i % seedLen];
+  }
+  return result;
+}
+exports.xorRotating = xorRotating;

package/lib/auth_plugins/caching_sha2_password.js

@@ -0,0 +1,108 @@
+'use strict';
+
+// https://mysqlserverteam.com/mysql-8-0-4-new-default-authentication-plugin-caching_sha2_password/
+
+const PLUGIN_NAME = 'caching_sha2_password';
+const crypto = require('crypto');
+const { xor, xorRotating } = require('../auth_41');
+
+const REQUEST_SERVER_KEY_PACKET = Buffer.from([2]);
+const FAST_AUTH_SUCCESS_PACKET = Buffer.from([3]);
+const PERFORM_FULL_AUTHENTICATION_PACKET = Buffer.from([4]);
+
+const STATE_INITIAL = 0;
+const STATE_TOKEN_SENT = 1;
+const STATE_WAIT_SERVER_KEY = 2;
+const STATE_FINAL = -1;
+
+function sha256(msg) {
+  const hash = crypto.createHash('sha256');
+  hash.update(msg);
+  return hash.digest();
+}
+
+function calculateToken(password, scramble) {
+  if (!password) {
+    return Buffer.alloc(0);
+  }
+  const stage1 = sha256(Buffer.from(password));
+  const stage2 = sha256(stage1);
+  const stage3 = sha256(Buffer.concat([stage2, scramble]));
+  return xor(stage1, stage3);
+}
+
+function encrypt(password, scramble, key) {
+  const stage1 = xorRotating(Buffer.from(`${password}\0`, 'utf8'), scramble);
+  return crypto.publicEncrypt(
+    {
+      key,
+      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
+    },
+    stage1
+  );
+}
+
+module.exports =
+  (pluginOptions = {}) =>
+  ({ connection }) => {
+    let state = 0;
+    let scramble = null;
+
+    const password = connection.config.password;
+
+    const authWithKey = (serverKey) => {
+      const _password = encrypt(password, scramble, serverKey);
+      state = STATE_FINAL;
+      return _password;
+    };
+
+    return (data) => {
+      switch (state) {
+        case STATE_INITIAL:
+          scramble = data.slice(0, 20);
+          state = STATE_TOKEN_SENT;
+          return calculateToken(password, scramble);
+
+        case STATE_TOKEN_SENT:
+          if (FAST_AUTH_SUCCESS_PACKET.equals(data)) {
+            state = STATE_FINAL;
+            return null;
+          }
+
+          if (PERFORM_FULL_AUTHENTICATION_PACKET.equals(data)) {
+            const isSecureConnection =
+              typeof pluginOptions.overrideIsSecure === 'undefined'
+                ? connection.config.ssl || connection.config.socketPath
+                : pluginOptions.overrideIsSecure;
+            if (isSecureConnection) {
+              state = STATE_FINAL;
+              return Buffer.from(`${password}\0`, 'utf8');
+            }
+
+            // if client provides key we can save one extra roundrip on first connection
+            if (pluginOptions.serverPublicKey) {
+              return authWithKey(pluginOptions.serverPublicKey);
+            }
+
+            state = STATE_WAIT_SERVER_KEY;
+            return REQUEST_SERVER_KEY_PACKET;
+          }
+          throw new Error(
+            `Invalid AuthMoreData packet received by ${PLUGIN_NAME} plugin in STATE_TOKEN_SENT state.`
+          );
+        case STATE_WAIT_SERVER_KEY:
+          if (pluginOptions.onServerPublicKey) {
+            pluginOptions.onServerPublicKey(data);
+          }
+          return authWithKey(data);
+        case STATE_FINAL:
+          throw new Error(
+            `Unexpected data in AuthMoreData packet received by ${PLUGIN_NAME} plugin in STATE_FINAL state.`
+          );
+      }
+
+      throw new Error(
+        `Unexpected data in AuthMoreData packet received by ${PLUGIN_NAME} plugin in state ${state}`
+      );
+    };
+  };

package/lib/auth_plugins/caching_sha2_password.md

@@ -0,0 +1,18 @@
+##
+
+https://dev.mysql.com/doc/refman/8.0/en/caching-sha2-pluggable-authentication.html
+
+```js
+const mysql = require('mysql');
+mysql.createConnection({
+  authPlugins: {
+    caching_sha2_password: mysql.authPlugins.caching_sha2_password({
+      onServerPublikKey: function (key) {
+        console.log(key);
+      },
+      serverPublicKey: 'xxxyyy',
+      overrideIsSecure: true, //
+    }),
+  },
+});
+```

package/lib/auth_plugins/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+module.exports = {
+  caching_sha2_password: require('./caching_sha2_password'),
+  mysql_clear_password: require('./mysql_clear_password'),
+  mysql_native_password: require('./mysql_native_password'),
+  sha256_password: require('./sha256_password'),
+};

package/lib/auth_plugins/mysql_clear_password.js

@@ -0,0 +1,17 @@
+'use strict';
+
+function bufferFromStr(str) {
+  return Buffer.from(`${str}\0`);
+}
+
+const create_mysql_clear_password_plugin = (pluginOptions) =>
+  function mysql_clear_password_plugin({ connection, command }) {
+    const password =
+      command.password || pluginOptions.password || connection.config.password;
+
+    return function (/* pluginData */) {
+      return bufferFromStr(password);
+    };
+  };
+
+module.exports = create_mysql_clear_password_plugin;

package/lib/auth_plugins/mysql_native_password.js

@@ -0,0 +1,34 @@
+'use strict';
+
+//const PLUGIN_NAME = 'mysql_native_password';
+const auth41 = require('../auth_41.js');
+
+module.exports =
+  (pluginOptions) =>
+  ({ connection, command }) => {
+    const password =
+      command.password || pluginOptions.password || connection.config.password;
+    const passwordSha1 =
+      command.passwordSha1 ||
+      pluginOptions.passwordSha1 ||
+      connection.config.passwordSha1;
+    return (data) => {
+      const authPluginData1 = data.slice(0, 8);
+      const authPluginData2 = data.slice(8, 20);
+      let authToken;
+      if (passwordSha1) {
+        authToken = auth41.calculateTokenFromPasswordSha(
+          passwordSha1,
+          authPluginData1,
+          authPluginData2
+        );
+      } else {
+        authToken = auth41.calculateToken(
+          password,
+          authPluginData1,
+          authPluginData2
+        );
+      }
+      return authToken;
+    };
+  };