このページでは、Data API を使用して Cloud SQL インスタンスのデータベースに対して SQL ステートメントを実行する方法について説明します。Data API を使用すると、Cloud SQL Admin API と gcloud CLI を使用して、Data API アクセスを有効にしたインスタンスで SQL ステートメントを実行できます。
Data API は、パブリック IP アドレス、プライベート サービス アクセス、または Private Service Connect を使用するインスタンスで使用できます。Data API は、データ操作言語（DML）、データ定義言語（DDL）、データクエリ言語（DQL）など、すべてのタイプの SQL ステートメントをサポートしています。Data API は、データベースのロールやユーザーの作成、スキーマの小規模な更新など、小規模で迅速な管理ステートメントの実行に適しています。
始める前に
インスタンスで SQL ステートメントを実行する前に、次の操作を行います。
- IAM データベース認証用にインスタンスを構成します。
- インスタンスに IAM ユーザーまたはサービス アカウントを追加し、SQL ステートメントを実行するために必要なロールまたは権限をアカウントに付与します。
必要なロールまたは権限
デフォルトでは、次のいずれかのロールを持つユーザーまたはサービス アカウントに、Cloud SQL インスタンスで SQL ステートメントを実行する権限（cloudsql.instances.executesql）があります。
Cloud SQL Admin（roles/cloudsql.admin）Cloud SQL Instance User（roles/cloudsql.instanceUser）Cloud SQL Studio User（roles/cloudsql.studioUser）
また、cloudsql.instances.executesql 権限を持つユーザーまたはサービス アカウントの IAM カスタムロールを定義することもできます。この権限は、IAM カスタムロールでサポートされています。
Data API を有効または無効にする
Data API を使用するには、インスタンスごとに有効にする必要があります。Data API はいつでも無効にできます。
gcloud
インスタンスで Data API アクセスを有効にするには、--data-api-access=ALLOW_DATA_API フラグを指定して gcloud sql instances patch コマンドを使用します。
gcloud sql instances patch INSTANCE_NAME --data-api-access=ALLOW_DATA_API
Data API アクセスを無効にするには、--data-api-access=DENY_DATA_API フラグを使用します。
gcloud sql instances patch INSTANCE_NAME --data-api-access=DENY_DATA_API
INSTANCE_NAME は、Data API を有効または無効にするインスタンスの名前に置き換えます。
SQL ステートメントを実行する
Cloud SQL インスタンスのデータベースに対して SQL ステートメントを実行するには、gcloud CLI または REST API を使用します。
gcloud
gcloud CLI を使用してインスタンスのデータベースに対して SQL ステートメントを実行するには、gcloud beta sql instances execute-sql コマンドを使用します。
gcloud beta sql instances execute-sql INSTANCE_NAME \ --database=DATABASE_NAME \ --sql=SQL_STATEMENT \ --partial_result_mode=PARTIAL_RESULT_MODE
次のように置き換えます。
- INSTANCE_NAME: インスタンスの名前。
- DATABASE_NAME: インスタンス内のデータベースの名前。
- SQL_STATEMENT: 実行する SQL ステートメント。ステートメントにスペースまたはシェル特殊文字が含まれている場合は、引用符で囲む必要があります。
- PARTIAL_RESULT_MODE: 省略可。結果が不完全な場合の対応方法を制御します。
ALLOW_PARTIAL_RESULT、FAIL_PARTIAL_RESULT、PARTIAL_RESULT_MODE_UNSPECIFIEDのいずれかです。切り捨て動作の変更をご覧ください。
必要に応じて --project=PROJECT_ID フラグを指定することもできます。
REST
REST API を使用してインスタンスのデータベースに対して SQL ステートメントを実行するには、executeSql エンドポイントに POST リクエストを送信します。
POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/executeSql
リクエストの本文には、データベース名と SQL ステートメントを含める必要があります。
{ "database": "DATABASE_NAME", "sqlStatement": "SQL_STATEMENT", "partialResultMode": "PARTIAL_RESULT_MODE" }
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- INSTANCE_NAME: インスタンスの名前。
- DATABASE_NAME: インスタンス内のデータベースの名前。
- SQL_STATEMENT: 実行する SQL ステートメント。
- PARTIAL_RESULT_MODE: 省略可。結果が 10 MB を超えた場合に API がどのように応答するかを制御します。
FAIL_PARTIAL_RESULTまたはALLOW_PARTIAL_RESULTのいずれかです。切り捨て動作の変更をご覧ください。
切り捨ての動作を変更する
SQL の実行時に大きな結果を処理する方法を制御できます。
- リクエストに
"partialResultMode"フィールドを含めます。このフィールドでは次の値を指定できます。FAIL_PARTIAL_RESULT: 結果が 10 MB を超える場合、または部分的な結果しか取得できない場合は、エラーをスローします。結果を返さないでください。ALLOW_PARTIAL_RESULT: 結果が 10 MB を超える場合、またはエラーにより部分的な結果しか取得できない場合は、切り捨てられた結果を返し、partial_resultを true に設定します。エラーをスローしないでください。
制限事項
- レスポンスのサイズの上限は 10 MB です。
partialResultModeがALLOW_PARTIAL_RESULTに設定されている場合、このサイズを超える結果は切り捨てられます。それ以外の場合は、エラーがスローされます。 - リクエストは 0.5 MB に制限されています。
- SQL ステートメントは、実行中の Cloud SQL for MySQL インスタンスに対してのみ実行できます。
- Cloud SQL は、外部サーバー レプリケーション用に設定されたインスタンスでの Data API の使用をサポートしていません。
- 30 秒を超えるリクエストはキャンセルされます。
SET SESSION MAX_EXECUTION_TIMEを使用してステートメント タイムアウトを長く設定することはできません。Cloud SQL for MySQL 5.6 と 5.7 では、長時間実行される DDL ステートメントがタイムアウトすると、安全にロールバックできない孤立したファイルやテーブルが発生する可能性があります。大きなテーブルに対してALTER TABLEのようなステートメントを使用する場合は注意が必要です。 - Cloud SQL では、各ユーザーの同時
executeSqlリクエストの数がインスタンスごとに 10 個に制限されています。この上限に達すると、後続のリクエストは「Maximum concurrent reads 10 reached.」というエラーで失敗します。 - 各レスポンスには、最大 10 個のデータベース メッセージまたは警告を含めることができます。
- ステートメントの構文エラーまたは実行エラーがある場合、結果は返されません。
- Cloud SQL for MySQL の場合、通知と警告は、複数ステートメントの実行の最後のステートメントでのみ使用できます。
- 大量のメモリを消費するステートメントは、メモリ不足エラーを引き起こす可能性があります。これらのエラーを回避する方法について詳しくは、メモリ使用量を管理するためのベスト プラクティスをご覧ください。メモリ使用率が高いデータベース インスタンスを実行すると、パフォーマンスの問題や機能の停止、さらにはデータベース停止の原因となることがよくあります。