MCP Tools Reference: cloud-sql

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

  1. Periksa apakah akun pengguna yang saat ini login ada sebagai pengguna IAM di instance menggunakan alat list_users.
  2. Jika akun pengguna IAM tidak ada, gunakan alat create_user untuk membuat akun pengguna IAM bagi pengguna yang login.
  3. 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.

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

Contoh berikut menunjukkan cara menggunakan curl untuk memanggil alat MCP execute_sql.

Permintaan Curl 
                  
curl --location 'https://sqladmin.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Skema Input

Instance menjalankan permintaan SQL untuk MCP.

SqlInstancesExecuteSqlMcpRequest

Representasi JSON 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string
}
Kolom
instance

string

Wajib. ID instance database. Ini tidak menyertakan project ID.
project

string

Wajib. Project ID project yang berisi instance.
sqlStatement

string

Wajib. Pernyataan SQL yang akan dijalankan di database. Dapat berupa satu pernyataan atau serangkaian pernyataan yang dipisahkan dengan titik koma.
database

string

Opsional. Nama database tempat pernyataan akan dieksekusi. Untuk Postgres, parameter ini wajib diisi, sedangkan untuk MySQL, parameter ini bersifat opsional. Untuk Postgres, jika kueri Anda tidak dicakup ke database yang ada, seperti mencantumkan database / membuat database baru / memberikan peran, Anda dapat meneruskan nilai default sebagai postgres.

Skema Output

Respons eksekusi pernyataan SQL.

SqlInstancesExecuteSqlResponse

Representasi JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
Kolom
messages[]

object (Message)

Daftar pemberitahuan dan peringatan yang dihasilkan selama eksekusi kueri. Untuk PostgreSQL, hal ini mencakup semua pemberitahuan dan peringatan. Untuk MySQL, hal ini mencakup peringatan yang dihasilkan oleh pernyataan terakhir yang dijalankan. Untuk mengambil semua peringatan untuk kueri multi-pernyataan, SHOW WARNINGS harus dieksekusi setelah setiap pernyataan.
metadata

object (Metadata)

Informasi metadata tambahan terkait eksekusi pernyataan SQL.
results[]

object (QueryResult)

Daftar hasil setelah menjalankan semua pernyataan SQL.
status

object (Status)

Berisi error dari database jika eksekusi SQL gagal.

Pesan

Representasi JSON 
{

  // Union field _message can be only one of the following:
  "message": string
  // End of list of possible types for union field _message.

  // Union field _severity can be only one of the following:
  "severity": string
  // End of list of possible types for union field _severity.
}
Kolom

Kolom union _message.

_message hanya dapat berupa salah satu dari berikut:
message

string

String pesan lengkap. Untuk PostgreSQL, ini adalah string yang diformat yang dapat mencakup tingkat keparahan, kode, dan pesan pemberitahuan/peringatan. Untuk MySQL, ini berisi pesan peringatan.

Kolom union _severity.

_severity hanya dapat berupa salah satu dari berikut:
severity

string

Tingkat keparahan pesan (misalnya, "NOTICE" untuk PostgreSQL, "WARNING" untuk MySQL).

Metadata

Representasi JSON 
{
  "sqlStatementExecutionTime": string
}
Kolom
sqlStatementExecutionTime

string (Duration format)

Waktu yang diperlukan untuk menjalankan pernyataan SQL.

Durasi dalam detik dengan maksimal sembilan digit pecahan, yang diakhiri dengan 's'. Contoh: "3.5s".

Durasi

Representasi JSON 
{
  "seconds": string,
  "nanos": integer
}
Kolom
seconds

string (int64 format)

Detik bertanda dari rentang waktu. Harus dari -315.576.000.000 hingga +315.576.000.000 inklusif. Catatan: batas ini dihitung dari: 60 dtk/mnt * 60 mnt/j * 24 j/h * 365,25 h/thn * 10.000 thn
nanos

integer

Pecahan detik bertanda pada resolusi nanodetik rentang waktu. Durasi kurang dari satu detik ditampilkan dengan kolom seconds 0 dan kolom nanos positif atau negatif. Untuk durasi satu detik atau lebih, nilai non-nol untuk kolom nanos harus memiliki tanda yang sama dengan kolom seconds. Harus dari -999.999.999 hingga +999.999.999 inklusif.

QueryResult

Representasi JSON 
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}
Kolom
columns[]

object (Column)

Daftar kolom yang disertakan dalam hasil. Hal ini juga mencakup jenis data kolom.
rows[]

object (Row)

Baris yang ditampilkan oleh pernyataan SQL.
message

string

Pesan yang terkait dengan hasil eksekusi SQL.
partialResult

boolean

Disetel ke benar (true) jika hasil eksekusi SQL dipangkas karena batas ukuran atau error saat mengambil hasil.
status

object (Status)

Jika hasil dipangkas karena error, detail error tersebut.

Kolom

Representasi JSON 
{
  "name": string,
  "type": string
}
Kolom
name

string

Nama kolom.
type

string

Jenis data kolom.

Baris

Representasi JSON 
{
  "values": [
    {
      object (Value)
    }
  ]
}
Kolom
values[]

object (Value)

Nilai untuk baris.

Nilai

Representasi JSON 
{
  "value": string,
  "nullValue": boolean
}
Kolom
value

string

Nilai sel dalam format string.
nullValue

boolean

Jika nilai sel adalah null, tanda ini akan disetel ke benar (true).

Status

Representasi JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Kolom
code

integer

Kode status, harus berupa nilai enum dari google.rpc.Code.
message

string

Pesan error yang ditampilkan ke developer dan seharusnya dalam bahasa Inggris. Setiap pesan error yang ditampilkan kepada pengguna harus dilokalkan dan dikirim di kolom google.rpc.Status.details, atau dilokalkan oleh klien.
details[]

object

Daftar pesan yang membawa detail error. Ada seperangkat jenis pesan umum untuk digunakan API.

Objek yang berisi kolom tipe arbitrer. Kolom tambahan "@type" berisi URI yang mengidentifikasi jenis. Contoh: { "id": 1234, "@type": "types.example.com/standard/id" }.

Semua

Representasi JSON 
{
  "typeUrl": string,
  "value": string
}
Kolom
typeUrl

string

URL/nama resource yang secara unik mengidentifikasi jenis pesan buffer protokol yang diserialkan. String ini harus berisi setidaknya satu karakter "/". Segmen terakhir jalur URL harus merepresentasikan nama jenis yang sepenuhnya memenuhi syarat (seperti dalam path/google.protobuf.Duration). Nama harus dalam bentuk kanonis (misalnya, "." di awal tidak diterima).

Dalam praktiknya, tim biasanya melakukan pra-kompilasi ke dalam biner semua jenis yang diharapkan untuk digunakan dalam konteks Any. Namun, untuk URL yang menggunakan skema http, https, atau tanpa skema, Anda dapat secara opsional menyiapkan server jenis yang memetakan URL jenis ke definisi pesan sebagai berikut:

  • Jika tidak ada skema yang diberikan, https akan diasumsikan.
  • HTTP GET di URL harus menghasilkan nilai google.protobuf.Type dalam format biner, atau menghasilkan error.
  • Aplikasi diizinkan untuk menyimpan hasil pencarian dalam cache berdasarkan URL, atau mengompilasinya terlebih dahulu ke dalam biner untuk menghindari pencarian. Oleh karena itu, kompatibilitas biner harus dipertahankan pada perubahan jenis. (Gunakan nama jenis berversi untuk mengelola perubahan yang menyebabkan gangguan.)

Catatan: fungsi ini saat ini tidak tersedia dalam rilis protobuf resmi, dan tidak digunakan untuk URL jenis yang dimulai dengan type.googleapis.com. Mulai Mei 2023, tidak ada implementasi server jenis yang banyak digunakan dan tidak ada rencana untuk mengimplementasikannya.

Skema selain http, https (atau skema kosong) dapat digunakan dengan semantik khusus penerapan.
value

string (bytes format)

Harus berupa buffer protokol berserial yang valid dari jenis yang ditentukan di atas.

String berenkode base64.

Anotasi Alat

Petunjuk Destruktif: ✅ | Petunjuk Idempoten: ❌ | Petunjuk Hanya Baca: ❌ | Petunjuk Dunia Terbuka: ❌