Cloud SQL Data API を使用して SQL ステートメントを実行する

このページでは、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 は、データベースのロールやユーザーの作成、スキーマの小規模な更新など、小規模で迅速な管理ステートメントの実行に適しています。Data API を使用して PostgreSQL 拡張機能を有効にすることもできます。

始める前に

インスタンスで 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 PostgreSQL インスタンスに対してのみ実行できます。
  • Cloud SQL は、外部サーバー レプリケーション用に設定されたインスタンスでの Data API の使用をサポートしていません。
  • 30 秒を超えるリクエストはキャンセルされます。SET STATEMENT_TIMEOUT を使用してステートメント タイムアウトを長く設定することはできません。
  • Cloud SQL では、各ユーザーの同時 executeSql リクエストの数がインスタンスごとに 10 個に制限されています。この上限に達すると、後続のリクエストは「Maximum concurrent reads 10 reached.」というエラーで失敗します。
  • 各レスポンスには、最大 10 個のデータベース メッセージまたは警告を含めることができます。
  • ステートメントの構文エラーまたは実行エラーがある場合、結果は返されません。
  • 大量のメモリを消費するステートメントは、メモリ不足エラーを引き起こす可能性があります。これらのエラーを回避する方法について詳しくは、メモリ使用量を管理するためのベスト プラクティスをご覧ください。メモリ使用率が高いデータベース インスタンスを実行すると、パフォーマンスの問題や機能の停止、さらにはデータベース停止の原因となることがよくあります。