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 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:

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

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.

Konsol

Di Konsol Google Cloud , 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 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=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 pada 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 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.

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 resource Terraform google_sql_provision_script.

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 project, selesaikan langkah-langkah di bagian berikut. Google Cloud

Menyiapkan Cloud Shell

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

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 Google Cloud project Anda untuk melihat hasilnya. Di konsol Google Cloud , 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 menambahkan pernyataan secara eksplisit dalam skrip seperti drop ... if exists, lalu menerapkan perubahan.

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"
  "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 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 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 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 "Paling banyak 10 kueri serentak yang dapat dijalankan di instance ini. Coba lagi nanti" atau "Maksimum pembacaan serentak 10 tercapai".
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.
Data API belum menjamin residensi data. Permintaan akan gagal dengan error "tidak didukung untuk instance di folder paket kontrol Assured Workloads tertentu" 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