MCP Tools Reference: cloud-sql

כלי: execute_sql

להריץ כל הצהרת SQL תקינה, כולל הצהרות של שפת הגדרת נתונים (DDL), שפת בקרת נתונים (DCL), שפת שאילתות נתונים (DQL) או שפת טיפול בנתונים (DML), במופע Cloud SQL.

כדי לתמוך בכלי execute_sql, מכונה ב-Cloud SQL צריכה לעמוד בדרישות הבאות:

  • הערך של data_api_access חייב להיות ALLOW_DATA_API.
  • במופע MySQL, צריך להגדיר את הדגל של מסד הנתונים cloudsql_iam_authentication לערך on. במכונת PostgreSQL, צריך להגדיר את האפשרות cloudsql.iam_authentication במסד הנתונים לערך on.
  • כדי להפעיל את הכלי execute_sql, צריך חשבון משתמש ב-IAM או חשבון שירות ב-IAM (CLOUD_IAM_USER או CLOUD_IAM_SERVICE_ACCOUNT). הכלי מריץ את הצהרות ה-SQL באמצעות ההרשאות של משתמש מסד הנתונים שנכנס באמצעות אימות מסד נתונים של IAM.

אחרי שמשתמשים בכלי create_instance כדי ליצור מופע, אפשר להשתמש בכלי create_user כדי ליצור חשבון משתמש IAM למשתמש שמחובר כרגע לפרויקט.

אלו המגבלות של הכלי execute_sql:

  • אם הצהרת SQL מחזירה תשובה גדולה מ-10 MB, התשובה תיחתך.
  • בכלי execute_sql, ברירת המחדל של הזמן הקצוב לתפוגה היא 30 שניות. אם שאילתה פועלת יותר מ-30 שניות, הכלי מחזיר שגיאה DEADLINE_EXCEEDED.
  • הכלי execute_sql לא נתמך ב-SQL Server.

אם מופיעות שגיאות כמו "אימות IAM לא מופעל עבור המופע", אפשר להשתמש בכלי get_instance כדי לבדוק את הערך של דגל אימות מסד הנתונים של IAM עבור המופע.

אם מופיעות שגיאות כמו "המופע לא מאפשר שימוש ב-executeSql כדי לגשת למופע הזה", אפשר להשתמש בכלי get_instance כדי לבדוק את ההגדרה data_api_access.

אם מתקבלות שגיאות אימות:

  1. בודקים אם חשבון המשתמש שמחובר כרגע קיים כמשתמש IAM במופע באמצעות הכלי list_users.
  2. אם חשבון המשתמש ב-IAM לא קיים, צריך להשתמש בכלי create_user כדי ליצור את חשבון המשתמש ב-IAM עבור המשתמש המחובר.
  3. אם למשתמש שמחובר כרגע אין את תפקידי המשתמש המתאימים במסד הנתונים, אפשר להשתמש בכלי update_user כדי להעניק למשתמש תפקידים במסד הנתונים. לדוגמה, תפקיד cloudsqlsuperuser יכול לספק למשתמש IAM הרבה הרשאות נדרשות.

  4. בודקים אם למשתמש שמחובר כרגע יש את הרשאות ה-IAM הנכונות שהוקצו לפרויקט. אפשר להשתמש בפקודה gcloud projects get-iam-policy [PROJECT_ID] כדי לבדוק אם למשתמש הוקצו התפקידים או ההרשאות המתאימים ב-IAM לפרויקט.

    • למשתמש צריכה להיות הרשאה cloudsql.instance.login לבצע אימות אוטומטי של מסד נתונים ב-IAM.
    • למשתמש צריכה להיות הרשאה cloudsql.instances.executeSql להפעיל הצהרות SQL באמצעות הכלי execute_sql או executeSql API.
    • תפקידי IAM נפוצים שמכילים את ההרשאות הנדרשות: Cloud SQL Instance User (roles/cloudsql.instanceUser) או Cloud SQL Admin (roles/cloudsql.admin)

כשמקבלים ExecuteSqlResponse, צריך תמיד לבדוק את השדות message ו-status בגוף התגובה. קוד סטטוס של HTTP שמציין הצלחה לא מבטיח שכל הצהרות ה-SQL יצליחו. בשדות message ו-status יצוין אם היו שגיאות או אזהרות חלקיות במהלך הביצוע של הצהרת ה-SQL.

בדוגמה הבאה אפשר לראות איך משתמשים ב-curl כדי להפעיל את כלי ה-MCP‏ execute_sql.

בקשת 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
}'

סכימת הקלט

בקשת SQL להרצה של מכונה עבור MCP.

SqlInstancesExecuteSqlMcpRequest

ייצוג ב-JSON 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string
}
שדות
instance

string

חובה. מזהה מופע של מסד נתונים. הפרטים האלה לא כוללים את מזהה הפרויקט.
project

string

חובה. מזהה הפרויקט שמכיל את המופע.
sqlStatement

string

חובה. הצהרות SQL להרצה במסד הנתונים. יכול להיות שזה יהיה משפט אחד או רצף של משפטים שמופרדים באמצעות נקודה-פסיק.
database

string

זה שינוי אופציונלי. שם מסד הנתונים שבו יופעל המשפט. ב-Postgres זה נדרש, ב-MySQL זה אופציונלי. ב-Postgres, אם השאילתה לא מוגבלת למסד נתונים קיים, כמו list databases / create new database / grant roles, אפשר להעביר ערך ברירת מחדל בתור postgres.

סכימת פלט

תגובה להרצת הצהרות SQL.

SqlInstancesExecuteSqlResponse

ייצוג ב-JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
שדות
messages[]

object (Message)

רשימה של הודעות ואזהרות שנוצרו במהלך הרצת השאילתה. ב-PostgreSQL, זה כולל את כל ההודעות והאזהרות. ב-MySQL, זה כולל אזהרות שנוצרו על ידי ההצהרה האחרונה שהופעלה. כדי לאחזר את כל האזהרות בשאילתה עם כמה הצהרות, צריך להריץ את SHOW WARNINGS אחרי כל הצהרה.
metadata

object (Metadata)

מידע נוסף על מטא-נתונים שקשורים להרצת הצהרות SQL.
results[]

object (QueryResult)

רשימת התוצאות אחרי הפעלת כל הצהרות ה-SQL.
status

object (Status)

מכיל את השגיאה ממסד הנתונים אם ביצוע ה-SQL נכשל.

הודעה

ייצוג ב-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.
}
שדות

שדה איחוד _message.

הערך _message יכול להיות רק אחד מהבאים:
message

string

מחרוזת ההודעה המלאה. ב-PostgreSQL, זהו מחרוזת מעוצבת שעשויה לכלול חומרה, קוד והודעת אזהרה. ב-MySQL, השדה הזה מכיל את הודעת האזהרה.

שדה איחוד _severity.

הערך _severity יכול להיות רק אחד מהבאים:
severity

string

רמת החומרה של ההודעה (למשל, ‫NOTICE ל-PostgreSQL,‏ WARNING ל-MySQL).

מטא-נתונים

ייצוג ב-JSON 
{
  "sqlStatementExecutionTime": string
}
שדות
sqlStatementExecutionTime

string (Duration format)

הזמן שנדרש להפעלת הצהרות ה-SQL.

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-'s'. דוגמה: "3.5s".

משך הזמן

ייצוג ב-JSON 
{
  "seconds": string,
  "nanos": integer
}
שדות
seconds

string (int64 format)

השניות החתומות של טווח הזמן. הערך חייב להיות בין ‎-315,576,000,000 לבין ‎+315,576,000,000, כולל. הערה: הגבולות האלה מחושבים לפי: 60 שניות/דקה * 60 דקות/שעה * 24 שעות/יום * 365.25 ימים/שנה * 10,000 שנים
nanos

integer

שברים חתומים של שנייה ברזולוציית ננו-שנייה של טווח הזמן. משכי זמן של פחות משנייה אחת מיוצגים באמצעות שדה seconds עם הערך 0 ושדה nanos עם ערך חיובי או שלילי. למשכי זמן של שנייה אחת או יותר, הערך בשדה nanos צריך להיות שונה מאפס ובעל אותו סימן כמו הערך בשדה seconds. הערך חייב להיות בין ‎-999,999,999 ל-‎+999,999,999, כולל.

QueryResult

ייצוג ב-JSON 
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}
שדות
columns[]

object (Column)

רשימת העמודות שנכללות בתוצאה. הוא כולל גם את סוג הנתונים של העמודה.
rows[]

object (Row)

השורות שמוחזרות על ידי הצהרת ה-SQL.
message

string

הודעה שקשורה לתוצאת ההרצה של SQL.
partialResult

boolean

הערך מוגדר כ-true אם התוצאה של ביצוע ה-SQL נחתכת בגלל מגבלות גודל או שגיאה באחזור התוצאות.
status

object (Status)

אם התוצאות נחתכו בגלל שגיאה, פרטי השגיאה.

עמודה

ייצוג ב-JSON 
{
  "name": string,
  "type": string
}
שדות
name

string

שם העמודה.
type

string

סוג הנתונים בעמודה.

Row

ייצוג ב-JSON 
{
  "values": [
    {
      object (Value)
    }
  ]
}
שדות
values[]

object (Value)

הערכים של השורה.

ערך

ייצוג ב-JSON 
{
  "value": string,
  "nullValue": boolean
}
שדות
value

string

ערך התא בפורמט מחרוזת.
nullValue

boolean

אם ערך התא הוא null, הדגל הזה יוגדר כ-true.

סטטוס

ייצוג ב-JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
שדות
code

integer

קוד הסטטוס, שצריך להיות ערך enum של google.rpc.Code.
message

string

הודעת שגיאה שמוצגת למפתחים, שצריכה להיות באנגלית. כל הודעת שגיאה שמוצגת למשתמש צריכה להיות מותאמת לשפה המקומית ולהישלח בשדה google.rpc.Status.details, או להיות מותאמת לשפה המקומית על ידי הלקוח.
details[]

object

רשימה של הודעות שכוללות את פרטי השגיאה. יש קבוצה משותפת של סוגי הודעות לשימוש בממשקי API.

אובייקט שמכיל שדות מכל סוג שהוא. שדה נוסף "@type" מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

הכול

ייצוג ב-JSON 
{
  "typeUrl": string,
  "value": string
}
שדות
typeUrl

string

כתובת URL או שם משאב שמזהים באופן ייחודי את הסוג של הודעת מאגר אחסון לפרוטוקולים שעברה סריאליזציה. המחרוזת הזו חייבת להכיל לפחות תו אחד של '/'. הפלח האחרון בנתיב של כתובת ה-URL חייב לייצג את השם המוגדר במלואו של הסוג (כמו ב-path/google.protobuf.Duration). השם צריך להיות בצורה קנונית (למשל, לא ניתן להשתמש בנקודה מובילה).

בפועל, צוותים בדרך כלל מבצעים קומפילציה מראש לבינארי של כל הסוגים שהם מצפים שהבינארי ישתמש בהם בהקשר של Any. עם זאת, עבור כתובות URL שמשתמשות בסכימה http,‏ https או ללא סכימה, אפשר להגדיר שרת סוגים שממפה כתובות URL של סוגים להגדרות של הודעות באופן הבא:

  • אם לא מציינים סכמה, ברירת המחדל היא https.
  • בקשת HTTP GET לכתובת ה-URL צריכה להחזיר ערך google.protobuf.Type בפורמט בינארי או להפיק שגיאה.
  • לאפליקציות מותר לשמור במטמון תוצאות של חיפושים על סמך כתובת ה-URL, או להדר אותן מראש לקובץ בינארי כדי להימנע מחיפוש. לכן, צריך לשמור על תאימות בינארית כשמשנים סוגים. (כדי לנהל שינויים שעלולים לשבור את התאימות, צריך להשתמש בשמות סוגים עם מספור גרסאות).

הערה: הפונקציונליות הזו לא זמינה כרגע בגרסה הרשמית של protobuf, והיא לא משמשת לכתובות URL של סוגים שמתחילות ב-type.googleapis.com. נכון למאי 2023, אין יישומי שרת מסוגים בשימוש נרחב, ואין תוכניות ליישם אחד כזה.

אפשר להשתמש בסכימות אחרות מלבד http, https (או הסכימה הריקה) עם סמנטיקה ספציפית להטמעה.
value

string (bytes format)

חייב להיות מאגר אחסון לפרוטוקולים סדרתי תקין מהסוג שצוין למעלה.

מחרוזת בקידוד Base64.

הערות על כלי

רמז הרסני: ✅ | רמז אידמפוטנטי: ❌ | רמז לקריאה בלבד: ❌ | רמז לעולם פתוח: ❌