Menjalankan pernyataan SQL menggunakan Cloud SQL Data API

Halaman ini menjelaskan cara menjalankan pernyataan SQL terhadap database di instance Cloud SQL menggunakan Data API. Dengan Data API, Anda menggunakan Cloud SQL Admin API dan gcloud CLI untuk menjalankan pernyataan SQL di instance mana pun tempat Anda mengaktifkan akses Data API.

Anda dapat menggunakan Data API dengan instance yang menggunakan alamat IP publik, akses layanan pribadi, atau Private Service Connect. Data API mendukung semua jenis pernyataan SQL, termasuk bahasa manipulasi data (DML), bahasa definisi data (DDL), dan bahasa kueri data (DQL). Data API cocok untuk menjalankan pernyataan administratif kecil dan cepat, seperti membuat peran atau pengguna database dan melakukan pembaruan skema kecil. Anda juga dapat menggunakan Data API untuk mengaktifkan ekstensi PostgreSQL.

Sebelum memulai

Sebelum Anda dapat menjalankan pernyataan SQL pada instance, lakukan hal berikut:

Peran atau izin yang diperlukan

Secara default, akun pengguna atau akun layanan dengan salah satu peran berikut memiliki izin untuk menjalankan pernyataan SQL pada instance Cloud SQL (cloudsql.instances.executesql):

  • Cloud SQL Admin (roles/cloudsql.admin)
  • Cloud SQL Instance User (roles/cloudsql.instanceUser)
  • Cloud SQL Studio User (roles/cloudsql.studioUser)

Anda juga dapat menentukan peran khusus IAM untuk akun pengguna atau akun layanan yang menyertakan izin cloudsql.instances.executesql. Izin ini didukung dalam peran khusus IAM.

Mengaktifkan atau menonaktifkan Data API

Untuk menggunakan Data API, Anda harus mengaktifkannya untuk setiap instance. Anda dapat menonaktifkan Data API kapan saja.

gcloud

Untuk mengaktifkan akses Data API pada instance, gunakan perintah gcloud sql instances patch dengan flag --data-api-access=ALLOW_DATA_API:

gcloud sql instances patch INSTANCE_NAME --data-api-access=ALLOW_DATA_API

Untuk menonaktifkan akses Data API, gunakan tanda --data-api-access=DENY_DATA_API:

gcloud sql instances patch INSTANCE_NAME --data-api-access=DENY_DATA_API

Ganti INSTANCE_NAME dengan nama instance tempat Data API akan diaktifkan atau dinonaktifkan.

Menjalankan pernyataan SQL

Anda dapat menjalankan pernyataan SQL terhadap database di instance Cloud SQL menggunakan gcloud CLI atau REST API.

gcloud

Untuk menjalankan pernyataan SQL terhadap database pada instance menggunakan gcloud CLI, gunakan perintah 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

Lakukan penggantian berikut:

  • INSTANCE_NAME: nama instance.
  • DATABASE_NAME: nama database dalam instance.
  • SQL_STATEMENT: pernyataan SQL yang akan dieksekusi. Jika pernyataan berisi spasi atau karakter khusus shell, pernyataan harus diberi tanda kutip.
  • PARTIAL_RESULT_MODE: optional. Mengontrol cara merespons saat hasil tidak lengkap. Dapat berupa ALLOW_PARTIAL_RESULT, FAIL_PARTIAL_RESULT, atau PARTIAL_RESULT_MODE_UNSPECIFIED. Lihat Mengubah perilaku pemotongan.

Anda juga dapat menyertakan tanda --project=PROJECT_ID jika diperlukan.

REST

Untuk menjalankan pernyataan SQL terhadap database pada instance menggunakan REST API, kirim permintaan POST ke endpoint executeSql:

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/executeSql

Isi permintaan harus berisi nama database dan pernyataan SQL:

{
  "database": "DATABASE_NAME",
  "sqlStatement": "SQL_STATEMENT",
  "partialResultMode": "PARTIAL_RESULT_MODE"
}

Lakukan penggantian berikut:

  • PROJECT_ID: project ID Anda.
  • INSTANCE_NAME: nama instance.
  • DATABASE_NAME: nama database dalam instance.
  • SQL_STATEMENT: pernyataan SQL yang akan dieksekusi.
  • PARTIAL_RESULT_MODE: optional. Mengontrol cara API merespons saat hasilnya melebihi 10 MB. Dapat berupa FAIL_PARTIAL_RESULT atau ALLOW_PARTIAL_RESULT. Lihat Mengubah perilaku pemotongan.

Mengubah perilaku pemotongan

Anda dapat mengontrol cara hasil besar ditangani saat menjalankan SQL.

  • Sertakan kolom "partialResultMode" dalam permintaan. Kolom ini menerima nilai berikut:
    • FAIL_PARTIAL_RESULT: Menampilkan error jika hasilnya melebihi 10 MB atau jika hanya sebagian hasil yang dapat diambil. Jangan menampilkan hasil.
    • ALLOW_PARTIAL_RESULT: Menampilkan hasil yang dipangkas dan menyetel partial_result ke benar (true) jika hasil melebihi 10 MB atau jika hanya sebagian hasil yang dapat diambil karena error. Jangan menampilkan error.

Batasan

  • Batas ukuran untuk respons adalah 10 MB. Hasil yang melebihi ukuran ini akan dipangkas jika partialResultMode disetel ke ALLOW_PARTIAL_RESULT, jika tidak, error akan muncul.
  • Permintaan dibatasi hingga 0,5 MB.
  • Anda hanya dapat menjalankan pernyataan SQL untuk instance Cloud SQL untuk PostgreSQL yang sedang berjalan.
  • Cloud SQL tidak mendukung penggunaan Data API dengan instance yang disiapkan untuk replikasi server eksternal.
  • Permintaan yang memerlukan waktu lebih dari 30 detik akan dibatalkan. Menetapkan waktu tunggu pernyataan yang lebih tinggi menggunakan SET STATEMENT_TIMEOUT tidak didukung.
  • Cloud SQL membatasi jumlah permintaan executeSql serentak hingga 10 per instance untuk setiap pengguna. Jika batas ini tercapai, permintaan berikutnya akan gagal dengan pesan "Maximum concurrent reads 10 reached".
  • Setiap respons dapat berisi maksimum 10 pesan atau peringatan database.
  • Jika ada error sintaks atau eksekusi pernyataan, tidak ada hasil yang ditampilkan.
  • Pernyataan yang menggunakan banyak memori dapat menyebabkan error kehabisan memori. Untuk mengetahui informasi selengkapnya tentang cara menghindari error ini, lihat Praktik terbaik untuk mengelola penggunaan memori. Instance database yang berjalan dengan pemakaian memori tinggi sering menyebabkan masalah performa, terhenti, atau bahkan periode nonaktif database.