הרצת הצהרות SQL באמצעות Cloud SQL Data API

בדף הזה מוסבר איך להריץ הצהרות SQL על מסדי נתונים במופעים של Cloud SQL באמצעות Data API. בעזרת Data API, אתם יכולים להשתמש ב-Cloud SQL Admin API וב-ה-CLI של gcloud כדי להריץ הצהרות SQL בכל מכונה שבה הפעלתם גישה ל-Data API.

אפשר להשתמש ב-Data API עם מופעים שמשתמשים בכתובות IP ציבוריות, בגישה לשירותים פרטיים או ב-Private Service Connect. ממשק Data API תומך בכל סוגי הצהרות SQL, כולל שפת טיפול בנתונים (DML), שפת הגדרת נתונים (DDL) ושפת שאילתות נתונים (DQL). ה-Data API מתאים להרצת הצהרות אדמיניסטרטיביות קטנות ומהירות, כמו יצירת תפקידים או משתמשים במסד נתונים וביצוע עדכונים קטנים בסכימה. אפשר גם להשתמש ב-Data API כדי להפעיל תוספים של PostgreSQL.

לפני שמתחילים

לפני שמריצים הצהרות SQL במופע, צריך לבצע את הפעולות הבאות:

תפקידים או הרשאות נדרשים

כברירת מחדל, למשתמשים או לחשבונות שירות עם אחד מהתפקידים הבאים יש הרשאה להריץ הצהרות SQL במופע 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)

אפשר גם להגדיר תפקיד בהתאמה אישית ב-IAM למשתמש או לחשבון השירות, שכולל את ההרשאה cloudsql.instances.executesql. ההרשאה הזו נתמכת בתפקידים בהתאמה אישית ב-IAM.

הפעלה או השבתה של Data API

כדי להשתמש ב-Data API, צריך להפעיל אותו לכל מופע. אפשר להשבית את Data API בכל שלב.

gcloud

כדי להפעיל גישה ל-Data API במופע, משתמשים בפקודה gcloud sql instances patch עם הדגל --data-api-access=ALLOW_DATA_API:

gcloud sql instances patch INSTANCE_NAME --data-api-access=ALLOW_DATA_API

כדי להשבית את הגישה ל-Data API, משתמשים בדגל --data-api-access=DENY_DATA_API:

gcloud sql instances patch INSTANCE_NAME --data-api-access=DENY_DATA_API

מחליפים את INSTANCE_NAME בשם המכונה שבה רוצים להפעיל או להשבית את Data API.

הפעלת הצהרת SQL

אפשר להריץ הצהרות SQL במסדי נתונים במופע Cloud SQL באמצעות ה-CLI של gcloud או API בארכיטקטורת REST.

gcloud

כדי להריץ הצהרת SQL במסד נתונים במכונה באמצעות ה-CLI של gcloud, משתמשים בפקודה gcloud beta sql instances execute-sql:

gcloud beta sql instances execute-sql INSTANCE_NAME \
--database=DATABASE_NAME \
--sql=SQL_STATEMENT \
--partial_result_mode=PARTIAL_RESULT_MODE

מחליפים את הפרטים הבאים:

  • ‫INSTANCE_NAME: השם של המכונה.
  • ‫DATABASE_NAME: השם של מסד הנתונים בתוך המכונה.
  • ‫SQL_STATEMENT: הצהרת ה-SQL להרצה. אם ההצהרה מכילה רווחים או תווים מיוחדים של מעטפת, צריך להוסיף לה מרכאות.
  • ‫PARTIAL_RESULT_MODE: אופציונלי. המדיניות הזו קובעת איך להגיב אם התוצאה לא מלאה. יכול להיות ALLOW_PARTIAL_RESULT, FAIL_PARTIAL_RESULT או PARTIAL_RESULT_MODE_UNSPECIFIED. מידע נוסף על שינוי התנהגות החיתוך

אפשר גם להוסיף את הדגל --project=PROJECT_ID אם צריך.

REST

כדי להריץ הצהרת SQL מול מסד נתונים במופע באמצעות API בארכיטקטורת REST, שולחים בקשת POST לנקודת הקצה executeSql:

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/executeSql

גוף הבקשה צריך להכיל את שם מסד הנתונים ואת הצהרת ה-SQL:

{
  "database": "DATABASE_NAME",
  "sqlStatement": "SQL_STATEMENT",
  "partialResultMode": "PARTIAL_RESULT_MODE"
}

מחליפים את הפרטים הבאים:

  • PROJECT_ID: מזהה הפרויקט.
  • ‫INSTANCE_NAME: השם של המכונה.
  • ‫DATABASE_NAME: השם של מסד הנתונים בתוך המכונה.
  • ‫SQL_STATEMENT: הצהרת ה-SQL להרצה.
  • ‫PARTIAL_RESULT_MODE: אופציונלי. קובעת איך ה-API מגיב כשהתוצאה גדולה מ-10MB. הערך יכול להיות FAIL_PARTIAL_RESULT או ALLOW_PARTIAL_RESULT. איך משנים את התנהגות החיתוך

שינוי התנהגות החיתוך

אתם יכולים לקבוע איך לטפל בתוצאות גדולות כשמריצים SQL.

  • כוללים את השדה "partialResultMode" בבקשה. אפשר להזין בשדה הזה את הערכים הבאים:
    • ‫FAIL_PARTIAL_RESULT: השגיאה תופעל אם התוצאה חורגת מ-10 MB או אם אפשר לאחזר רק תוצאה חלקית. לא להחזיר את התוצאה.
    • ‫ALLOW_PARTIAL_RESULT: מחזירה תוצאה קטועה ומגדירה את partial_result כ-true אם התוצאה גדולה מ-10 MB או אם אפשר לאחזר רק תוצאה חלקית בגלל שגיאה. לא להציג שגיאה.

מגבלות

  • גודל התגובה המקסימלי הוא 10 MB. אם התוצאות חורגות מהגודל הזה, הן נחתכות אם הערך של partialResultMode הוא ALLOW_PARTIAL_RESULT, אחרת מוצגת שגיאה.
  • הבקשות מוגבלות ל-0.5 MB.
  • אפשר להריץ הצהרות SQL רק במופעים של Cloud SQL ל-PostgreSQL שפועלים.
  • ‫Cloud SQL לא תומך בשימוש ב-Data API עם מופעים שמוגדרים לשכפול שרת חיצוני.
  • בקשות שנמשכות יותר מ-30 שניות מבוטלות. אי אפשר להגדיר פסק זמן ארוך יותר להצהרה באמצעות SET STATEMENT_TIMEOUT.
  • ב-Cloud SQL, מספר הבקשות המקבילות של executeSql מוגבל ל-10 לכל מופע עבור כל משתמש. אם מגיעים למגבלה הזו, בקשות עוקבות נכשלות עם השגיאה 'הגעת למגבלה של 10 קריאות מקבילות'.
  • כל תגובה יכולה להכיל עד 10 הודעות או אזהרות ממסד הנתונים.
  • אם יש שגיאה בתחביר או בהרצה של ההצהרה, לא מוחזרת תוצאה.
  • הצהרות שצורכות כמות גדולה של זיכרון עלולות לגרום לשגיאות של חוסר זיכרון. מידע נוסף על הימנעות מהשגיאות האלה זמין במאמר שיטות מומלצות לניהול השימוש בזיכרון. מופע של מסד נתונים שפועל עם ניצול גבוה של הזיכרון גורם לעיתים קרובות לבעיות בביצועים, להשהיות או אפילו להשבתה של מסד הנתונים.