すべてのプロダクト
Search
ドキュメントセンター

Realtime Compute for Apache Flink:JDBC connector

最終更新日:Oct 10, 2026

JDBC コネクタは、リレーショナルデータベース (MySQL、PostgreSQL、Oracle) との間で、Flink SQL ジョブの標準 SQL DDL を使用してデータの読み書きを行います。

サポートされるテーブルタイプ:ソーステーブル、ディメンションテーブル、結果テーブル

サポートされる実行モード:ストリーミングモード、バッチモード、SQL API

結果テーブルでの更新と削除:サポートされています

前提条件

開始する前に、以下を確認してください。

  • ターゲットのデータベースとテーブルが既に存在していること

  • ご利用のデータベース用の JDBC ドライバー JAR がアップロード可能であること

制限事項

  • 有界読み取り:JDBC ソーステーブルは有界ソースです。すべての行が読み取られるとタスクは完了します。リアルタイムの変更データをキャプチャするには、代わりに Change Data Capture (CDC) コネクタを使用してください。詳細については、「MySQL CDC ソーステーブルの作成」および「PostgreSQL CDC ソーステーブルの作成 (パブリックプレビュー)」をご参照ください。

  • PostgreSQL のバージョン:結果テーブルは ON CONFLICT 句に依存するため、PostgreSQL への書き込みにはバージョン 9.5 以降が必要です。

  • JDBC ドライバーのアップロード:ジョブを実行する前に、JDBC ドライバーの JAR を依存関係ファイルとしてアップロードしてください。一般的なドライバーは以下の通りです。

    データベース グループ ID アーティファクト ID
    MySQL mysql mysql-connector-java
    Oracle com.oracle.database.jdbc ojdbc8
    PostgreSQL org.postgresql postgresql

    ここに記載されていないドライバーについては、使用前に互換性を確認してください。

  • MySQL のアップサート動作:プライマリキーを持つ MySQL の結果テーブルに書き込む際、コネクタは INSERT INTO ... ON DUPLICATE KEY UPDATE ... 文を発行します。

    警告

    プライマリキーが異なる場合でも、一意なインデックスの値が重複する行を挿入すると、一意なインデックス制約を持つ物理テーブル内の既存の行が上書きされ、データ損失が発生します。

JDBC テーブルの作成

CREATE TABLE jdbc_table (
  `id`   BIGINT,
  `name` VARCHAR,
  PRIMARY KEY (id) NOT ENFORCED
) WITH (
  'connector'  = 'jdbc',
  'url'        = 'jdbc:<db-type>://<host>:<port>/<database>',
  'table-name' = '<yourTable>',
  'username'   = '<yourUsername>',
  'password'   = '<yourPassword>'
);

コネクタオプション

一般

オプション 型 必須 デフォルト 説明
connector STRING はい — jdbc に設定します。
url STRING はい — データベースの JDBC URL。
table-name STRING はい — 読み書き対象のテーブル名。
username STRING いいえ — データベースのユーザー名。password と一緒に設定します。両方のオプションは、secret://kms.<secret-name>.<key> 形式の KMS 認証情報リファレンスを受け入れます。
password STRING いいえ — データベースのパスワード。
kms.endpoint STRING いいえ — KMS 共有ゲートウェイまたは専用ゲートウェイのエンドポイント。例:kms.cn-hangzhou.aliyuncs.com。詳細については、「KMS エンドポイント」をご参照ください。KMS 認証情報を使用する場合に必須です。詳細については、「KMS 認証情報管理の統合」をご参照ください。
kms.akless.assume-role.role-name STRING いいえ — KMS 認証情報の読み取りに使用される RAM ロールの名前。このロールは、事前にセキュリティ設定で参照されている必要があります。KMS 認証情報を使用する場合に必須です。詳細については、「KMS 認証情報管理の統合」をご参照ください。
kms.ca STRING いいえ — KMS 専用ゲートウェイの CA 証明書のパス。このオプションには、oss://flink-fullymanaged-<workspace ID>/artifacts/namespaces/<namespace name>/<file name> 形式の絶対 OSS パスを設定します。KMS 専用ゲートウェイを使用する場合に必須です。詳細については、「KMS 認証情報管理の統合」をご参照ください。

ソースオプション

オプション 型 必須 デフォルト 説明
scan.partition.column STRING いいえ — データをパーティションに分割するために使用される列。この列は NUMERIC または TIMESTAMP 型である必要があり、データベースはその型と数値との比較をサポートしている必要があります。詳細については、「パーティションスキャン」をご参照ください。
scan.partition.num INTEGER いいえ — パーティションの数。
scan.partition.lower-bound LONG いいえ — 最初のパーティションの最小値。
scan.partition.upper-bound LONG いいえ — 最後のパーティションの最大値。
scan.fetch-size INTEGER いいえ 0 データベースへのラウンドトリップごとにフェッチされる行数。0 に設定すると、このオプションは無視されます。
scan.auto-commit BOOLEAN いいえ true 読み取りトランザクションの自動コミットを有効にします。

シンクオプション

オプション 型 必須 デフォルト 説明
sink.buffer-flush.max-rows INTEGER いいえ 100 フラッシュする前にバッファリングする最大行数。0 に設定すると、各行が即座にフラッシュされます。
sink.buffer-flush.interval DURATION いいえ 1000 ms バッファリングされた行をフラッシュするまでの最大保持時間。0 に設定すると、各行が即座にフラッシュされます。
sink.max-retries INTEGER いいえ 3 失敗時の最大書き込みリトライ回数。
sink.ignore-delete BOOLEAN いいえ false 削除メッセージを転送せずに無視します。VVR 11.4 以降が必要です。
sink.ignore-delete-mode STRING いいえ ALL sink.ignore-delete が true の場合に無視する削除メッセージを制御します。VVR 11.4 以降が必要です。有効な値:ALL (-D と -U を無視)、REAL_DELETE (-D のみ無視)、UPDATE_BEFORE (-U のみ無視)。
説明

バッファリングされた行を行数ではなくタイマーで非同期にフラッシュするには、sink.buffer-flush.max-rows を 0 に設定し、sink.buffer-flush.interval を希望のフラッシュ間隔に設定します。

ディメンションテーブルオプション

オプション 型 必須 デフォルト 説明
lookup.cache.max-rows INTEGER いいえ — ルックアップキャッシュの最大行数。キャッシュが満杯になると、最も長く使用されていない行が有効期限切れになります。lookup.cache.max-rows と lookup.cache.ttl の両方が設定されていない限り、キャッシュは無効になります。
lookup.cache.ttl DURATION いいえ — キャッシュされた行が有効期限切れになるまでの最大有効期間。
lookup.cache.caching-missing-key BOOLEAN いいえ true 見つからないキーに対するデータベースクエリの繰り返しを避けるため、空のルックアップ結果をキャッシュします。空の結果のキャッシュをスキップするには false に設定します。
lookup.max-retries INTEGER いいえ 3 データベースクエリが失敗した場合の最大リトライ回数。

PostgreSQL オプション

オプション 型 必須 デフォルト 説明
source.extend-type.enabled BOOLEAN いいえ false true の場合、ソーステーブルとディメンションテーブルは PostgreSQL の JSONB および UUID 列を Flink の STRING にマッピングします。UUID 列でのルックアップ結合の場合は、PostgreSQL がキャストではなく実際の型でクエリを実行するように、JDBC URL に stringtype=unspecified も追加してください。

主な動作

パーティションスキャン

ソーステーブルからの並列読み取りを有効にするには、scan.partition.column、scan.partition.lower-bound、scan.partition.upper-bound オプションを scan.partition.num と一緒に設定します。パーティション列は数値型または TIMESTAMP 型である必要があります。分割の計算方法の詳細については、Apache Flink ドキュメントの「パーティションスキャン」をご参照ください。

ルックアップキャッシュ

デフォルトでは、すべてのルックアップ結合クエリは直接データベースにヒットします。lookup.cache.max-rows と lookup.cache.ttl の両方を設定して LRU キャッシュを有効にすることで、データがわずかに古くなる可能性がありますが、データベースの負荷を軽減できます。

べき等書き込み

結果テーブルにプライマリキーがある場合、コネクタはデータベース固有のアップサート文を発行します。MySQL の場合、コネクタは INSERT ... ON DUPLICATE KEY UPDATE ... を使用します。

例

3つの例はすべて、ステートメントが自己完結型になるように、軽量な対向先として blackhole または datagen コネクタを使用しています。

データベースからの読み取り (ソーステーブル)

CREATE TEMPORARY TABLE jdbc_source (
  `id`   INT,
  `name` VARCHAR
) WITH (
  'connector'  = 'jdbc',
  'url'        = 'jdbc:mysql://localhost:3306/mydb',
  'table-name' = '<yourTable>',
  'username'   = '<yourUsername>',
  'password'   = '<yourPassword>'
);

CREATE TEMPORARY TABLE blackhole_sink (
  `id`   INT,
  `name` VARCHAR
) WITH (
  'connector' = 'blackhole'
);

INSERT INTO blackhole_sink SELECT * FROM jdbc_source;

データベースへの書き込み (結果テーブル)

CREATE TEMPORARY TABLE datagen_source (
  `name` VARCHAR,
  `age`  INT
) WITH (
  'connector' = 'datagen'
);

CREATE TEMPORARY TABLE jdbc_sink (
  `name` VARCHAR,
  `age`  INT
) WITH (
  'connector'  = 'jdbc',
  'url'        = 'jdbc:mysql://localhost:3306/mydb',
  'table-name' = '<yourTable>',
  'username'   = '<yourUsername>',
  'password'   = '<yourPassword>'
);

INSERT INTO jdbc_sink SELECT * FROM datagen_source;

データベースルックアップによるストリームのエンリッチ (ディメンションテーブル)

CREATE TEMPORARY TABLE datagen_source (
  `id`       INT,
  `data`     BIGINT,
  `proctime` AS PROCTIME()
) WITH (
  'connector' = 'datagen'
);

CREATE TEMPORARY TABLE jdbc_dim (
  `id`   INT,
  `name` VARCHAR
) WITH (
  'connector'  = 'jdbc',
  'url'        = 'jdbc:mysql://localhost:3306/mydb',
  'table-name' = '<yourTable>',
  'username'   = '<yourUsername>',
  'password'   = '<yourPassword>'
);

CREATE TEMPORARY TABLE blackhole_sink (
  `id`   INT,
  `data` BIGINT,
  `name` VARCHAR
) WITH (
  'connector' = 'blackhole'
);

-- 処理時間に各ストリームレコードに対応する名前をルックアップします
INSERT INTO blackhole_sink
SELECT T.`id`, T.`data`, H.`name`
FROM datagen_source AS T
JOIN jdbc_dim FOR SYSTEM_TIME AS OF T.proctime AS H
  ON T.id = H.id;

データ型マッピング

MySQL Oracle PostgreSQL Flink SQL
TINYINT — — TINYINT
SMALLINT, TINYINT UNSIGNED — SMALLINT, INT2, SMALLSERIAL, SERIAL2 SMALLINT
INT, MEDIUMINT, SMALLINT UNSIGNED — INTEGER, SERIAL INT
BIGINT, INT UNSIGNED — BIGINT, BIGSERIAL BIGINT
BIGINT UNSIGNED — — DECIMAL(20, 0)
FLOAT BINARY_FLOAT REAL, FLOAT4 FLOAT
DOUBLE, DOUBLE PRECISION BINARY_DOUBLE FLOAT8, DOUBLE PRECISION DOUBLE
NUMERIC(p, s), DECIMAL(p, s) SMALLINT, FLOAT(s), DOUBLE PRECISION, REAL, NUMBER(p, s) NUMERIC(p, s), DECIMAL(p, s) DECIMAL(p, s)
BOOLEAN, TINYINT(1) — BOOLEAN BOOLEAN
DATE DATE DATE DATE
TIME [(p)] DATE TIME [(p)] [WITHOUT TIMEZONE] TIME [(p)] [WITHOUT TIMEZONE]
DATETIME [(p)] TIMESTAMP [(p)] [WITHOUT TIMEZONE] TIMESTAMP [(p)] [WITHOUT TIMEZONE] TIMESTAMP [(p)] [WITHOUT TIMEZONE]
CHAR(n), VARCHAR(n), TEXT CHAR(n), VARCHAR(n), CLOB CHAR(n), CHARACTER(n), VARCHAR(n), CHARACTER VARYING(n), TEXT, JSONB, UUID STRING
BINARY, VARBINARY, BLOB RAW(s), BLOB BYTEA BYTES
— — ARRAY ARRAY

次のステップ