| list_instances |
Mencantumkan semua instance Cloud SQL dalam project.
|
| get_instance |
Mendapatkan detail instance Cloud SQL.
|
| create_instance |
Memulai pembuatan instance Cloud SQL.
Kecuali jika ditentukan lain, instance yang baru dibuat akan menggunakan konfigurasi instance default lingkungan pengembangan. Berikut adalah konfigurasi default untuk instance di lingkungan pengembangan:
{
"tier": "db-perf-optimized-N-2",
"data_disk_size_gb": 100,
"region": "us-central1",
"database_version": "POSTGRES_18",
"edition": "ENTERPRISE_PLUS",
"availability_type": "ZONAL",
"tags": [{"environment": "dev"}]
}
Konfigurasi berikut direkomendasikan untuk instance di lingkungan produksi:
{
"tier": "db-perf-optimized-N-8",
"data_disk_size_gb": 250,
"region": "us-central1",
"database_version": "POSTGRES_18",
"edition": "ENTERPRISE_PLUS",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
Konfigurasi instance berikut direkomendasikan untuk SQL Server:
{
"tier": "db-perf-optimized-N-8",
"data_disk_size_gb": 250,
"region": "us-central1",
"database_version": "SQLSERVER_2022_STANDARD",
"edition": "ENTERPRISE",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
|
| execute_sql |
Jalankan pernyataan SQL yang valid, termasuk pernyataan bahasa definisi data (DDL), bahasa kontrol data (DCL), bahasa kueri data (DQL), atau bahasa pengolahan data (DML), pada instance Cloud SQL. Untuk mendukung alat execute_sql, instance Cloud SQL harus memenuhi persyaratan berikut:
- Nilai
data_api_access harus ditetapkan ke ALLOW_DATA_API.
- Untuk pengguna built_in, password_secret_version harus disetel.
- Jika tidak, untuk pengguna IAM, untuk instance MySQL, tanda database
cloudsql_iam_authentication harus disetel ke on. Untuk instance PostgreSQL, tanda database cloudsql.iam_authentication harus disetel ke on.
- Setelah menggunakan alat
create_instance untuk membuat instance, Anda dapat menggunakan alat create_user untuk membuat akun pengguna IAM bagi pengguna yang saat ini login ke project.
Alat execute_sql memiliki batasan berikut:
- Jika pernyataan SQL menampilkan respons yang lebih besar dari 10 MB, respons akan dipangkas.
- Alat
execute_sql memiliki waktu tunggu default 30 detik. Jika kueri berjalan lebih dari 30 detik, alat akan menampilkan error DEADLINE_EXCEEDED.
- Alat
execute_sql tidak didukung untuk SQL Server.
Jika Anda menerima error yang mirip dengan "IAM authentication is not enabled for the instance", Anda dapat menggunakan alat get_instance untuk memeriksa nilai flag autentikasi database IAM untuk instance tersebut. Jika Anda menerima error seperti "The instance doesn't allow using executeSql to access this instance", Anda dapat menggunakan alat get_instance untuk memeriksa setelan data_api_access. Saat Anda menerima error autentikasi:
- Periksa apakah akun pengguna yang saat ini login ada sebagai pengguna IAM di instance menggunakan alat
list_users.
- Jika akun pengguna IAM tidak ada, gunakan alat
create_user untuk membuat akun pengguna IAM bagi pengguna yang login.
- Jika pengguna yang saat ini login tidak memiliki peran pengguna database yang tepat, Anda dapat menggunakan alat
update_user untuk memberikan peran database kepada pengguna. Misalnya, peran cloudsqlsuperuser dapat memberikan banyak izin yang diperlukan kepada pengguna IAM.
Periksa apakah pengguna yang saat ini login telah diberi izin IAM yang benar untuk project tersebut. Anda dapat menggunakan perintah gcloud projects get-iam-policy [PROJECT_ID] untuk memeriksa apakah pengguna telah diberi peran atau izin IAM yang tepat untuk project.
- Pengguna harus memiliki izin
cloudsql.instance.login untuk melakukan autentikasi database IAM otomatis.
- Pengguna harus memiliki izin
cloudsql.instances.executeSql untuk menjalankan pernyataan SQL menggunakan alat execute_sql atau executeSql API.
- Peran IAM umum yang berisi izin yang diperlukan: Pengguna Instance Cloud SQL (
roles/cloudsql.instanceUser) atau Admin Cloud SQL (roles/cloudsql.admin)
Saat menerima ExecuteSqlResponse, selalu periksa kolom message dan status dalam isi respons. Kode status HTTP yang berhasil tidak menjamin keberhasilan penuh semua pernyataan SQL. Kolom message dan status akan menunjukkan apakah ada error atau peringatan parsial selama eksekusi pernyataan SQL.
|
| execute_sql_readonly |
Jalankan pernyataan SQL hanya baca yang valid pada instance Cloud SQL. Untuk mendukung alat execute_sql_readonly, instance Cloud SQL harus memenuhi persyaratan berikut:
- Nilai
data_api_access harus ditetapkan ke ALLOW_DATA_API.
- Untuk instance MySQL, flag database
cloudsql_iam_authentication harus disetel ke on. Untuk instance PostgreSQL, tanda database cloudsql.iam_authentication harus disetel ke on.
- Akun pengguna IAM atau akun layanan IAM (
CLOUD_IAM_USER atau CLOUD_IAM_SERVICE_ACCOUNT) diperlukan untuk memanggil alat execute_sql_readonly. Alat ini menjalankan pernyataan SQL menggunakan hak istimewa pengguna database yang login dengan autentikasi database IAM.
Setelah menggunakan alat create_instance untuk membuat instance, Anda dapat menggunakan alat create_user untuk membuat akun pengguna IAM bagi pengguna yang saat ini login ke project. Alat execute_sql_readonly memiliki batasan berikut:
- Jika pernyataan SQL menampilkan respons yang lebih besar dari 10 MB, respons akan dipangkas.
- Alat ini memiliki waktu tunggu default 30 detik. Jika kueri berjalan lebih dari 30 detik, alat akan menampilkan error
DEADLINE_EXCEEDED.
- Alat ini tidak didukung untuk SQL Server.
Jika Anda menerima error yang mirip dengan "IAM authentication is not enabled for the instance", Anda dapat menggunakan alat get_instance untuk memeriksa nilai flag autentikasi database IAM untuk instance tersebut. Jika Anda menerima error seperti "The instance doesn't allow using executeSql to access this instance", Anda dapat menggunakan alat get_instance untuk memeriksa setelan data_api_access. Saat Anda menerima error autentikasi:
- Periksa apakah akun pengguna yang saat ini login ada sebagai pengguna IAM di instance menggunakan alat
list_users.
- Jika akun pengguna IAM tidak ada, gunakan alat
create_user untuk membuat akun pengguna IAM bagi pengguna yang login.
- Jika pengguna yang saat ini login tidak memiliki peran pengguna database yang tepat, Anda dapat menggunakan alat
update_user untuk memberikan peran database kepada pengguna. Misalnya, peran cloudsqlsuperuser dapat memberikan banyak izin yang diperlukan kepada pengguna IAM.
Periksa apakah pengguna yang saat ini login telah diberi izin IAM yang benar untuk project tersebut. Anda dapat menggunakan perintah gcloud projects get-iam-policy [PROJECT_ID] untuk memeriksa apakah pengguna telah diberi peran atau izin IAM yang tepat untuk project.
- Pengguna harus memiliki izin
cloudsql.instance.login untuk melakukan autentikasi database IAM otomatis.
- Pengguna harus memiliki izin
cloudsql.instances.executeSql untuk menjalankan pernyataan SQL menggunakan alat execute_sql_readonly atau executeSql API.
- Peran IAM umum yang berisi izin yang diperlukan: Pengguna Instance Cloud SQL (
roles/cloudsql.instanceUser) atau Admin Cloud SQL (roles/cloudsql.admin)
Saat menerima ExecuteSqlResponse, selalu periksa kolom message dan status dalam isi respons. Kode status HTTP yang berhasil tidak menjamin keberhasilan penuh semua pernyataan SQL. Kolom message dan status akan menunjukkan apakah ada error atau peringatan parsial selama eksekusi pernyataan SQL.
|
| get_operation |
Mendapatkan status operasi yang berjalan lama. Operasi yang berjalan lama dapat memerlukan waktu beberapa menit untuk diselesaikan. Jika operasi memerlukan waktu yang lama, gunakan alat command line untuk menjeda selama 30 detik sebelum memeriksa kembali status operasi.
|
| create_user |
Buat pengguna database untuk instance Cloud SQL.
- Alat ini menampilkan operasi yang berjalan lama. Gunakan alat
get_operation untuk melakukan polling statusnya hingga operasi selesai.
- Saat Anda menggunakan alat
create_user, tentukan jenis pengguna: CLOUD_IAM_USER, CLOUD_IAM_SERVICE_ACCOUNT, atau BUILT_IN.
- Secara default, pengguna yang baru dibuat diberi peran
cloudsqlsuperuser, kecuali jika Anda menentukan peran database lain secara eksplisit dalam permintaan.
- Anda dapat menggunakan pengguna yang baru dibuat dengan alat
execute_sql jika pengguna tersebut adalah pengguna IAM yang saat ini login. Alat execute_sql menjalankan pernyataan SQL menggunakan hak istimewa pengguna database yang login menggunakan autentikasi database IAM.
Alat create_user memiliki batasan berikut:
- Untuk membuat pengguna bawaan dengan sandi, gunakan kolom
password_secret_version untuk memberikan sandi menggunakan Google Cloud Secret Manager. Nilai password_secret_version harus berupa nama resource versi rahasia, seperti projects/12345/locations/us-central1/secrets/my-password-secret/versions/1 atau projects/12345/locations/us-central1/secrets/my-password-secret/versions/latest. Pemanggil harus memiliki izin secretmanager.secretVersions.access pada versi rahasia.
- Alat
create_user tidak mendukung pembuatan pengguna untuk SQL Server.
Untuk membuat pengguna IAM di PostgreSQL:
- Nama pengguna database harus berupa alamat email pengguna IAM dan semua huruf kecil. Misalnya, untuk membuat pengguna bagi pengguna IAM PostgreSQL
example-user@example.com, Anda dapat menggunakan permintaan berikut:
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance":"test-instance",
"project": "test-project"
}
Nama pengguna database yang dibuat untuk pengguna IAM adalah example-user@example.com. Untuk membuat akun layanan IAM di PostgreSQL:
- Nama pengguna database harus dibuat tanpa akhiran
.gserviceaccount.com meskipun alamat email lengkap untuk akun tersebut adalah service-account-name@project-id.iam.gserviceaccount.com. Misalnya, untuk membuat akun layanan IAM untuk PostgreSQL, Anda dapat menggunakan format permintaan berikut:
{
"name": "test@test-project.iam",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
Nama pengguna database yang dibuat untuk akun layanan IAM adalah test@test-project.iam. Untuk membuat akun pengguna IAM atau akun layanan IAM di MySQL:
- Saat menyimpan nama pengguna, Cloud SQL untuk MySQL akan memotong @ dan nama domain dari alamat email pengguna atau akun layanan. Misalnya,
example-user@example.com menjadi example-user.
- Oleh karena itu, Anda tidak dapat menambahkan dua pengguna IAM atau akun layanan dengan nama pengguna yang sama tetapi nama domain yang berbeda ke instance Cloud SQL yang sama.
- Misalnya, untuk membuat pengguna bagi pengguna IAM MySQL
example-user@example.com, gunakan permintaan berikut:
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance": "test-instance",
"project": "test-project"
}
Nama pengguna database yang dibuat untuk pengguna IAM adalah example-user.
- Misalnya, untuk membuat akun layanan IAM MySQL
service-account-name@project-id.iam.gserviceaccount.com, gunakan permintaan berikut:
{
"name": "service-account-name@project-id.iam.gserviceaccount.com",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
Nama pengguna database yang dibuat untuk akun layanan IAM adalah service-account-name.
|
| update_user |
Memperbarui pengguna database untuk instance Cloud SQL. Kasus penggunaan umum untuk update_user adalah memberikan peran cloudsqlsuperuser kepada pengguna, yang dapat memberikan banyak izin yang diperlukan kepada pengguna. Alat ini hanya mendukung pembaruan pengguna untuk menetapkan peran database.
- Alat ini menampilkan operasi yang berjalan lama. Gunakan alat
get_operation untuk melakukan polling statusnya hingga operasi selesai.
- Sebelum memanggil alat
update_user, selalu periksa konfigurasi pengguna yang ada, seperti jenis pengguna dengan alat list_users.
- Sebagai kasus khusus untuk MySQL, jika alat
list_users menampilkan alamat email lengkap untuk kolom iamEmail, misalnya {name=test-account,
iamEmail=test-account@project-id.iam.gserviceaccount.com}, maka dalam permintaan update_user, gunakan alamat email lengkap di kolom iamEmail dalam kolom name permintaan alat Anda. Misalnya, name=test-account@project-id.iam.gserviceaccount.com.
Parameter utama untuk memperbarui peran pengguna:
database_roles: Daftar peran database yang akan ditetapkan kepada pengguna.revokeExistingRoles: Kolom boolean (default: false) yang mengontrol cara penanganan peran yang ada. Cara kerja pembaruan peran:
Jika revokeExistingRoles bernilai benar:
- Semua peran yang sudah ada yang diberikan kepada pengguna tetapi TIDAK ada dalam daftar
database_roles yang diberikan akan DICABUT.
- Mencabut hanya berlaku untuk peran non-sistem. Peran sistem seperti
cloudsqliamuser, dll. tidak akan dicabut.
- Semua peran dalam daftar
database_roles yang BELUM dimiliki pengguna akan DIBERIKAN.
- Jika
database_roles kosong, maka SEMUA peran non-sistem yang ada akan dibatalkan.
Jika revokeExistingRoles salah (default):
- Semua peran dalam daftar
database_roles yang BELUM dimiliki pengguna akan DIBERIKAN.
- Peran yang ada yang TIDAK ada dalam daftar
database_roles akan TETAP ADA.
- Jika
database_roles kosong, tidak ada perubahan pada peran pengguna.
Contoh:
|
| clone_instance |
Buat instance Cloud SQL sebagai clone instance sumber.
- Alat ini menampilkan operasi yang berjalan lama. Gunakan alat
get_operation untuk melakukan polling statusnya hingga operasi selesai.
- Operasi clone dapat memerlukan waktu beberapa menit. Gunakan alat command line untuk menjeda selama 30 detik sebelum memeriksa ulang status.
|
| update_instance |
Memperbarui sebagian setelan konfigurasi instance Cloud SQL.
- Alat ini menampilkan operasi yang berjalan lama. Gunakan alat
get_operation untuk melakukan polling statusnya hingga operasi selesai.
- Beberapa operasi update, seperti mengubah upgrade edisi atau tingkat instance, dll. dapat menyebabkan instance dimulai ulang, sehingga terjadi periode nonaktif. Sebelum Anda melanjutkan operasi tersebut, dapatkan konfirmasi dari pengguna.
|
| list_users |
Mencantumkan semua pengguna database untuk instance Cloud SQL.
|
| create_backup |
Membuat cadangan pada instance Cloud SQL. Selalu isi kolom project dan instance pada permintaan. Lokasi (region) dan deskripsi cadangan juga dapat diberikan secara opsional, dan dalam hal ini kolom permintaan yang sesuai juga harus diisi.
|
| restore_backup |
Memulihkan cadangan ke instance Cloud SQL. target_instance dan target_project harus diberikan dan diisi dalam permintaan. ID cadangan dapat diberikan dengan beberapa cara:
- backup_run_id (yang merupakan bilangan bulat).
- URI cadangan dengan format
projects/{project-id}/backups/{backup-uid}.
- URI cadangan dengan format
projects/{project-id}/locations/{location}/backupVaults/{backupvault}/dataSources/{datasource}/backups/{backup-uid}.
Gunakan ID untuk mengisi kolom backup_id dalam permintaan. source_project harus diisi dalam permintaan. Jika ID adalah backup_run_id, source_project akan diberikan. Jika ID adalah URI cadangan, source_project mungkin perlu diekstrak dari URI. Jangan salah mengartikan source_project yang diekstrak dengan target_project, yang akan diberikan dengan cara lain. Selain itu, jika ID adalah backup_run_id, source_instance harus diberikan dan diisi dalam permintaan. Jangan mencoba membuat instance sebelum pemulihan, pemulihan itu sendiri akan membuat instance jika diperlukan. Konfirmasi parameter dengan pengguna sebelum menjalankan pemulihan.
|
| import_data |
Mengimpor data ke instance Cloud SQL. Jika file tidak dimulai dengan gs://, maka diasumsikan bahwa file disimpan secara lokal. Jika file bersifat lokal, file tersebut harus diupload ke Cloud Storage sebelum Anda dapat melakukan panggilan import_data yang sebenarnya. Untuk mengupload file ke Cloud Storage, Anda dapat menggunakan perintah gcloud atau gsutil. Sebelum mengupload file ke Cloud Storage, pertimbangkan apakah Anda ingin menggunakan bucket yang ada atau membuat bucket baru dalam project yang disediakan. Setelah file diupload ke Cloud Storage, akun layanan instance harus memiliki izin yang memadai untuk membaca file yang diupload dari bucket Cloud Storage. Hal ini dapat dilakukan sebagai berikut:
- Gunakan alat
get_instance untuk mendapatkan alamat email akun layanan instance. Dari output alat, dapatkan nilai kolom serviceAccountEmailAddress.
- Berikan peran
storage.objectAdmin kepada akun layanan instance di bucket Cloud Storage yang disediakan. Gunakan perintah seperti gcloud storage buckets
add-iam-policy-binding atau permintaan ke Cloud Storage API. Mungkin perlu waktu dua hingga tujuh menit atau lebih agar peran diberikan dan izin disebarkan ke akun layanan di Cloud Storage. Jika Anda mengalami error izin setelah memperbarui kebijakan IAM, tunggu beberapa menit, lalu coba lagi.
Setelah izin diberikan, Anda dapat mengimpor data. Sebaiknya biarkan parameter opsional kosong dan gunakan default sistem. Jenis file biasanya dapat ditentukan oleh ekstensi file. Misalnya, jika file adalah file SQL, .sql atau .csv untuk file CSV. Berikut adalah contoh SQL importContext untuk MySQL.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL"
}
Tidak ada parameter database untuk MySQL karena nama database diharapkan ada dalam file SQL. Tentukan hanya satu URI. Tidak ada kolom lain yang diperlukan selain importContext. Untuk PostgreSQL, kolom database wajib diisi. Berikut adalah contoh importContext PostgreSQL dengan kolom database yang ditentukan.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL",
"database": "sample-db"
}
Alat import_data menampilkan operasi yang berjalan lama. Gunakan alat get_operation untuk melakukan polling statusnya hingga operasi selesai.
|
| postgres_upgrade_precheck |
Memeriksa apakah instance Cloud SQL untuk PostgreSQL siap untuk upgrade versi utama ke versi target yang ditentukan. target_database_version HARUS diberikan dalam permintaan (misalnya, POSTGRES_15).
Alat ini membantu mengidentifikasi potensi masalah sebelum mencoba upgrade sebenarnya, sehingga mengurangi risiko kegagalan atau periode nonaktif. Alat ini hanya didukung untuk instance utama PostgreSQL dan tidak berjalan di replika baca. Pemeriksaan awal biasanya mengevaluasi:
- Kompatibilitas skema database dengan versi target.
- Batasan dan fitur yang tidak didukung Cloud SQL.
- Batasan resource instance (misalnya, jumlah relasi).
- Kompatibilitas setelan dan ekstensi database saat ini.
- Kondisi dan kesiapan instance secara keseluruhan.
Alat ini menampilkan operasi yang berjalan lama. Gunakan alat get_operation dengan nama operasi yang ditampilkan oleh panggilan ini untuk melakukan polling statusnya. PENTING: Setelah status operasi adalah SELESAI, hasil pra-pemeriksaan mendetail tersedia dalam resource Operation. Anda harus memeriksa respons dari get_operation. Temuan ini berada di kolom pre_check_major_version_upgrade_context.pre_check_response. Temuan disusun, yang menunjukkan:
- INFO: Informasi umum.
- PERINGATAN: Potensi masalah yang tidak menghalangi upgrade, tetapi harus ditinjau.
- ERROR: Masalah penting yang HARUS diselesaikan sebelum mencoba upgrade.
Setiap temuan harus menyertakan pesan dan tindakan yang diperlukan. Menangani masalah yang dilaporkan sangat penting sebelum melanjutkan upgrade versi utama. Jika pre_check_response kosong atau tidak ada, hal ini menunjukkan bahwa tidak ada masalah yang teridentifikasi selama pra-pemeriksaan. Menjalankan pemeriksaan awal ini tidak akan memengaruhi ketersediaan instance.
|
