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

‫MySQL   |  PostgreSQL   |  SQL Server

בדף הזה מוסבר איך להריץ הצהרות 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 מתאים להרצת הצהרות אדמיניסטרטיביות קטנות ומהירות, כמו יצירת תפקידים או משתמשים במסד נתונים וביצוע עדכונים קטנים בסכימה.

הערה: Google Cloud משתמש בספק זהויות חיצוני, ולכן צריך להשתמש במזהים של ישויות ראשיות של איחוד שירותי אימות הזהות של כוח עבודה. מחליפים מופעים של מזהים של חשבונות ראשיים ב-Google Account – כמו user:[e-mail], group:[e-mail] ו-domain:example.com – במזהים מתאימים של חשבונות ראשיים באיחוד שירותי אימות הזהות של כוח העבודה.

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

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

הגדרת משתמש במסד הנתונים

כדי להריץ הצהרות SQL, צריך לאמת את Data API כמשתמש במסד הנתונים. אתם יכולים לבצע אימות כמשתמש מובנה, משתמש IAM, חשבון שירות IAM או קבוצת IAM.

כדי לבצע אימות באמצעות IAM, מבצעים את הפעולות הבאות:

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

כדי לבצע אימות כמשתמש מובנה באמצעות סיסמה:

1. יוצרים חשבון משתמש עם סיסמה לא ריקה. שימו לב: אי אפשר לאמת את Data API כמשתמש ברירת המחדל root.
2. מקצים לחשבון את התפקידים או ההרשאות הנדרשים להרצת הצהרות SQL. אפשר להקצות תפקידים במסד הנתונים בזמן יצירת החשבון או עדכון החשבון. אם יצרתם תפקידים מותאמים אישית במסד הנתונים עם הרשאות מינימליות, הקצו אותם לחשבון. אחרת, צריך להקצות לחשבון את התפקיד המוגדר מראש cloudsqlsuperuser, להשתמש ב-Data API כדי ליצור תפקידים חדשים בהתאמה אישית במסד הנתונים עם הרשאות מוגבלות יותר, ואז להעניק את התפקידים החדשים לחשבון במקום cloudsqlsuperuser.
3. משתמשים ב-Secret Manager כדי ליצור Secret אזורי לאחסון הסיסמה. מטעמי אבטחה, בבקשת ה-API, Data API מבקש את שם המשאב של הסוד במקום את הסיסמה. הסוד האזורי צריך להיות מאוחסן באותו אזור שבו נמצאת מכונת Cloud SQL. לא ניתן להשתמש בסוד שנוצר באמצעות נקודת הקצה הגלובלית של Secret Manager, גם אם הוא מאוחסן באותו אזור.
4. הענקת הרשאה למבצע הקריאה ל-Data API‏ roles/secretmanager.secretAccessor. מומלץ להגדיר תנאים ב-IAM כדי לאפשר למשתמש גישה לסוד ספציפי, אבל לא לסודות אחרים בפרויקט.

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

למשתמשים או לחשבונות השירות שמשמשים לקריאה ל-Data API צריכה להיות הרשאה להפעיל הצהרות 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.

כשמשתמשים בסוד של Secret Manager לאימות, למשתמש או לחשבון השירות צריכה להיות גם הרשאה לגשת לסוד, secretmanager.versions.access. ההרשאה כלולה באחד מהתפקידים המוגדרים מראש הבאים:

• Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)
• Secret Manager Admin (roles/secretmanager.admin)

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

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

המסוף

1. נכנסים לדף Cloud SQL Instances במסוף Google Cloud .

   כניסה לדף Cloud SQL Instances

2. כדי לפתוח את הדף סקירה כללית של מכונה, לוחצים על שם המכונה.
3. בתפריט הניווט SQL, בוחרים באפשרות Connections (קישורים).
4. נכנסים לכרטיסייה Networking.
5. מסמנים את תיבת הסימון Allow Data API (התרת שימוש ב-Data API).
6. לוחצים על Save.

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=DISALLOW_DATA_API:

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

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

REST

כדי להפעיל גישה ל-Data API במופע, שולחים בקשת PATCH לנקודת הקצה instances.patch:

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

גוף הבקשה צריך להכיל את השדה dataApiAccess עם הערך ALLOW_DATA_API:

{
  "dataApiAccess": "ALLOW_DATA_API"
}

כדי להשבית את הגישה ל-Data API, מגדירים את dataApiAccess ל-DISALLOW_DATA_API.

הפעלת הצהרת SQL

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

אימות באמצעות IAM

אפשר להריץ הצהרות SQL באמצעות אימות מסד נתונים של IAM.

gcloud

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

gcloud 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 אם צריך.

Terraform

אפשר להשתמש ב-Data API ב-Terraform כדי להקצות משאבים במסד הנתונים, כמו מסדי נתונים, טבלאות, תוספים, משתמשים והענקת הרשאות, בלי להתחבר למופע באופן ידני. כדי להריץ סקריפט SQL ב-Terraform, משתמשים במשאב google_sql_provision_script Terraform.

resource "google_sql_database_instance" "instance" {
  name             = "my-instance"
  database_version = "MYSQL_8_4"

  settings {
    tier            = "db-perf-optimized-N-2"
    data_api_access = "ALLOW_DATA_API"  # This allows the use of Data API.
    database_flags {
      name  = "cloudsql_iam_authentication"
      value = "on"
    }
  }
}

/*
 * Create a database user for your account and grant roles so it has privilege
 * to access the database. Set the type to CLOUD_IAM_USER for huamn
 * account or CLOUD_IAM_SERVICE_ACCOUNT for service account.
 */
resource "google_sql_user" "iam_user" {
  name     = "[e-mail]"
  instance = google_sql_database_instance.instance.name
  type     = "CLOUD_IAM_USER"

  # Roles granted to the user. To follow the principle of least privilege, you
  # can first use `google_sql_provision_script` to create custom database role(s)
  # with lesser privileges and then assign them to this user in place of
  # `cloudsqlsuperuser`.
  # This field doesn't support MySQL 5.6 and 5.7.
  database_roles = ["cloudsqlsuperuser"]
}

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 DATABASE pets;"
  instance = google_sql_database_instance.instance.name

  # Some of your queries may require a database. You can create and use a
  # database in the script or explicitly create and reference a database
  # like database = google_sql_database.database.name.

  description = "sql script to create DBs"

  # The identity account used to apply your Terraform config must exist as an
  # IAM user or IAM service account in the instance. Terraform connects to the
  # instance via IAM database authentication to execute the script.
  depends_on = [google_sql_user.iam_user]
}

החלה של השינויים

כדי להחיל את הגדרות Terraform בפרויקט ב- Google Cloud , מבצעים את השלבים בקטעים הבאים.

הכנת Cloud Shell

1. מפעילים את Cloud Shell.

2. מגדירים את Google Cloud פרויקט ברירת המחדל שבו רוצים להחיל את ההגדרות של Terraform.

   תצטרכו להריץ את הפקודה הזו רק פעם אחת לכל פרויקט, ותוכלו לעשות זאת בכל ספרייה.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   אם תגדירו ערכים ספציפיים בקובץ התצורה של Terraform, הם יבטלו את ערכי ברירת המחדל של משתני הסביבה.

הכנת הספרייה

לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. אם אתם עוקבים אחרי המדריך, תוכלו להעתיק את הקוד לדוגמה בכל קטע או שלב.

   מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

   לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.

3. בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
4. שומרים את השינויים.
5. מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה.

   terraform init

   אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google:

   terraform init -upgrade

החלה של השינויים

1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם:

   terraform plan

   מתקנים את ההגדרות לפי הצורך.

2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform:

   terraform apply

   ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

3. פותחים את Google Cloud הפרויקט כדי לראות את התוצאות. במסוף Google Cloud , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

הערה: בדרך כלל הנחת העבודה בדוגמאות של Terraform היא שממשקי ה-API הנדרשים מופעלים ב Google Cloud פרויקט.

מחיקת השינויים

מחיקה של משאב google_sql_provision_script לא תמחק את המשאבים במסד הנתונים שהוא יצר. כדי למחוק אותם, אפשר להוסיף הצהרות באופן מפורש בסקריפט, כמו drop ... if exists, ואז להחיל את השינויים.

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"
  "autoIamAuthn": true
}

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

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

אימות באמצעות סיסמה

אפשר להריץ הצהרות SQL באמצעות אימות סיסמה מובנה, כשהסיסמה מאוחסנת כסוד אזורי ב-Secret Manager באותו אזור כמו מופע Cloud SQL.

gcloud

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

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

• ‫INSTANCE_NAME: השם של המכונה.
• ‫DATABASE_NAME: השם של מסד הנתונים בתוך המכונה.
• ‫SQL_STATEMENT: הצהרת ה-SQL להרצה. אם ההצהרה מכילה רווחים או תווים מיוחדים של מעטפת, צריך להוסיף לה מרכאות.
• USER: משתמש מסד הנתונים שיש לבצע אימות בתורו. לא כוללים את @ ואת שם המארח.
• ‫PASSWORD_SECRET_VERSION: שם המשאב של הסוד ב-Secret Manager שמכיל את הסיסמה של משתמש מסד הנתונים. הסוד צריך להיות סוד אזורי ולאחסן אותו באותו אזור שבו נמצא מופע Cloud SQL. הפורמט הצפוי של שם המשאב הוא projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}.
• ‫PARTIAL_RESULT_MODE: אופציונלי. המדיניות הזו קובעת איך להגיב כשהתוצאה לא מלאה. יכול להיות ALLOW_PARTIAL_RESULT, FAIL_PARTIAL_RESULT או PARTIAL_RESULT_MODE_UNSPECIFIED. מידע נוסף על שינוי התנהגות החיתוך

Terraform

אפשר להשתמש ב-Data API ב-Terraform כדי להקצות משאבים במסד הנתונים, כמו מסדי נתונים, טבלאות, תוספים, משתמשים והענקת הרשאות, בלי להתחבר למופע באופן ידני. כדי להריץ סקריפט SQL ב-Terraform, משתמשים במשאב google_sql_provision_script 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
  ]
}

החלה של השינויים

כדי להחיל את הגדרות Terraform בפרויקט ב- Google Cloud , מבצעים את השלבים בקטעים הבאים.

הכנת Cloud Shell

1. מפעילים את Cloud Shell.

2. מגדירים את Google Cloud פרויקט ברירת המחדל שבו רוצים להחיל את ההגדרות של Terraform.

   תצטרכו להריץ את הפקודה הזו רק פעם אחת לכל פרויקט, ותוכלו לעשות זאת בכל ספרייה.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   אם תגדירו ערכים ספציפיים בקובץ התצורה של Terraform, הם יבטלו את ערכי ברירת המחדל של משתני הסביבה.

הכנת הספרייה

לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. אם אתם עוקבים אחרי המדריך, תוכלו להעתיק את הקוד לדוגמה בכל קטע או שלב.

   מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

   לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.

3. בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
4. שומרים את השינויים.
5. מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה.

   terraform init

   אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google:

   terraform init -upgrade

החלה של השינויים

1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם:

   terraform plan

   מתקנים את ההגדרות לפי הצורך.

2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform:

   terraform apply

   ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

3. פותחים את Google Cloud הפרויקט כדי לראות את התוצאות. במסוף Google Cloud , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

הערה: בדרך כלל הנחת העבודה בדוגמאות של Terraform היא שממשקי ה-API הנדרשים מופעלים ב Google Cloud פרויקט.

מחיקת השינויים

מחיקה של משאב google_sql_provision_script לא תמחק את המשאבים במסד הנתונים שהוא יצר. כדי למחוק אותם, אפשר להוסיף הצהרות באופן מפורש בסקריפט, כמו drop ... if exists, ואז להחיל את השינויים.

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",
  "user": "USER",
  "passwordSecretVersion": "PASSWORD_SECRET_VERSION",
  "partialResultMode": "PARTIAL_RESULT_MODE"
}

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

• PROJECT_ID: מזהה הפרויקט.
• ‫INSTANCE_NAME: השם של המכונה.
• ‫DATABASE_NAME: השם של מסד הנתונים בתוך המכונה.
• ‫SQL_STATEMENT: הצהרת ה-SQL להרצה.
• USER: משתמש מסד הנתונים שיש לבצע אימות בתורו. לא כוללים את @ ואת שם המארח.
• ‫PASSWORD_SECRET_VERSION: שם המשאב של הסוד ב-Secret Manager שמכיל את הסיסמה של משתמש מסד הנתונים. הסוד צריך להיות סוד אזורי ולאחסן אותו באותו אזור שבו נמצא מופע Cloud SQL. הפורמט הצפוי של שם המשאב הוא projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}.
• ‫PARTIAL_RESULT_MODE: אופציונלי. קובעת איך ה-API מגיב כשגודל התוצאה חורג מ-10MB. יכול להיות FAIL_PARTIAL_RESULT, ALLOW_PARTIAL_RESULT או PARTIAL_RESULT_MODE_UNSPECIFIED. מידע נוסף על שינוי התנהגות החיתוך

שינוי התנהגות הקיצור

אתם יכולים לקבוע איך המערכת תטפל בתוצאות גדולות כשמריצים SQL, על ידי הכללת השדה "partialResultMode" בבקשה. בשדה הזה אפשר להזין את הערכים הבאים:

• ‫FAIL_PARTIAL_RESULT: ברירת מחדל. הפונקציה מחזירה שגיאה אם התוצאה גדולה מ-10 MB או אם אפשר לאחזר רק חלק מהתוצאה. לא להחזיר את התוצאה.
• ‫ALLOW_PARTIAL_RESULT: מחזירה תוצאה קטועה ומגדירה את partial_result לערך true אם התוצאה גדולה מ-10 MB או אם אפשר לאחזר רק תוצאה חלקית בגלל שגיאה. לא להקפיץ הודעת שגיאה.
• ‫PARTIAL_RESULT_MODE_UNSPECIFIED: מצב לא מוגדר, זהה למצב FAIL_PARTIAL_RESULT.

שאילתות ביקורת

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

אתם יכולים להשתמש בתובנות לגבי שאילתות כדי לעקוב אחרי מידע נוסף על השאילתות שלכם ולנתח בעיות בביצועים. שימו לב: בכלי Query Insights יוצגו שאילתות ExecuteSql עם כתובת ה-IP של הלקוח localhost כי החיבור למסד הנתונים מתבצע מתוך מופע Cloud SQL עצמו.

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

מגבלות

• המגבלה על גודל התגובה היא 10 MB. אם התוצאות חורגות מהגודל הזה, הן נחתכות אם הערך של partialResultMode הוא ALLOW_PARTIAL_RESULT, אחרת מוצגת שגיאה.
• הבקשות מוגבלות ל-0.5 MB.
• אפשר להריץ הצהרות SQL רק במכונות של Cloud SQL ל-MySQL שפועלות.
• ‫Cloud SQL לא תומך בשימוש ב-Data API עם מופעים שמוגדרים לשכפול שרת חיצוני.
• בקשות שנמשכות יותר מ-30 שניות מבוטלות. אי אפשר להגדיר פסק זמן ארוך יותר להצהרה באמצעות SET SESSION MAX_EXECUTION_TIME. ב-Cloud SQL ל-MySQL 5.6 ו-5.7, הצהרות DDL שפועלות במשך זמן רב מדי עשויות לגרום לקבצים או לטבלאות יתומים שלא ניתן לבטל אותם בבטחה. צריך להיזהר עם הצהרות כמו ALTER TABLE בטבלאות גדולות.

• ב-Cloud SQL, מספר הבקשות executeSql בו-זמניות לכל מכונה מוגבל כדי למנוע עומס יתר. אם מגיעים למגבלה, הבקשות הבאות נכשלות ומוחזרת אחת מהשגיאות הבאות:

  • At most 'x' concurrent queries may be run on this instance. Try again later.
  • Maximum concurrent reads 'x' reached.

  המגבלה (x) היא 10 שאילתות לכל מופע.

• כל תגובה יכולה להכיל עד 10 הודעות או אזהרות ממסד הנתונים.

• אם יש שגיאה בתחביר או בהרצה של ההצהרה, לא מוחזרת תוצאה.

• אי אפשר לבצע אימות של Data API כמשתמשים מובנים עם סיסמאות ריקות.

• ב-Cloud SQL ל-MySQL, הודעות ואזהרות זמינות רק עבור ההצהרה האחרונה של ביצוע מרובה הצהרות.

• ב-Cloud SQL ל-MySQL, אי אפשר לאמת את Data API כמשתמשים עם אותו שם כמו משתמש מערכת, כמו root.

• הצהרות שצורכות כמות גדולה של זיכרון עלולות לגרום לשגיאות שקשורות לזיכרון. מידע נוסף על הימנעות מהשגיאות האלה זמין במאמר שיטות מומלצות לניהול השימוש בזיכרון. מופע של מסד נתונים שפועל עם ניצול גבוה של הזיכרון גורם לעיתים קרובות לבעיות בביצועים, להשהיות או אפילו להשבתה של מסד הנתונים.

• יכול להיות ש-Data API ייחסם באופן זמני למטרות של תקינות נתונים, בזמן שמתבצעות פעולות תחזוקה מסוימות במופע. אם זה קורה, אפשר לנסות שוב מאוחר יותר.

• כשמריצים כמה שאילתות ואחת מהן נכשלת, מוחזרת השגיאה הראשונה שנתקלים בה. יכול להיות שחלק מההצהרות בחבילה לפני השגיאה בוצעו בהצלחה. כדי למנוע את הבעיה הזו, אפשר להוסיף כמה שאילתות להצהרת transaction:

  START TRANSACTION;
      YOUR_SQL_STATEMENTS
  COMMIT;
  

  מחליפים את מה שכתוב בשדות הבאים:

  • ‫YOUR_SQL_STATEMENTS: ההצהרות שרוצים להריץ כחלק מהשאילתה הזו

• יכול להיות שתסריט ה-SQL והתגובה להרצה שלו יעברו דרך מיקומים ביניים בין הלקוח לבין המיקום של מופע היעד. לכן, בקשות ייכשלו עם השגיאה 'לא נתמך עבור מופעים בתיקיות מסוימות של חבילות בקרה של Assured Workloads' עבור פרויקטים מסוימים של Assured Workloads ועבור פרויקטים עם constraints/sql.restrictNoncompliantResourceCreation שנאכף באופן ידני.

פתרון בעיות

בקטע הזה מפורט מידע על בעיות שקשורות לשימוש ב-Data API, וגם שלבים לפתרון הבעיות.

שגיאה	פתרון בעיות
The instance doesn't allow using ExecuteSql to access this instance. You can allow it by patching the instance with {settings: { dataApiAccess: "ALLOW_DATA_API" }}	ממשק Data API מושבת כברירת מחדל. כדי לפתור את הבעיה, צריך להפעיל את Data API במופע.
Secret cannot be provided when auto_iam_authn is true.	כשמגדירים את auto_iam_authn ל-true, מתבצע אימות למסד הנתונים באמצעות IAM. שיטת האימות הזו לא דורשת סיסמה או סוד. אימות באמצעות IAM
ExecuteSql API is not supported for instances in certain Assured Workloads control packages folders yet.	יכול להיות שסקריפט ה-SQL והתגובה להרצה שלו יעברו דרך מיקומים ביניים בין הלקוח לבין המיקום של מופע היעד. לכן, בקשות ייכשלו עבור מקרים בפרויקטים מסוימים של Assured Workloads. אם הפרויקט שלכם לא רשום ב-Assured Workloads אבל constraints/sql.restrictNoncompliantResourceCreation נאכף באופן ידני, בקשו מהאדמין של הארגון להסיר את האילוץ, והבעיה תיפתר במופעים שייווצרו.
IAM authentication is not enabled for the instance	כדי לפתור את הבעיה, צריך להגדיר את המופע לאימות IAM.
The database is currently unavailable.	יכול להיות שהמופע מופעל מחדש, עובר תחזוקה או שהוא במצב לא תקין. צריך לבדוק את הסטטוס של המופע ולנסות שוב מאוחר יותר.