MySQL外部テーブルプラグイン

本記事では、OceanBaseデータベースに外部テーブルJDBCプラグインをインストールし、使用する方法について説明します。外部テーブルJDBCプラグインを使用することで、JDBCがサポートするデータソース（現在はMySQLデータベースのデータソースへのアクセスのみをサポートしています）にアクセスできます。

機能の制限

• OceanBaseデータベースのOracleモード：現在、この機能はOracleモードをサポートしていません。

• データ型：Array 型は現在サポートされていません。

• クエリの制限：

  • 並列クエリはサポートされていません。
  • 同一データソースの複数テーブルに対する JOIN は、1つのSQLとしてデータソースにプッシュダウンされません。
  • 集計関数や LIMIT などはプッシュダウンされません。

• 依存関係の管理：JARパッケージは動的ロードをサポートしていないため、プロセス起動前に指定されたディレクトリにJARパッケージを配置する必要があります。

• タイムアウト設定：プラグインを通じてクエリのタイムアウト時間を設定することはできません。

• パラメータの変更：テーブルの PARAMETERS プロパティは変更できません。テーブルを再作成する必要があります。

前提条件

• OceanBaseデータベースのデプロイが完了し、MySQLモードのユーザーテナントが作成されていること。
• JDK（バージョン ≥ 11）がインストール済みであり、JAVA_HOME 環境変数が設定されていること。

MySQL外部テーブルプラグインのJARパッケージパスの設定

MySQL外部テーブルプラグインのダウンロードURLからMySQL外部テーブルプラグインのJARパッケージをダウンロードし、指定ディレクトリ（パラメータob_java_connector_pathディレクトリ内）に配置します。

例：

1. JARパッケージを配置するためのディレクトリを作成します。

   mkdir -p /jdbc/plugin/jar/package/directory
   

2. ディレクトリに移動します。

   cd /jdbc/plugin/jar/package/directory
   

3. MySQL外部テーブルプラグインのJARパッケージをダウンロードします。

   wget https://github.com/oceanbase/oceanbase-plugins/releases/download/external-v1.0.0/oceanbase-external-plugin-1.0.0-jar-with-dependencies.jar
   

OceanBaseデータベースパラメータの設定（再起動後に反映）

1. Javaを有効化します。

   例：

   ALTER SYSTEM SET ob_enable_java_env = true;
   

   詳細については、ob_enable_java_envを参照してください。

2. 現在のOBServerノード上のJavaホームディレクトリを設定します。

   説明

   このパスはJDKのHOMEディレクトリから取得されます。$JAVA_HOME環境変数に設定するだけで済みます。

   例：

   ALTER SYSTEM SET ob_java_home = "/java/home/path";
   

   詳細については、ob_java_homeを参照してください。

3. JDBCプラグインのJARファイルディレクトリを設定します。

   説明

   MySQL外部テーブルプラグインのJARファイルディレクトリのみを設定する必要があります。JARファイル名は不要です。ディレクトリ内のJARファイルは自動的に展開されます。

   例：

   ALTER SYSTEM SET ob_java_connector_path = "/jdbc/plugin/jar/package/directory";
   

   詳細については、ob_java_connector_pathを参照してください。

4. Java環境起動に関するパラメータを設定します。

   1. 対応するログフォルダのパスを作成します。

      mkdir -p /home/user/jvmlogs
      mkdir -p /home/user/jvmlogs/heapdumps
      

   2. Java実行時のJVM起動パラメータを設定します。

      例：

      ALTER SYSTEM SET ob_java_opts = "-Djdk.lang.processReaperUseDefaultStackSize=true -XX:+HeapDumpOnOutOfMemoryError -Xrs -Xmx2048m -Xms2048m -Xloggc:/home/user/jvmlogs/gc.log -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/home/user/jvmlogs/heapdumps/ -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=10 -XX:GCLogFileSize=100M -XX:+UseG1GC  -XX:-CriticalJNINatives --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED -Darrow.allocation.manager.type=Netty";
      

      詳細については、ob_java_optsを参照してください。

      注意

      • この構成パラメータを変更するには、observerプロセスを再起動する必要があります。現在使用されているメモリコピーアウトは、データストリームからC++メモリヒープへの直接コピーであるため、-Xmx2048m -Xms2048mの設定を適宜削減できます。
      • 関連するGCログファイルについては、対応する設定フォルダのパスが存在していればよいです。対応するパスが存在しない場合、関連するログファイルも存在しません。

5. OceanBaseデータベースを再起動し、プラグインが正常にインストールされたか確認します。

   例：

   SELECT *
   FROM oceanbase.GV$OB_PLUGINS
   WHERE TYPE = 'EXTERNAL TABLE'
   AND STATUS = 'READY';
   

   実行結果は次のとおりです：

   +--------------+----------+-------+--------+----------------+---------+-----------------+------------------+-------------------+-----------------------+---------------+-----------------------------------------------------+
   | SVR_IP       | SVR_PORT | NAME  | STATUS | TYPE           | LIBRARY | LIBRARY_VERSION | LIBRARY_REVISION | INTERFACE_VERSION | AUTHOR                | LICENSE       | DESCRIPTION                                         |
   +--------------+----------+-------+--------+----------------+---------+-----------------+------------------+-------------------+-----------------------+---------------+-----------------------------------------------------+
   | 127.0.0.1    |    55803 | java  | READY  | EXTERNAL TABLE | NULL    | 0.1.0           | NULL             | 0.2.0             | OceanBase Corporation | Mulan PubL v2 | This is the java external table data source plugin. |
   | 127.0.0.1    |    55803 | jdbc  | READY  | EXTERNAL TABLE | NULL    | 0.1.0           | NULL             | 0.2.0             | OceanBase Corporation | Mulan PubL v2 | This is a java external data source                 |
   | 127.0.0.1    |    55803 | mysql | READY  | EXTERNAL TABLE | NULL    | 0.1.0           | NULL             | 0.2.0             | OceanBase Corporation | Mulan PubL v2 | This is a java external data source                 |
   +--------------+----------+-------+--------+----------------+---------+-----------------+------------------+-------------------+-----------------------+---------------+-----------------------------------------------------+
   

   ここで、javaはJava外部テーブルプラグインの汎用実装、jdbcはJava JDBCデータソースであり、javaプラグインに基づいて実装されています。MySQLはMySQL JDBCデータソースであり、jdbcプラグインに基づいて実装されています。

使用例

ステップ１：環境の準備

以下のデータベース環境を仮定します：

ステップ2：テストテーブルを作成する

1. MySQLデータベースにテーブルを作成します。

   例：

   CREATE TABLE `lineitem` (
       `l_orderkey`      bigint(20) NOT NULL,
       `l_partkey`       bigint(20) NOT NULL,
       `l_suppkey`       bigint(20) NOT NULL,
       `l_linenumber`    bigint(20) NOT NULL,
       `l_quantity`      bigint(20) NOT NULL,
       `l_extendedprice` decimal(10,2) NOT NULL,
       `l_discount`      decimal(10,2) NOT NULL,
       `l_tax`           decimal(10,2) NOT NULL,
       `l_returnflag`    char(1) DEFAULT NULL,
       `l_linestatus`    char(1) DEFAULT NULL,
       `l_shipdate`      date DEFAULT NULL,
       `l_commitdate`    date DEFAULT NULL,
       `l_receiptdate`   date DEFAULT NULL,
       `l_shipinstruct`  char(25) DEFAULT NULL,
       `l_shipmode`      char(10) DEFAULT NULL,
       `l_comment`       varchar(44) DEFAULT NULL,
       PRIMARY KEY (`l_orderkey`,`l_linenumber`)
       )
       ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
   

2. OceanBaseデータベースに外部テーブルを作成します。

   例：

   CREATE EXTERNAL TABLE lineitem (
       l_orderkey           bigint,
       l_partkey            bigint,
       l_suppkey            bigint,
       l_linenumber         bigint,
       l_quantity           bigint,
       l_extendedprice      decimal(10,2),
       l_discount           decimal(10,2),
       l_tax                decimal(10,2),
       l_returnflag         char(1) ,
       l_linestatus         char(1) ,
       l_shipdate           date ,
       l_commitdate         date ,
       l_receiptdate        date ,
       l_shipinstruct       char(25) ,
       l_shipmode           char(10) ,
       l_comment            varchar(44)
       )
       PROPERTIES (
           TYPE='plugin',
           NAME='mysql',
           PARAMETERS='{"user":"root","password":"","table":"lineitem","jdbc_url":"jdbc:mysql://xxx.xxx.xxx.1:3306/test?useSSL=false"}'
       );
   

   注意

   JDBC接続文字列に useSSL=falseパラメータを追加しました。MySQL JDBCプラグインはバージョン8.0.3を使用しているため、MySQLバージョン5.7と接続する際にこのオプションが必要です。

3. MySQLデータベースのテーブルにテストデータを挿入します。

   例：

   INSERT INTO `lineitem` (`l_orderkey`, `l_partkey`, `l_suppkey`, `l_linenumber`, `l_quantity`, `l_extendedprice`, `l_discount`, `l_tax`, `l_returnflag`, `l_linestatus`, `l_shipdate`, `l_commitdate`, `l_receiptdate`, `l_shipinstruct`, `l_shipmode`, `l_comment`) VALUES
       (1, 155190, 7706, 1, 17, 21168.23, 0.04, 0.02, 'N', 'O', '1996-03-13', '1996-02-12', '1996-03-22', 'DELIVER IN PERSON', 'TRUCK', 'egular courts above the'),
       (1, 67310, 7311, 2, 36, 45983.16, 0.09, 0.06, 'N', 'O', '1996-04-12', '1996-02-28', '1996-04-20', 'TAKE BACK RETURN', 'MAIL', 'ly final dependencies: slyly bold '),
       (1, 63700, 3701, 3, 8, 13309.60, 0.10, 0.02, 'N', 'O', '1996-01-29', '1996-03-05', '1996-01-31', 'TAKE BACK RETURN', 'REG AIR', 'riously. regular, express dep'),
       (1, 2132, 4633, 4, 28, 28955.64, 0.09, 0.06, 'N', 'O', '1996-04-21', '1996-03-30', '1996-05-16', 'NONE', 'AIR', 'lites. fluffily even de'),
       (1, 24027, 1534, 5, 24, 22824.48, 0.10, 0.04, 'N', 'O', '1996-03-30', '1996-03-14', '1996-04-01', 'NONE', 'FOB', ' pending foxes. slyly re'),
       (1, 15635, 638, 6, 32, 49620.16, 0.07, 0.02, 'N', 'O', '1996-01-30', '1996-02-07', '1996-02-03', 'DELIVER IN PERSON', 'MAIL', 'arefully slyly ex'),
       (2, 106170, 1191, 1, 38, 44694.46, 0.00, 0.05, 'N', 'O', '1997-01-28', '1997-01-14', '1997-02-02', 'TAKE BACK RETURN', 'RAIL', 'ven requests. deposits breach a'),
       (3, 4297, 1798, 1, 45, 54058.05, 0.06, 0.00, 'R', 'F', '1994-02-02', '1994-01-04', '1994-02-23', 'NONE', 'AIR', 'ongside of the furiously brave acco'),
       (3, 19036, 6540, 2, 49, 46796.47, 0.10, 0.00, 'R', 'F', '1993-11-09', '1993-12-20', '1993-11-24', 'TAKE BACK RETURN', 'RAIL', ' unusual accounts. eve'),
       (3, 128449, 3474, 3, 27, 39890.88, 0.06, 0.07, 'A', 'F', '1994-01-16', '1993-11-22', '1994-01-23', 'DELIVER IN PERSON', 'SHIP', 'nal foxes wake. ');
   

4. OceanBaseデータベースでデータをクエリします。

   例：

   SELECT * FROM lineitem;
   

   実行結果は次のとおりです：

   +------------+-----------+-----------+--------------+------------+-----------------+------------+-------+--------------+--------------+------------+--------------+---------------+-------------------+------------+-------------------------------------+
   | l_orderkey | l_partkey | l_suppkey | l_linenumber | l_quantity | l_extendedprice | l_discount | l_tax | l_returnflag | l_linestatus | l_shipdate | l_commitdate | l_receiptdate | l_shipinstruct    | l_shipmode | l_comment                           |
   +------------+-----------+-----------+--------------+------------+-----------------+------------+-------+--------------+--------------+------------+--------------+---------------+-------------------+------------+-------------------------------------+
   |          1 |    155190 |      7706 |            1 |         17 |        21168.23 |       0.04 |  0.02 | N            | O            | 1996-03-13 | 1996-02-12   | 1996-03-22    | DELIVER IN PERSON | TRUCK      | egular courts above the             |
   |          1 |     67310 |      7311 |            2 |         36 |        45983.16 |       0.09 |  0.06 | N            | O            | 1996-04-12 | 1996-02-28   | 1996-04-20    | TAKE BACK RETURN  | MAIL       | ly final dependencies: slyly bold   |
   |          1 |     63700 |      3701 |            3 |          8 |        13309.60 |       0.10 |  0.02 | N            | O            | 1996-01-29 | 1996-03-05   | 1996-01-31    | TAKE BACK RETURN  | REG AIR    | riously. regular, express dep       |
   |          1 |      2132 |      4633 |            4 |         28 |        28955.64 |       0.09 |  0.06 | N            | O            | 1996-04-21 | 1996-03-30   | 1996-05-16    | NONE              | AIR        | lites. fluffily even de             |
   |          1 |     24027 |      1534 |            5 |         24 |        22824.48 |       0.10 |  0.04 | N            | O            | 1996-03-30 | 1996-03-14   | 1996-04-01    | NONE              | FOB        |  pending foxes. slyly re            |
   |          1 |     15635 |       638 |            6 |         32 |        49620.16 |       0.07 |  0.02 | N            | O            | 1996-01-30 | 1996-02-07   | 1996-02-03    | DELIVER IN PERSON | MAIL       | arefully slyly ex                   |
   |          2 |    106170 |      1191 |            1 |         38 |        44694.46 |       0.00 |  0.05 | N            | O            | 1997-01-28 | 1997-01-14   | 1997-02-02    | TAKE BACK RETURN  | RAIL       | ven requests. deposits breach a     |
   |          3 |      4297 |      1798 |            1 |         45 |        54058.05 |       0.06 |  0.00 | R            | F            | 1994-02-02 | 1994-01-04   | 1994-02-23    | NONE              | AIR        | ongside of the furiously brave acco |
   |          3 |     19036 |      6540 |            2 |         49 |        46796.47 |       0.10 |  0.00 | R            | F            | 1993-11-09 | 1993-12-20   | 1993-11-24    | TAKE BACK RETURN  | RAIL       |  unusual accounts. eve              |
   |          3 |    128449 |      3474 |            3 |         27 |        39890.88 |       0.06 |  0.07 | A            | F            | 1994-01-16 | 1993-11-22   | 1994-01-23    | DELIVER IN PERSON | SHIP       | nal foxes wake.                     |
   +------------+-----------+-----------+--------------+------------+-----------------+------------+-------+--------------+--------------+------------+--------------+---------------+-------------------+------------+-------------------------------------+
   10 rows in set
   

   説明

   JARパッケージなどのリソースを読み込む必要があるため、初回実行時は遅くなります。

データ型

MySQLデータベースには豊富なデータ型がありますが、OceanBaseデータベースのMySQL外部テーブルプラグインはまだ完全にはサポートしていません。現在のバージョンのOceanBaseデータベースのMySQL外部テーブルプラグインがサポートするデータ型は以下のとおりです：

• 整数型：TINYINT、SMALLINT、MEDIUMINT、INT、BIGINT（UNSIGNEDを含む）
• 浮動小数点数：FLOAT、DOUBLE、DECIMAL
• 文字列型：CHAR、VARCHAR
• テキスト型：TEXT、CLOB
• バイナリ型：BINARY、VARBINARY、BLOB
• 日付時刻：DATE、TIME、DATETIME、TIMESTAMP、YEAR
• ブール型：BOOLEAN
• 空間型：GIS関連
• その他の型：JSON、ENUM、SET

述語のプッシュダウンルール

データアクセス効率を向上させるため、OceanBaseデータベースは一部の述語をリモートのMySQLデータベースにプッシュダウンすることをサポートしています。

プッシュダウンがサポートされている述語の条件：

• データ型：整数、浮動小数点数（一部のシナリオ）、文字列（CHAR 型を除く）
• 演算子：=、!=(<>)、<=、<、>=、>、IS [NOT] NULL、[NOT] IN、[NOT] LIKE、[NOT] BETWEEN
• 組み合わせ式：AND、OR、NOT。

システムのアップグレード

既存のOceanBaseクラスタでは、ノードごとに再起動する方法でプラグインをインストールまたはアップグレードできます。

推奨されるアップグレード手順は以下のとおりです：

1. 新バージョンのプラグインJARファイルを指定ディレクトリ（パラメータob_java_connector_pathが指すディレクトリ）に配置します。
2. ノードを1つずつ再起動し、再起動時にノードのプラグインロード状況を確認します。
3. OceanBaseクラスタの再起動が完了したら、クラスタのプラグインインストール状況を確認します。

クラスタのアップグレードに関する情報については、OceanBaseクラスタのアップグレードを参照してください。

関連ドキュメント

外部テーブル作成構文の詳細については、CREATE EXTERNAL TABLEを参照してください。