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 mysqlmysql-connector-java Oracle com.oracle.database.jdbcojdbc8 PostgreSQL org.postgresqlpostgresql ここに記載されていないドライバーについては、使用前に互換性を確認してください。
-
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 |
次のステップ
-
MySQL CDC ソーステーブルの作成 — MySQL からリアルタイムの変更データをキャプチャする
-
PostgreSQL CDC ソーステーブルの作成 (パブリックプレビュー) — PostgreSQL からリアルタイムの変更データをキャプチャする