ייצוא קובץ SQL

בדף הזה מוסבר איך לייצא נתונים מאשכולות של AlloyDB ל-PostgreSQL לקובצי SQL dump.

מידע על העברה של מסד נתונים שלם משרת מסד נתונים נתמך למופע חדש של AlloyDB זמין במאמר העברת מסד נתונים ל-AlloyDB באמצעות Database Migration Service. אם אתם מייצאים כי אתם רוצים ליצור מופע חדש מהקובץ המיוצא, כדאי לכם לשחזר אשכול מגיבוי מאוחסן.

אתם יכולים לבטל את ייצוא הנתונים מאשכולות של AlloyDB ל-PostgreSQL. מידע נוסף מופיע במאמר ביטול ייצוא נתונים.

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

  • לפני שמתחילים פעולת ייצוא, חשוב לזכור שפעולות ייצוא משתמשות במשאבי מסד נתונים, אבל הן לא מפריעות לפעולות רגילות של מסד נתונים, אלא אם המופע לא מספק מספיק משאבים.
  • חיובים על העברת נתונים בין אזורים חלים כשהקטגוריה של היעד נמצאת באזור שונה מהאזור של אשכול המקור. מידע נוסף זמין במאמר בנושא תמחור של AlloyDB ל-PostgreSQL.
  • הדחיסה מופעלת אם שם האובייקט מסתיים בסיומת .gz. האובייקט מיוצא בפורמט .gz ל-Cloud Storage.
  • אפשר להריץ כמה פעולות ייצוא במקביל.

תפקידים והרשאות שנדרשים לייצוא מ-AlloyDB

כדי לייצא נתונים מ-AlloyDB ל-Cloud Storage, למשתמש שמבצע את הייצוא צריך להיות אחד מהתפקידים הבאים בניהול זהויות והרשאות גישה (IAM):

בנוסף, לחשבון השירות של אשכול AlloyDB צריך להיות אחד מהתפקידים הבאים בקטגוריית Cloud Storage:

  • תפקיד ה-IAM‏ storage.objectAdmin או storage.objectCreator
  • תפקיד בהתאמה אישית, כולל ההרשאה storage.objects.create

במאמר ניהול זהויות והרשאות גישה מוסבר איך משתמשים בתפקידים ב-IAM.

ייצוא נתונים מ-AlloyDB לקובץ SQL מוכן לשימוש

כשמבצעים ייצוא באמצעות AlloyDB, בין אם באמצעות ה-CLI של gcloud או ה-API, משתמשים בכלי pg_dump עם האפשרויות הנדרשות כדי לוודא שקובץ הייצוא שמתקבל תקין לייבוא חזרה ל-AlloyDB.

כדי לייצא נתונים ממסד נתונים באשכול AlloyDB לקובץ SQL dump בקטגוריה של Cloud Storage, צריך לבצע את השלבים הבאים:

gcloud

  1. מוודאים שיש קטגוריה של Cloud Storage קיימת לאחסון הקובץ המיוצא, או יוצרים קטגוריה חדשה של Cloud Storage.

  2. משתמשים בפורמט שמופיע כאן כדי לזהות את חשבון השירות של הפרויקט שממנו מייצאים. הפורמט של חשבון השירות הוא:

    service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com

    נותנים לחשבון השירות הרשאות לקטגוריה של Cloud Storage לצורך פעולת הייצוא.

  3. משתמשים ב-gcloud storage buckets add-iam-policy-binding כדי להקצות את storage.objectAdmin תפקיד IAM לחשבון השירות. במאמר הגדרה וניהול של מדיניות IAM בקטגוריות מוסבר איך מקצים תפקידים בקטגוריות.

    אם אתם מייצאים את הקובץ לקטגוריה קיימת ב-Cloud Storage שלא אתם יצרתם, יכול להיות שתצטרכו הרשאות נוספות ב-IAM כדי להקצות תפקידים בקטגוריה. לפרטים נוספים

  4. מייצאים את מסד הנתונים לקטגוריה של Cloud Storage. בהמשך מפורטות אפשרויות לייצוא נתונים בפורמט SQL dump:

    • ‫--async (אופציונלי): חזרה מיידית, בלי לחכות שהפעולה תסתיים.
    • ‫--tables (אופציונלי): טבלאות לייצוא.
    • ‫--schema-only (אופציונלי): אם ההגדרה הזו מוגדרת, רק הסכימה מיוצאת.
    • ‫--clean-target-objects (אופציונלי): אם ההגדרה הזו מוגדרת, הפקודות מוצגות לDROPכל האובייקטים של מסד הנתונים שנוצרו לפני שהפקודות מוצגות ליצירתם.
    • ‫--if-exist-target-objects (אופציונלי): אם ההגדרה הזו מוגדרת, משתמשים בפקודות DROP ... IF EXISTS כדי לבדוק אם האובייקט קיים לפני שמשחררים אותו במצב --clean-target-objects.

    כדי להשתמש בתכונות האלה, צריך לכלול את האפשרויות האלה בפקודה gcloud. אם רוצים לייצא רק את הגדרות האובייקט (סכימה) ולא נתונים, משתמשים בדגל –-schema-only. כדי לציין אילו טבלאות לייצא, משתמשים בדגל --tables=TABLE_NAMES. כדי לציין כמה טבלאות, אפשר להשתמש בערכים מופרדים בפסיקים של שמות טבלאות או בדפוסי תו כללי.

    אחרת, מסירים את הפרמטרים האלה מהפקודה הבאה:

    gcloud alloydb clusters export CLUSTER_NAME
  --region=REGION
  --database=DATABASE_NAME
  --gcs-uri="gs://BUCKET_NAME/OBJECT_NAME"
  --tables=TABLE_NAMES
  --schema-only
  --clean-target-objects
  --if-exist-target-objects
  --sql

    הפקודה alloydb clusters export לא מכילה טריגרים או פרוצדורות מאוחסנות, אבל היא כן מכילה תצוגות. כדי לייצא טריגרים או פרוצדורות מאוחסנות, משתמשים בכלי pg_dump.

    מידע נוסף על השימוש בפקודה alloydb clusters export זמין בדף העזרה של הפקודה alloydb clusters export.

  5. אם אין צורך לשמור את תפקיד ה-IAM שהגדרתם קודם, צריך לבטל את התפקיד עכשיו.

REST v1

  1. מוודאים שיש קטגוריה קיימת ב-Cloud Storage לאחסון הקובץ המיוצא, או יוצרים קטגוריה חדשה:

    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME

  2. משתמשים בפורמט של חשבון השירות כדי לזהות את חשבון השירות של הפרויקט שממנו מייצאים.

    הפורמט של חשבון השירות הוא:

     service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com

    נותנים לחשבון השירות הרשאות לקטגוריה של Cloud Storage לצורך פעולת הייצוא.

  3. משתמשים ב-gcloud storage buckets add-iam-policy-binding כדי להקצות את storage.objectAdmin תפקיד IAM לחשבון השירות. במאמר הגדרה וניהול של מדיניות IAM בקטגוריות מוסבר איך מקצים תפקידים בקטגוריות.

    אם אתם מייצאים את הקובץ לקטגוריה קיימת ב-Cloud Storage שלא אתם יצרתם, יכול להיות שתצטרכו הרשאות נוספות ב-IAM כדי להקצות תפקידים בקטגוריה. לפרטים נוספים

  4. מייצאים את מסד הנתונים.

    משתמשים ב-method הבא ב-HTTP ובכתובת ה-URL:

    POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export

    לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט.
    • ‫REGION: האזור שבו נפרס אשכול AlloyDB.
    • ‫CLUSTER_ID: מזהה האשכול.
    • ‫BUCKET_NAME: שם הקטגוריה ב-Cloud Storage.
    • ‫PATH_TO_SQL_FILE: הנתיב לקובץ ה-SQL המוכן לשימוש.
    • ‫DATABASE_NAME: השם של מסד נתונים בתוך מופע AlloyDB.
    • ‫TABLES: הטבלאות לייצוא.
    • ‫SCHEMA_ONLY: אם true, ייצוא הסכימה בלבד.
    • ‫CLEAN_TARGET_OBJECTS: אם true, פקודות הפלט יכללו אתDROP כל אובייקטי מסד הנתונים שנוצרו לפני הפלט של הפקודות ליצירתם.
    • ‫IF_EXIST_TARGET_OBJECTS: אם true, משתמשים בפקודות DROP ... IF EXISTS כדי לבדוק אם האובייקט קיים לפני שמעבירים אותו למצב clean_target_objects.

    כדי להשתמש בתכונות האלה, צריך להגדיר את הערכים של הפרמטרים האלה בתור true. אחרת, מגדירים את הערכים שלהם ל-false. אם רוצים לייצא רק את הגדרות האובייקט (סכימה) ולא נתונים, משתמשים בדגל schema_only. כדי לציין אילו טבלאות לייצא, משתמשים בשדה tables. אפשר לבחור כמה טבלאות על ידי הזנת רשימה של שמות טבלאות שמופרדים בפסיקים, או על ידי כתיבת תווים כלליים בתבנית.

    תוכן בקשת JSON:

    {
  "gcs_destination": {
    "uri": "gs://BUCKET_NAME/PATH_TO_SQL_FILE"
  },
  "database": "DATABASE_NAME",
  "sql_export_options": {
    "schema_only": true,
    "tables": [
     "TABLE1",
     "TABLE2"
    ],
    "clean_target_objects": false,
    "if_exist_target_objects": true
  }
}

    כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

    ‏Curl (Linux,‏ macOS או Cloud Shell)

    שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

       curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"

    ‎PowerShell (Windows)

    שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

       $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }

   Invoke-WebRequest `
     -Method POST `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile request.json `
   -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"| Select-Object -Expand Content

    מקבלים תגובת JSON שדומה לזו:

    תשובה

    {
  "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
    "createTime": "2024-09-17T06:05:31.244428646Z",
    "target": "projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID",
    "verb": "export",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

  5. אם אין לכם צורך לשמור את תפקיד ה-IAM שהגדרתם קודם, אתם יכולים להסיר אותו עכשיו.

רשימה מלאה של הפרמטרים של הבקשה מופיעה במאמר בנושא clusters:export.

המאמרים הבאים