Menjalankan pernyataan SQL menggunakan Cloud SQL Data API

MySQL | PostgreSQL | SQL Server

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 membuat update skema kecil. Anda juga dapat menggunakan Data API untuk mengaktifkan ekstensi PostgreSQL.

Sebelum memulai

Sebelum dapat menjalankan pernyataan SQL di instance, lakukan hal berikut:

Konfigurasi instance untuk autentikasi database IAM.
Tambahkan akun pengguna atau layanan IAM ke instance dan berikan akun tersebut peran atau izin yang diperlukan untuk menjalankan pernyataan SQL.

Peran atau izin yang diperlukan

Secara default, akun pengguna atau layanan dengan salah satu peran berikut memiliki izin untuk menjalankan pernyataan SQL di 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.

Konsol

Di Google Cloud Konsol, buka halaman Instance Cloud SQL.

Buka Instance Cloud SQL
Untuk membuka halaman Ringkasan instance, klik nama instance.
Dari menu navigasi SQL, pilih Koneksi.
Klik tab Networking.
Centang kotak Izinkan Data API.
Klik Simpan.

gcloud

Untuk mengaktifkan akses Data API di 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 flag --data-api-access=DISALLOW_DATA_API:

gcloud sql instances patch INSTANCE_NAME --data-api-access=DISALLOW_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 di instance menggunakan gcloud CLI, gunakan perintah gcloud sql instances execute-sql:

gcloud 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 dijalankan. Jika pernyataan berisi spasi atau karakter khusus shell, pernyataan tersebut harus diapit tanda kutip.
PARTIAL_RESULT_MODE: opsional. 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 flag --project=PROJECT_ID jika diperlukan.

Terraform

Anda dapat menggunakan Data API di Terraform untuk menyediakan resource dalam database seperti database, tabel, ekstensi, pengguna, dan pemberian hak istimewa, tanpa terhubung ke instance secara manual. Untuk menjalankan skrip SQL di Terraform, gunakan google_sql_provision_script resource Terraform.

resource "google_sql_database_instance" "instance" {
  name             = "my-instance"
  database_version = "POSTGRES_17"

  settings {
    tier            = "db-perf-optimized-N-2"
    data_api_access = "ALLOW_DATA_API"  # This allows the use of Data API.
    database_flags {
      name  = "cloudsql.iam_authentication"
      value = "on"
    }
  }
}

/*
 * Create a database user for your account and grant roles so it has privilege to
 * access the database. Set the type to CLOUD_IAM_USER for huamn account or
 * CLOUD_IAM_SERVICE_ACCOUNT for service account. If a service account is used
 * and the instance is Postgres, trim the ".gserviceaccount.com"
 * suffix to avoid exceeding the username length limit.
*/
resource "google_sql_user" "iam_user" {
  name     = "account-used-to-apply-this-config@example.com"
  instance = google_sql_database_instance.instance.name
  type     = "CLOUD_IAM_USER"

  # Roles granted to the user. Smaller roles are preferred, if exist.
  database_roles = ["cloudsqlsuperuser"]
}

resource "google_sql_database" "database" {
  name     = "my-database"
  instance = google_sql_database_instance.instance.name
}

resource "google_sql_provision_script" "script" {
  # You can inline the script or import from a file like script  = file("${path.module}/script.sql")
  # When modified, the whole script will be executed again. It's recommended to
  # make the script idempotent with patterns like create if not exists ... or
  # if not exists (select ...) then ... end if.
  script  = "CREATE TABLE IF NOT EXISTS table1 ( col VARCHAR(16) NOT NULL );"

  instance = google_sql_database_instance.instance.name
  database = google_sql_database.database.name
  description = "sql script to create tables"

  # The identity account used to apply your Terraform config must exist as an
  # IAM user or IAM service account in the instance. Terraform connects to the
  # instance via IAM database authentication to execute the script.
  depends_on = [google_sql_user.iam_user]
}

Menerapkan perubahan

Untuk menerapkan konfigurasi Terraform di Google Cloud project, selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

Luncurkan Cloud Shell.
Tetapkan project default tempat Anda ingin menerapkan konfigurasi Terraform. Google Cloud

Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

Salin kode contoh ke dalam main.tf yang baru dibuat.

Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.
Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
Simpan perubahan Anda.
Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori.
```
terraform init
```
Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade:
```
terraform init -upgrade
```

Menerapkan perubahan

Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan:
```
terraform plan
```
Koreksi konfigurasi jika diperlukan.
Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:
```
terraform apply
```
Tunggu hingga Terraform menampilkan pesan "Apply complete!".
Buka project Anda Google Cloud untuk melihat hasilnya. Di Google Cloud Konsol, buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Menghapus perubahan

Menghapus resource google_sql_provision_script tidak akan menghapus resource dalam database yang dibuatnya. Untuk menghapusnya, Anda dapat secara eksplisit menambahkan pernyataan dalam skrip seperti drop ... if exists, lalu menerapkan perubahan.

REST

Untuk menjalankan pernyataan SQL terhadap database di 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"
  "autoIamAuthn": true
}

Lakukan penggantian berikut:

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

Mengubah perilaku pemotongan

Anda dapat mengontrol cara menangani hasil besar saat menjalankan SQL.

Sertakan kolom "partialResultMode" dalam permintaan. Kolom ini menerima nilai berikut:
- FAIL_PARTIAL_RESULT: Menampilkan error jika hasil melebihi 10 MB atau jika hanya hasil sebagian yang dapat diambil. Jangan menampilkan hasilnya.
- ALLOW_PARTIAL_RESULT: Menampilkan hasil yang dipangkas dan menetapkan partial_result ke benar (true) jika hasil melebihi 10 MB atau jika hanya hasil sebagian 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 ditetapkan ke ALLOW_PARTIAL_RESULT, jika tidak, error akan ditampilkan.
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 "At most 10 concurrent queries may be run on this instance. Try again later." atau "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.
Data API dapat diblokir sementara untuk tujuan integritas data saat operasi pemeliharaan tertentu sedang berlangsung di instance. Coba lagi nanti jika hal ini terjadi.
Skrip SQL dan respons eksekusinya mungkin transit melalui lokasi perantara antara klien Anda dan lokasi instance target. Oleh karena itu, permintaan akan gagal dengan error "not supported for instances in certain Assured Workloads control packages folders" untuk project Assured Workloads tertentu dan untuk project dengan constraints/sql.restrictNoncompliantResourceCreation yang diterapkan secara manual.

Menjalankan pernyataan SQL menggunakan Cloud SQL Data API Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Peran atau izin yang diperlukan

Mengaktifkan atau menonaktifkan Data API

Konsol

gcloud

Menjalankan pernyataan SQL

gcloud

Terraform

Menerapkan perubahan

Menyiapkan Cloud Shell

Menyiapkan direktori

Menerapkan perubahan

Menghapus perubahan

REST

Mengubah perilaku pemotongan

Batasan

Menjalankan pernyataan SQL menggunakan Cloud SQL Data API