Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

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 pengolahan 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.

Sebelum memulai

Sebelum dapat menjalankan pernyataan SQL di instance, lakukan langkah-langkah berikut.

Mengonfigurasi pengguna database

Data API perlu melakukan autentikasi sebagai pengguna database untuk menjalankan pernyataan SQL.

Untuk melakukan autentikasi sebagai pengguna bawaan menggunakan sandi, lakukan hal berikut:

Buat akun pengguna dengan sandi yang tidak kosong. Anda juga dapat menggunakan pengguna default sqlserver.
Berikan peran atau hak istimewa yang diperlukan kepada akun untuk menjalankan pernyataan SQL. Jika pengguna bukan sqlserver, berikan peran db_owner kepada pengguna.
Gunakan Secret Manager untuk membuat secret regional guna menyimpan sandi. Untuk keamanan, Data API meminta nama resource secret, bukan sandi dalam permintaan API. Secret regional harus disimpan di region yang sama dengan instance Cloud SQL Anda. Secret yang dibuat menggunakan endpoint global Secret Manager tidak didukung meskipun disimpan di region yang sama.
Sebagai praktik terbaik, tentukan IAM kondisi untuk mengizinkan pengguna mengakses secret tertentu, tetapi tidak mengakses secret lain dalam project.

Peran atau izin yang diperlukan

Secara default, akun pengguna atau akun 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.

Melakukan autentikasi menggunakan sandi

Anda dapat menjalankan pernyataan SQL menggunakan autentikasi sandi bawaan, jika sandi disimpan sebagai secret regional dengan Secret Manager di region yang sama dengan instance Cloud SQL.

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 \
--user=USER \
--password-secret-version=PASSWORD_SECRET_VERSION \
--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.
USER: pengguna database yang akan diautentikasi.
PASSWORD_SECRET_VERSION: nama resource secret Secret Manager yang menyimpan sandi untuk pengguna database. Secret harus berupa a secret regional dan disimpan di region yang sama dengan instance Cloud SQL. Format nama resource yang diharapkan adalah projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}.
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.

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_user" "built_in_user" {
  name     = "tf-user"
  host     = "%"  # Don't set this field for PostgreSQL and SQL Server.
  instance = google_sql_database_instance.instance.name
  password = "changeme"
  type     = "BUILT_IN"
}

# Create a regional secret. Global secrets are not supported even if
# located in one region only.
resource "google_secret_manager_regional_secret" "secret" {
  secret_id = "db-password"

  # Use the same region as the Cloud SQL instance.
  location = "us-central1"
}

resource "google_secret_manager_regional_secret_version" "secret_version" {
  secret = google_secret_manager_regional_secret.secret.id
  secret_data = "changeme"
}

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"
  user = google_sql_user.built_in_user.name

  # The location should be the same as the Cloud SQL instance's location.
  password_secret_version = "projects/my-project/locations/us-central1/secrets/db-password/versions/latest"

  # The built-in database user and password secret version must be created
  # first. Cloud SQL will retrieve password from Secret Manager
  # and connect to this user account to execute your script.
  depends_on = [
    google_sql_user.built_in_user,
    google_secret_manager_regional_secret_version.secret_version
  ]
}

Menerapkan perubahan

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

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 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 menambahkan pernyataan secara eksplisit 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",
  "user": "USER",
  "passwordSecretVersion": "PASSWORD_SECRET_VERSION",
  "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 dijalankan.
USER: pengguna database yang akan diautentikasi.
PASSWORD_SECRET_VERSION: nama resource secret Secret Manager yang menyimpan sandi untuk pengguna database. Secret harus berupa a secret regional dan disimpan di region yang sama dengan instance Cloud SQL. Format nama resource yang diharapkan adalah projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}.
PARTIAL_RESULT_MODE: opsional. Mengontrol cara API merespons saat hasil melebihi 10 MB. Dapat berupa FAIL_PARTIAL_RESULT, ALLOW_PARTIAL_RESULT, atau PARTIAL_RESULT_MODE_UNSPECIFIED. Lihat Mengubah perilaku pemotongan.

Mengubah perilaku pemotongan

Anda dapat mengontrol cara menangani hasil besar saat menjalankan SQL, dengan menyertakan kolom "partialResultMode" dalam permintaan. Kolom ini menerima nilai berikut:

FAIL_PARTIAL_RESULT: Default. Menampilkan error jika hasilnya melebihi 10 MB atau jika hanya hasil sebagian yang dapat diambil. Jangan menampilkan hasilnya.
ALLOW_PARTIAL_RESULT: Menampilkan hasil yang dipotong dan menetapkan partial_result ke benar (true) jika hasilnya melebihi 10 MB atau jika hanya hasil sebagian yang dapat diambil karena error. Jangan menampilkan error.
PARTIAL_RESULT_MODE_UNSPECIFIED: Mode tidak ditentukan, yang secara efektif sama dengan FAIL_PARTIAL_RESULT.

Batasan

Batas ukuran untuk respons adalah 10 MB. Hasil yang melebihi ukuran ini akan dipotong 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 SQL Server 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 LOCK_TIMEOUT tidak didukung.
Cloud SQL membatasi jumlah permintaan executeSql serentak per instance untuk mencegah kelebihan beban. Jika batas tercapai, permintaan berikutnya akan gagal dan menampilkan salah satu error berikut:
- At most 'x' concurrent queries may be run on this instance. Try again later.
- Maximum concurrent reads 'x' reached.
Batas (x) adalah 5 kueri untuk instance dengan memori total kurang dari 10 GB, dan 10 kueri untuk instance dengan memori total minimal 10 GB.
Setiap respons dapat berisi maksimum 10 pesan atau peringatan database.
Jika ada error sintaksis atau eksekusi pernyataan, tidak ada hasil yang ditampilkan.
Data API tidak dapat melakukan autentikasi sebagai pengguna bawaan dengan sandi kosong.
Data API dapat diblokir sementara untuk tujuan integritas data saat operasi pemeliharaan tertentu sedang berlangsung di instance. Coba lagi nanti jika hal ini terjadi.

Perintah GO tidak didukung. Perintah ini digunakan dalam utilitas Microsoft SQL Server untuk menunjukkan bahwa batch pernyataan telah berakhir dan dapat dikirim ke SQL Server.
Jika kueri menyertakan kolom biner, Data API tidak dapat menampilkannya. Sebagai gantinya, konversi nilai biner menjadi string.

Misalnya, ganti:
```
SELECT my_binary_column from my_table2;
```
dengan:
```
SELECT CONVERT(NVARCHAR(4000), my_binary_column, 1) from my_table2;
```
Saat menjalankan beberapa kueri dan salah satunya gagal, error pertama yang ditemui akan ditampilkan. Beberapa pernyataan dalam batch sebelum error mungkin telah berhasil dijalankan. Anda dapat menggabungkan beberapa kueri dalam pernyataan transaction untuk mencegah masalah ini:
```
BEGIN TRANSACTION
    YOUR_SQL_STATEMENTS
COMMIT;
```
Ganti kode berikut:
- YOUR_SQL_STATEMENTS: pernyataan yang ingin Anda jalankan sebagai bagian dari kueri ini

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

Mengonfigurasi pengguna database

Peran atau izin yang diperlukan

Mengaktifkan atau menonaktifkan Data API

Konsol

gcloud

Menjalankan pernyataan SQL

Melakukan autentikasi menggunakan sandi

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