JDBC to Cloud Spanner テンプレート

Dataproc Serverless JDBC to Spanner テンプレートを使用して、JDBC データベースから Spanner にデータを抽出します。

このテンプレートでは、次のデータベースを入力としてサポートしています。

MySQL
PostgreSQL
Microsoft SQL Server
Oracle

テンプレートの使用

テンプレートを実行するには、gcloud CLI または Dataproc API を使用します。

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

PROJECT_ID: 必須。IAM 設定に載っている Google Cloud プロジェクト ID。
REGION: 必須。Compute Engine のリージョン。
TEMPLATE_VERSION: 必須。最新のテンプレートバージョンまたは特定バージョンの日付（2023-03-17_v0.1.0-beta など）には latest を指定します（gs://dataproc-templates-binaries にアクセスするか、gsutil ls gs://dataproc-templates-binaries を実行して、使用可能なテンプレートバージョンを一覧表示します）。
SUBNET: 省略可。サブネットが指定されていない場合、default ネットワークの指定された REGION のサブネットが選択されます。
例: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

JDBC_CONNECTOR_CLOUD_STORAGE_PATH: 必須。JDBC コネクタ jar が格納されるファイル名を含む、Cloud Storage の完全なパス。次のコマンドを使用して、Cloud Storage にアップロードする JDBC コネクタをダウンロードできます。

MySQL:

wget http://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-5.1.30.tar.gz

Postgres SQL:

wget https://jdbc.postgresql.org/download/postgresql-42.2.6.jar

MS SQL Server:

wget https://repo1.maven.org/maven2/com/microsoft/sqlserver/mssql-jdbc/6.4.0.jre8/mssql-jdbc-6.4.0.jre8.jar

Oracle:

wget https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc8/21.7.0.0/ojdbc8-21.7.0.0.jar

必要となる JDBC_CONNECTION_URL の作成に次の変数が使用されます。

JDBC_HOST、JDBC_PORT、JDBC_DATABASE、または Oracle、JDBC_SERVICE、JDBC_USERNAME、JDBC_PASSWORD: 必須。JDBC のホスト、ポート、データベース、ユーザー名、パスワード。

MySQL:

jdbc:mysql://JDBC_HOST:JDBC_PORT/JDBC_DATABASE?user=JDBC_USERNAME&password=JDBC_PASSWORD

PostgreSQL:

jdbc:postgresql://JDBC_HOST:JDBC_PORT/JDBC_DATABASE?user=JDBC_USERNAME&password=JDBC_PASSWORD

MS SQL Server:

jdbc:sqlserver://JDBC_HOST:JDBC_PORT;databaseName=JDBC_DATABASE;user=JDBC_USERNAME;password=JDBC_PASSWORD

Oracle:

jdbc:oracle:thin:@//JDBC_HOST:JDBC_PORT/JDBC_SERVICE?user=JDBC_USERNAME&password=JDBC_PASSWORD

DRIVER: 必須。接続に使用される JDBC ドライバ:

MySQL:
```
com.mysql.cj.jdbc.Driver
```
Postgres SQL:
```
org.postgresql.Driver
```

MS SQL Server:

  com.microsoft.sqlserver.jdbc.SQLServerDriver

Oracle:
```
oracle.jdbc.driver.OracleDriver
```

QUERY または QUERY_FILE: 必須 QUERY または QUERY_FILE のいずれかを設定し、JDBC からデータを抽出するために使用するクエリを指定します。
INPUT_PARTITION_COLUMN、LOWERBOUND、UPPERBOUND、NUM_PARTITIONS: 省略可。使用する場合は、次のパラメータをすべて指定する必要があります。
- INPUT_PARTITION_COLUMN: JDBC 入力テーブルのパーティション列名。
- LOWERBOUND: パーティションの入力ストライドの決定に使用される JDBC 入力テーブルパーティション列の下限。
- UPPERBOUND: パーティションの入力ストライドの決定に使用される JDBC 入力テーブルパーティション列の上限。
- NUM_PARTITIONS: テーブルの読み取りと書き込みの並列処理に使用できるパーティションの最大数。指定すると、この値が JDBC の入力接続と出力接続に使用されます。デフォルト: 10。
FETCHSIZE: 省略可。フェッチするラウンドトリップあたりの行数。デフォルト: 10。
JDBC_SESSION_INIT: 省略可。Java テンプレートを読み取るセッション初期化ステートメント。
TEMPVIEW、SQL_QUERY: 省略可。これら 2 つのオプションのパラメータを使用して、Spanner にデータを読み込むときに Spark SQL 変換を適用できます。TEMPVIEW は一時的なビュー名で、SQL_QUERY はクエリステートメントです。TEMPVIEW と SQL_QUERY のテーブル名が一致する必要があります。
INSTANCE: 必須。Spanner インスタンス ID。
SPANNER_DATABASE: 必須。Spanner データベース ID。
TABLE: 必須。Spanner 出力のテーブル名。
MODE: 省略可。Spanner 出力の書き込みモード。オプション: Append、Overwrite、Ignore、ErrorIfExists。デフォルトは ErrorIfExists です。
PRIMARY_KEY: 必須。Spanner 出力テーブルを作成するときに必要なカンマ区切りの主キー列。
SERVICE_ACCOUNT: 省略可。指定しない場合は、デフォルトの Compute Engine サービスアカウントが使用されます。
PROPERTY、PROPERTY_VALUE: 省略可。Spark プロパティ=value ペアのカンマ区切りのリスト。
LABEL、LABEL_VALUE: 省略可。label=value ペアのカンマ区切りのリスト。
LOG_LEVEL: 省略可。ロギングのレベル。ALL、DEBUG、ERROR、FATAL、INFO、OFF、TRACE、WARN のいずれかです。デフォルト: INFO
KMS_KEY: 省略可。暗号化に使用する Cloud Key Management Service 鍵。鍵が指定されていない場合、データは Google が管理する鍵を使用して保存時に暗号化されます。
例: projects/PROJECT_ID/regions/REGION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME

次のコマンドを実行します。

Linux、macOS、Cloud Shell

gcloud dataproc batches submit spark \
    --class=com.google.cloud.dataproc.templates.main.DataProcTemplate \
    --version="1.1" \
    --project="PROJECT_ID" \
    --region="REGION" \
    --jars="gs://dataproc-templates-binaries/TEMPLATE_VERSION/java/dataproc-templates.jar,JDBC_CONNECTOR_CLOUD_STORAGE_PATH" \
    --subnet="SUBNET" \
    --kms-key="KMS_KEY" \
    --service-account="SERVICE_ACCOUNT" \
    --properties="PROPERTY=PROPERTY_VALUE" \
    --labels="LABEL=LABEL_VALUE" \
    -- --template=JDBCTOSPANNER \
    --templateProperty log.level="LOG_LEVEL" \
    --templateProperty project.id="PROJECT_ID" \
    --templateProperty jdbctospanner.jdbc.url="JDBC_CONNECTION_URL" \
    --templateProperty jdbctospanner.jdbc.driver.class.name="DRIVER" \
    --templateProperty jdbctospanner.jdbc.fetchsize="FETCHSIZE" \
    --templateProperty jdbctospanner.jdbc.sessioninitstatement="JDBC_SESSION_INIT" \
    --templateProperty jdbctospanner.sql="QUERY" \
    --templateProperty jdbctospanner.sql.file="QUERY_FILE" \
    --templateProperty jdbctospanner.sql.numPartitions="NUM_PARTITIONS" \
    --templateProperty jdbctospanner.sql.partitionColumn="INPUT_PARTITION_COLUMN" \
    --templateProperty jdbctospanner.sql.lowerBound="LOWERBOUND" \
    --templateProperty jdbctospanner.sql.upperBound="UPPERBOUND" \
    --templateProperty jdbctospanner.output.instance="INSTANCE" \
    --templateProperty jdbctospanner.output.database="SPANNER_DATABASE" \
    --templateProperty jdbctospanner.output.table="TABLE" \
    --templateProperty jdbctospanner.output.saveMode="MODE" \
    --templateProperty jdbctospanner.output.primaryKey="PRIMARY_KEY" \
    --templateProperty jdbctospanner.output.batch.size="BATCHSIZE" \
    --templateProperty jdbctospanner.temp.table="TEMPVIEW" \
    --templateProperty jdbctospanner.temp.query="SQL_QUERY"

Windows（PowerShell）

gcloud dataproc batches submit spark `
    --class=com.google.cloud.dataproc.templates.main.DataProcTemplate `
    --version="1.1" `
    --project="PROJECT_ID" `
    --region="REGION" `
    --jars="gs://dataproc-templates-binaries/TEMPLATE_VERSION/java/dataproc-templates.jar,JDBC_CONNECTOR_CLOUD_STORAGE_PATH" `
    --subnet="SUBNET" `
    --kms-key="KMS_KEY" `
    --service-account="SERVICE_ACCOUNT" `
    --properties="PROPERTY=PROPERTY_VALUE" `
    --labels="LABEL=LABEL_VALUE" `
    -- --template=JDBCTOSPANNER `
    --templateProperty log.level="LOG_LEVEL" `
    --templateProperty project.id="PROJECT_ID" `
    --templateProperty jdbctospanner.jdbc.url="JDBC_CONNECTION_URL" `
    --templateProperty jdbctospanner.jdbc.driver.class.name="DRIVER" `
    --templateProperty jdbctospanner.jdbc.fetchsize="FETCHSIZE" `
    --templateProperty jdbctospanner.jdbc.sessioninitstatement="JDBC_SESSION_INIT" `
    --templateProperty jdbctospanner.sql="QUERY" `
    --templateProperty jdbctospanner.sql.file="QUERY_FILE" `
    --templateProperty jdbctospanner.sql.numPartitions="NUM_PARTITIONS" `
    --templateProperty jdbctospanner.sql.partitionColumn="INPUT_PARTITION_COLUMN" `
    --templateProperty jdbctospanner.sql.lowerBound="LOWERBOUND" `
    --templateProperty jdbctospanner.sql.upperBound="UPPERBOUND" `
    --templateProperty jdbctospanner.output.instance="INSTANCE" `
    --templateProperty jdbctospanner.output.database="SPANNER_DATABASE" `
    --templateProperty jdbctospanner.output.table="TABLE" `
    --templateProperty jdbctospanner.output.saveMode="MODE" `
    --templateProperty jdbctospanner.output.primaryKey="PRIMARY_KEY" `
    --templateProperty jdbctospanner.output.batch.size="BATCHSIZE" `
    --templateProperty jdbctospanner.temp.table="TEMPVIEW" `
    --templateProperty jdbctospanner.temp.query="SQL_QUERY"

Windows（cmd.exe）

gcloud dataproc batches submit spark ^
    --class=com.google.cloud.dataproc.templates.main.DataProcTemplate ^
    --version="1.1" ^
    --project="PROJECT_ID" ^
    --region="REGION" ^
    --jars="gs://dataproc-templates-binaries/TEMPLATE_VERSION/java/dataproc-templates.jar,JDBC_CONNECTOR_CLOUD_STORAGE_PATH" ^
    --subnet="SUBNET" ^
    --kms-key="KMS_KEY" ^
    --service-account="SERVICE_ACCOUNT" ^
    --properties="PROPERTY=PROPERTY_VALUE" ^
    --labels="LABEL=LABEL_VALUE" ^
    -- --template=JDBCTOSPANNER ^
    --templateProperty log.level="LOG_LEVEL" ^
    --templateProperty project.id="PROJECT_ID" ^
    --templateProperty jdbctospanner.jdbc.url="JDBC_CONNECTION_URL" ^
    --templateProperty jdbctospanner.jdbc.driver.class.name="DRIVER" ^
    --templateProperty jdbctospanner.jdbc.fetchsize="FETCHSIZE" ^
    --templateProperty jdbctospanner.jdbc.sessioninitstatement="JDBC_SESSION_INIT" ^
    --templateProperty jdbctospanner.sql="QUERY" ^
    --templateProperty jdbctospanner.sql.file="QUERY_FILE" ^
    --templateProperty jdbctospanner.sql.numPartitions="NUM_PARTITIONS" ^
    --templateProperty jdbctospanner.sql.partitionColumn="INPUT_PARTITION_COLUMN" ^
    --templateProperty jdbctospanner.sql.lowerBound="LOWERBOUND" ^
    --templateProperty jdbctospanner.sql.upperBound="UPPERBOUND" ^
    --templateProperty jdbctospanner.output.instance="INSTANCE" ^
    --templateProperty jdbctospanner.output.database="SPANNER_DATABASE" ^
    --templateProperty jdbctospanner.output.table="TABLE" ^
    --templateProperty jdbctospanner.output.saveMode="MODE" ^
    --templateProperty jdbctospanner.output.primaryKey="PRIMARY_KEY" ^
    --templateProperty jdbctospanner.output.batch.size="BATCHSIZE" ^
    --templateProperty jdbctospanner.temp.table="TEMPVIEW" ^
    --templateProperty jdbctospanner.temp.query="SQL_QUERY"

REST

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: 必須。IAM 設定に載っている Google Cloud プロジェクト ID。
REGION: 必須。Compute Engine のリージョン。
TEMPLATE_VERSION: 必須。最新のテンプレートバージョンまたは特定バージョンの日付（2023-03-17_v0.1.0-beta など）には latest を指定します（gs://dataproc-templates-binaries にアクセスするか、gsutil ls gs://dataproc-templates-binaries を実行して、使用可能なテンプレートバージョンを一覧表示します）。
SUBNET: 省略可。サブネットが指定されていない場合、default ネットワークの指定された REGION のサブネットが選択されます。
例: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

MySQL:

wget http://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-5.1.30.tar.gz

Postgres SQL:

wget https://jdbc.postgresql.org/download/postgresql-42.2.6.jar

MS SQL Server:

wget https://repo1.maven.org/maven2/com/microsoft/sqlserver/mssql-jdbc/6.4.0.jre8/mssql-jdbc-6.4.0.jre8.jar

Oracle:

wget https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc8/21.7.0.0/ojdbc8-21.7.0.0.jar

必要となる JDBC_CONNECTION_URL の作成に次の変数が使用されます。
- JDBC_HOST、JDBC_PORT、JDBC_DATABASE、または Oracle、JDBC_SERVICE、JDBC_USERNAME、JDBC_PASSWORD: 必須。JDBC のホスト、ポート、データベース、ユーザー名、パスワード。
- DRIVER: 必須。接続に使用される JDBC ドライバ:
  - MySQL:
```
com.mysql.cj.jdbc.Driver
```
  - Postgres SQL:
```
org.postgresql.Driver
```
  - MS SQL Server:
```
  com.microsoft.sqlserver.jdbc.SQLServerDriver
```
  - Oracle:
```
oracle.jdbc.driver.OracleDriver
```
- QUERY または QUERY_FILE: 必須 QUERY または QUERY_FILE のいずれかを設定し、JDBC からデータを抽出するために使用するクエリを指定します。
- INPUT_PARTITION_COLUMN、LOWERBOUND、UPPERBOUND、NUM_PARTITIONS: 省略可。使用する場合は、次のパラメータをすべて指定する必要があります。
  - INPUT_PARTITION_COLUMN: JDBC 入力テーブルのパーティション列名。
  - LOWERBOUND: パーティションの入力ストライドの決定に使用される JDBC 入力テーブルパーティション列の下限。
  - UPPERBOUND: パーティションの入力ストライドの決定に使用される JDBC 入力テーブルパーティション列の上限。
  - NUM_PARTITIONS: テーブルの読み取りと書き込みの並列処理に使用できるパーティションの最大数。指定すると、この値が JDBC の入力接続と出力接続に使用されます。デフォルト: 10。
- FETCHSIZE: 省略可。フェッチするラウンドトリップあたりの行数。デフォルト: 10。
- JDBC_SESSION_INIT: 省略可。Java テンプレートを読み取るセッション初期化ステートメント。
- TEMPVIEW、SQL_QUERY: 省略可。これら 2 つのオプションのパラメータを使用して、Spanner にデータを読み込むときに Spark SQL 変換を適用できます。TEMPVIEW は一時的なビュー名で、SQL_QUERY はクエリステートメントです。TEMPVIEW と SQL_QUERY のテーブル名が一致する必要があります。
- INSTANCE: 必須。Spanner インスタンス ID。
- SPANNER_DATABASE: 必須。Spanner データベース ID。
- TABLE: 必須。Spanner 出力のテーブル名。
- MODE: 省略可。Spanner 出力の書き込みモード。オプション: Append、Overwrite、Ignore、ErrorIfExists。デフォルトは ErrorIfExists です。
- PRIMARY_KEY: 必須。Spanner 出力テーブルを作成するときに必要なカンマ区切りの主キー列。
- SERVICE_ACCOUNT: 省略可。指定しない場合は、デフォルトの Compute Engine サービスアカウントが使用されます。
- PROPERTY、PROPERTY_VALUE: 省略可。Spark プロパティ=value ペアのカンマ区切りのリスト。
- LABEL、LABEL_VALUE: 省略可。label=value ペアのカンマ区切りのリスト。
- LOG_LEVEL: 省略可。ロギングのレベル。ALL、DEBUG、ERROR、FATAL、INFO、OFF、TRACE、WARN のいずれかです。デフォルト: INFO
- KMS_KEY: 省略可。暗号化に使用する Cloud Key Management Service 鍵。鍵が指定されていない場合、データは Google が管理する鍵を使用して保存時に暗号化されます。
  例: projects/PROJECT_ID/regions/REGION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME
HTTP メソッドと URL:
```
POST https://dataproc.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/batches
```
リクエストの本文（JSON）:
```
{
  "environmentConfig": {
    "executionConfig": {
      "subnetworkUri": "SUBNET",
      "kmsKey": "KMS_KEY",
      "serviceAccount": "SERVICE_ACCOUNT"
    }
  },
  "labels": {
    "LABEL": "LABEL_VALUE"
  },
  "runtimeConfig": {
    "version": "1.1",
    "properties": {
      "PROPERTY": "PROPERTY_VALUE"
    }
  },
  "sparkBatch": {
    "mainClass": "com.google.cloud.dataproc.templates.main.DataProcTemplate",
    "args": [
      "--template","JDBCTOSPANNER",
      "--templateProperty","log.level=LOG_LEVEL",
      "--templateProperty","project.id=PROJECT_ID",
      "--templateProperty","jdbctospanner.jdbc.url=JDBC_CONNECTION_URL",
      "--templateProperty","jdbctospanner.jdbc.driver.class.name=DRIVER",
      "--templateProperty","jdbctospanner.jdbc.fetchsize=FETCHSIZE",
      "--templateProperty","jdbctospanner.jdbc.sessioninitstatement=JDBC_SESSION_INIT",
      "--templateProperty","jdbctospanner.sql=QUERY",
      "--templateProperty","jdbctospanner.sql.file=QUERY_FILE",
      "--templateProperty","jdbctospanner.sql.numPartitions=NUM_PARTITIONS",
      "--templateProperty","jdbctospanner.sql.partitionColumn=INPUT_PARTITION_COLUMN",
      "--templateProperty","jdbctospanner.sql.lowerBound=LOWERBOUND",
      "--templateProperty","jdbctospanner.sql.upperBound=UPPERBOUND",
      "--templateProperty","jdbctospanner.output.instance=INSTANCE",
      "--templateProperty","jdbctospanner.output.database=SPANNER_DATABASE",
      "--templateProperty","jdbctospanner.output.table=TABLE",
      "--templateProperty","jdbctospanner.output.saveMode=MODE",
      "--templateProperty","jdbctospanner.output.primaryKey=PRIMARY_KEY",
      "--templateProperty","jdbctospanner.output.batch.size=BATCHSIZE",
      "--templateProperty","jdbctospanner.temp.table=TEMPVIEW",
      "--templateProperty","jdbctospanner.temp.query=SQL_QUERY"
    ],
    "jarFileUris": [
      "gs://dataproc-templates-binaries/TEMPLATE_VERSION/java/dataproc-templates.jar","JDBC_CONNECTOR_CLOUD_STORAGE_PATH"
    ]
  }
}
```
リクエストを送信するには、次のいずれかのオプションを展開します。
curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dataproc.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/batches"
```
PowerShell（Windows）

注:次のコマンドは、gcloud init または gcloud auth login を実行してユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dataproc.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/batches" | Select-Object -Expand Content
```
次のような JSON レスポンスが返されます。
```
{
  "name": "projects/PROJECT_ID/regions/REGION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata",
    "batch": "projects/PROJECT_ID/locations/REGION/batches/BATCH_ID",
    "batchUuid": "de8af8d4-3599-4a7c-915c-798201ed1583",
    "createTime": "2023-02-24T03:31:03.440329Z",
    "operationType": "BATCH",
    "description": "Batch"
  }
}
```

JDBC to Cloud Spanner テンプレート

テンプレートの使用

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）