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

המסוף

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

   כניסה לדף Cloud SQL Instances

2. כדי לפתוח את הדף Overview של מכונה, לוחצים על שם המכונה.
3. בתפריט הניווט של SQL, לוחצים על Connections.
4. נכנסים לכרטיסייה Networking.
5. מסמנים את התיבה Allow 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 לנקודת הקצה (endpoint) של 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.

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 = "POSTGRES_17"

  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. If a service account is used
 * and the instance is Postgres, trim the ".gserviceaccount.com"
 * suffix to avoid exceeding the username length limit.
*/
resource "google_sql_user" "iam_user" {
  name     = "account-used-to-apply-this-config@example.com"
  instance = google_sql_database_instance.instance.name
  type     = "CLOUD_IAM_USER"

  # Roles granted to the user. For least privilege, you can create smaller roles
  # and then assign them to this user in place of `cloudsqlsuperuser`.
  database_roles = ["cloudsqlsuperuser"]
}

resource "google_sql_database" "database" {
  name     = "my-database"
  instance = google_sql_database_instance.instance.name
}

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"

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

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

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

REST

כדי להריץ הצהרת SQL במסד נתונים במכונה באמצעות ה-API בארכיטקטורת REST, שולחים בקשת POST לנקודת הקצה (endpoint) של 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. שינוי אופן החיתוך

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.

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

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

REST

כדי להריץ הצהרת SQL במסד נתונים במכונה באמצעות ה-API בארכיטקטורת REST, שולחים בקשת POST לנקודת הקצה (endpoint) של 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. שינוי אופן החיתוך