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

בדף הזה מוסבר איך לשדרג את הגרסה הראשית של מסד הנתונים באמצעות שדרוג במקום של מכונת Cloud SQL, במקום להעביר נתונים.

מבוא

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

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

פעולת השדרוג במקום של Cloud SQL ל-PostgreSQL משתמשת בכלי pg_upgrade.

תכנון שדרוג של גרסה ראשית

  1. מוודאים שיש לכם את התפקיד הנדרש כדי לשדרג לגרסה ראשית: בעלים של Cloud SQL או אדמין של Cloud SQL.

  2. בוחרים את הגרסה הראשית הרצויה.

    gcloud

    במאמר התקנת ה-CLI של gcloud מוסבר איך מתקינים את ה-CLI של gcloud ומתחילים להשתמש בו. למידע על הפעלת Cloud Shell, קראו את המאמר שימוש ב-Cloud Shell.

    כדי לבדוק את גרסאות מסד הנתונים שאפשר לשדרג במקום במכונה:

    1. מריצים את הפקודה הבאה:
      2. gcloud sql instances describe INSTANCE_NAME

      מחליפים את INSTANCE_NAME בשם המכונה.

    2. בפלט של הפקודה, מאתרים את הקטע שמסומן בתווית upgradableDatabaseVersions.
    3. כל סעיף משנה מחזיר גרסה של מסד נתונים שאפשר לשדרג. בכל סעיף משנה, בודקים את השדות הבאים.
      • ‫majorVersion: הגרסה הראשית שאפשר להגדיר כיעד לשדרוג במקום.
      • ‫name: מחרוזת גרסת מסד הנתונים שכוללת את הגרסה הראשית.
      • ‫displayName: השם המוצג של גרסת מסד הנתונים.

    REST v1

    כדי לבדוק אילו גרסאות של מסד נתונים זמינות לשדרוג במקום של גרסה ראשית, משתמשים ב-method‏ instances.get של Cloud SQL Admin API.

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

    • ‫INSTANCE_NAME: שם המכונה.

    ה-method של ה-HTTP וכתובת ה-URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

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

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

    
upgradableDatabaseVersions:

{
  major_version: "POSTGRES_15_0"
  name: "POSTGRES_15_0"
  display_name: "PostgreSQL 15.0"
}

    REST v1beta4

    כדי לבדוק אילו גרסאות של מסד נתונים זמינות לשדרוג במקום של גרסה ראשית של מכונה, משתמשים ב-method‏ instances.get של Cloud SQL Admin API.

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

    • ‫INSTANCE_NAME: שם המכונה.

    ה-method של ה-HTTP וכתובת ה-URL: 

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

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

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

    
upgradableDatabaseVersions:

{
  major_version: "POSTGRES_15_0"
  name: "POSTGRES_15_0"
  display_name: "PostgreSQL 15.0"
}

    ברשימה המלאה של גרסאות מסדי הנתונים שנתמכות ב-Cloud SQL מפורטות גרסאות מסדי הנתונים ומדיניות הגרסאות.

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

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

  4. מבצעים בדיקה מקדימה לשדרוגים.

  5. בודקים את השדרוג באמצעות הרצת בדיקה.

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

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

  6. מחליטים מתי לשדרג.

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

הכנה לשדרוג גרסה ראשית

לפני השדרוג, צריך לבצע את הפעולות הבאות.

  1. בודקים את הערך של LC_COLLATE במסדי הנתונים template ו-postgres. ערכת התווים של כל מסד נתונים חייבת להיות en_US.UTF8.

    אם הערך של LC_COLLATE במסדי הנתונים template ו-postgres הוא לא en_US.UTF8, השדרוג של הגרסה הראשית נכשל. כדי לפתור את הבעיה, אם באחד ממסדי הנתונים יש מערכת תווים שונה מ-en_US.UTF8, צריך לשנות את הערך של LC_COLLATE ל-en_US.UTF8 לפני שמבצעים את השדרוג.

    כדי לשנות את הקידוד של מסד נתונים:

    1. מרוקנים את מסד הנתונים.
    2. מחיקת מסד הנתונים.
    3. יוצרים מסד נתונים חדש עם הקידוד השונה (בדוגמה הזו, en_US.UTF8).
    4. טוענים מחדש את הנתונים.

    אפשרות אחרת היא לשנות את השם של מסד הנתונים:

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

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

  2. מנהלים את שאר התוספים של PostgreSQL.

    רוב התוספים פועלים בגרסה הראשית המשודרגת של מסד הנתונים. צריך להסיר את כל התוספים שלא נתמכים יותר בגרסת היעד. לדוגמה, אם משדרגים ל-PostgreSQL 11 או לגרסאות חדשות יותר, צריך להסיר את התוסף chkpass.

    אתם יכולים לשדרג ידנית את PostGIS ואת התוספים הקשורים אליו לגרסאות הנתמכות האחרונות.

    לפעמים, שדרוג מגרסאות 2.x של PostGIS יכול ליצור מצב שבו נשארים אובייקטים של מסד נתונים שלא משויכים לתוסף PostGIS. זה יכול לחסום את פעולת השדרוג. כדי לפתור את הבעיה, קראו את המאמר Fixing a broken postgis raster install.

    לפעמים אי אפשר להשלים את השדרוג לגרסה 3.1.7 ומעלה של PostGIS כי אובייקטים משתמשים בפונקציות שהוצאו משימוש. זה יכול לחסום את פעולת השדרוג. כדי לבדוק את סטטוס השדרוג, מריצים את הפקודה SELECT PostGIS_full_version();. אם מופיעות אזהרות, צריך להסיר את כל האובייקטים שמשתמשים בפונקציות שהוצאו משימוש ולעדכן את התוסף PostGIS לגרסת ביניים או לגרסה גבוהה יותר. אחרי שמבצעים את הפעולות האלה, מריצים שוב את הפקודה SELECT PostGIS_full_version();. מוודאים שלא מופיעות אזהרות. לאחר מכן, ממשיכים בפעולת השדרוג.

    מידע נוסף על שדרוג תוספי PostGIS זמין במאמר שדרוג PostGIS. לבעיות שקשורות לשדרוג PostGIS, ראו בדיקת הגרסה של מכונת PostgreSQL.
  3. ניהול דגלים לניהול מסד נתונים בהתאמה אישית. בודקים את השמות של כל הדגלים לניהול מסד נתונים בהתאמה אישית שהגדרתם למכונה של PostgreSQL. לבעיות שקשורות לדגלים האלה, ראו בדיקת הדגלים בהתאמה אישית של מכונת PostgreSQL.
  4. כשמשדרגים מגרסה ראשית אחת לאחרת, נסו להתחבר לכל מסד נתונים כדי לבדוק אם יש בעיות תאימות. מוודאים שמסדי הנתונים יכולים להתחבר זה לזה. בודקים את השדה datallowconn בכל מסד נתונים כדי לוודא שהחיבור מותר. הערך t מציין שהחיבור מותר, והערך f מציין שאי אפשר ליצור חיבור.
  5. אם אתם משתמשים בהתקנה של Datadog כדי לשדרג את מכונת Cloud SQL ל-PostgreSQL בגרסה 10 ואילך, לפני שאתם מבצעים את השדרוג, צריך להסיר את הפונקציה pg_stat_activity().

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

    משך הזמן שנדרש לשדרוג גרסה ראשית במקום תלוי במספר האובייקטים של מסד הנתונים במכונה. במכונות עם מספר גדול מאוד של אובייקטים, במיוחד טבלאות ואינדקסים, יכול להיות שזמני השדרוג יהיו ארוכים יותר באופן משמעותי. זה מגדיל את הסיכון שהזמן הקצוב לתפוגה של הפעולה יסתיים. ‫Cloud SQL מותאם למכונות עם עד כ-100,000 יחסים. אם המכונה חורגת מהמגבלה הזו, השדרוג לא נחסם, אבל הוא נחשב לפחות אמין ויש סיכוי גבוה יותר שהוא יימשך זמן רב או ייכשל אחרי זמן קצוב של 6 שעות.

    אם המכונה מכילה מספר גבוה של אובייקטים, לפני שמתחילים בתהליך השדרוג העיקרי:

    1. בודקים ומוחקים אובייקטים שלא בשימוש: מזהים ומסירים טבלאות ריקות, טבלאות שמשמשות רק לבדיקה או כל אובייקט אחר של מסד נתונים (סכימות, תצוגות, פונקציות) שכבר לא צריך.
    2. אופטימיזציה של מבני טבלאות:
      • אם אתם משתמשים בחלוקה למחיצות בטבלה, מספר מוגזם של מחיצות עשוי לתרום למספר גבוה של קשרים. במקרה כזה, כדאי לבדוק איך אפשר לצמצם את מספר המחיצות שבהן אתם משתמשים.
      • כדאי להעביר נתונים היסטוריים או נתונים שהגישה אליהם לא תכופה לאפשרות אחרת של אחסון נתונים. יכול להיות שהפעולה הזו תצמצם את מספר הטבלאות הפעילות או את הגודל והמורכבות של הטבלאות הקיימות.
    3. הרצת בדיקת שדרוג: מבצעים הרצה יבשה של השדרוג על שיבוט של המכונה בסביבת הייצור. כך תוכלו לקבל הערכה ריאלית של הזמן שנדרש ולגלות בעיות פוטנציאליות. ההערכה הזו חשובה במיוחד למסדי נתונים עם מספר גבוה של אובייקטים.

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

  7. לנהל מכונות עם אובייקטים גדולים (LOB).

    תהליך השדרוג במקום משתמש בכלי pg_upgrade של PostgreSQL. התהליך הזה יכול להימשך הרבה זמן אם מסד הנתונים מכיל מספר גדול מאוד של LOB, ועלול לגרום לכשל בשדרוג בגלל זמן קצוב לתפוגה.

    כדי לבדוק את מספר האובייקטים הגדולים במסד הנתונים, מתחברים למכונה של מסד הנתונים באמצעות לקוח PostgreSQL, כמו psql, ומריצים את השאילתה הבאה:

        SELECT count(*) AS total_large_objects FROM pg_largeobject_metadata;

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

    1. ניקוי אובייקטים גדולים (LOB) מיותמים: ‫PostgreSQL לא מסיר באופן אוטומטי אובייקטים גדולים (LOB) שאין להם יותר הפניות. כדי להסיר LOB מיותרים, משתמשים בכלי vacuumlo, שהוא חלק מהמודול contrib. צריך להריץ את הפקודה הזו ממכונה של לקוח שיכולה להתחבר למכונה של Cloud SQL.
      • אם אין לכם את vacuumlo, התקינו את החבילה postgresql-contrib במכונת הלקוח.
      • מריצים את הפקודה הבאה כדי לבצע הרצת בדיקה ולראות אילו LOB יימחקו:
        ‫
                vacuumlo -h INSTANCE_IP -U DATABASE_USER --dry-run DATABASE_NAME
        מחליפים את INSTANCE_IP,‏ DATABASE_USER ו-DATABASE_NAME בפרטי המכונה. תתבקשו להזין את הסיסמה של המשתמש.
      • מריצים את הפקודה הבאה כדי להסיר את ה-LOB שזוהו: 
                vacuumlo -h INSTANCE_IP -U DATABASE_USER DATABASE_NAME
        אחרי שמריצים את vacuumlo, בודקים שוב את מספר ה-LOB כדי לוודא שהניקוי הצליח.
    2. מחיקה ידנית של אובייקטים גדולים: בודקים את מדיניות שמירת הנתונים של האפליקציה ומסירים את כל ה-LOB שכבר לא נחוצים.
    3. הגדלת משאבי המכונה: מגדילים את ה-vCPU והזיכרון של המכונה באופן זמני או קבוע. כך יהיו יותר משאבים לתהליך pg_upgrade.
    4. העברת הנתונים: אם אי אפשר לצמצם את מספר ה-LOB במידה מספקת, כדאי לשדרג באמצעות העברת הנתונים. אתם יכולים ליצור גישה מותאמת אישית באמצעות pg_dump ו-pg_restore במיוחד בשביל LOB. יכול להיות ששיטות סטנדרטיות של רפליקציה לוגית לא יתמכו באופן מלא ב-LOB, ויידרשו שלבים נוספים וזמן השבתה להעברת LOB.

  8. מתעדים את המידע שצריך כדי ליצור מחדש את כל משבצות השכפול הלוגי במכונה, כולל משבצות שמשמשות את pglogical, השכפול הלוגי המובנה של PostgreSQL, ‏Datastream או כל צרכן אחר של פענוח לוגי.

מגבלות ידועות

המגבלות הבאות משפיעות על שדרוגים במקום של גרסאות ראשיות ב-Cloud SQL ל-PostgreSQL:

  • אי אפשר לשדרג גרסה ראשית במקום ברפליקה חיצונית.
  • שדרוג מגרסה אחת לאחרת של מכונות שיש בהן יותר מ-1,000 מסדי נתונים עלול להימשך זמן רב ולגרום לתפוגת הזמן הקצוב.
  • משתמשים בהצהרה select * from pg_largeobject_metadata; כדי לשלוח שאילתה על מספר האובייקטים הגדולים בכל מסד נתונים של PostgreSQL במכונה של Cloud SQL. אם התוצאה מכל מסדי הנתונים היא יותר מ-10 מיליון אובייקטים גדולים, השדרוג נכשל. מערכת Cloud SQL חוזרת לגרסה הקודמת של מסד הנתונים.
  • לפני שמשדרגים את הגרסה הראשית של PostgreSQL לגרסה 16 ואילך, צריך לשדרג את התוסף PostGIS לגרסה 3.4.0 בכל מסדי הנתונים. ב-PostgreSQL 18, שדרגו ל-PostGIS גרסה 3.6.0.
  • לפני שמשדרגים את הגרסה הראשית של PostgreSQL ל-17, צריך לשדרג את התוסף rdkit לגרסה 4.6.1 בכל מסדי הנתונים.
  • לפני שמשדרגים את הגרסה הראשית של PostgreSQL ל-16, 17 או 18, צריך לשדרג את התוסף pg_squeeze לגרסה 1.6, 1.7 או 1.8 בהתאמה בכל מסדי הנתונים.
  • אם אתם משתמשים בגרסאות 9.6,‏ 10,‏ 11 או 12 של PostgreSQL, גרסה 3.4.0 של התוסף PostGIS לא נתמכת. לכן, כדי לשדרג לגרסה ראשית של PostgreSQL 16 ואילך, קודם צריך לשדרג לגרסת ביניים של PostgreSQL (גרסאות 13, 14 או 15).

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

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

בדיקת המוכנות לשדרוג של המכונה

ב-Cloud SQL אפשר להריץ בדיקה מקדימה במכונה לפני שמשדרגים לגרסה ראשית. הבדיקה המקדימה הזו היא פעולה ממושכת (LRO) שבודקת אם המכונה מוכנה לשדרוג. הוא עוזר למצוא בעיות פוטנציאליות כמו חוסר תאימות, בעיות בהגדרות או בעיות בנתונים לפני פעולת השדרוג.

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

‫Cloud SQL יכול להריץ את תהליך הבדיקה המקדימה במקביל לעומס העבודה. כדי למנוע כשל בשדרוג, כדאי להריץ את הבדיקה המקדימה לפני שמשדרגים לגרסה ראשית.

כשמריצים את הבדיקה המקדימה, קורה אחד מהדברים הבאים:

  • לא נמצאו בעיות: הבדיקה המקדימה הסתיימה בהצלחה ולא נמצאו בעיות.
  • נמצאו בעיות: הבדיקה המקדימה הסתיימה בהצלחה, אבל נמצאו שגיאות שיחסמו את השדרוג. צריך לפתור את הבעיות לפני השדרוג.
  • Warnings found: הבדיקה המקדימה הסתיימה בהצלחה ונמצאו אזהרות. קוראים את האזהרות. מומלץ לטפל בכל הבעיות לפני שממשיכים בשדרוג.

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

מגבלות

כשמשתמשים בבדיקה המקדימה לשדרוג גרסה ראשית, חשוב לשים לב למגבלות הבאות:

  • מצב המכונה צריך להיות RUNNING.
  • המכונה חייבת להיות מכונה ראשית. הבדיקה המקדימה לא תומכת במכונות רפליקה.

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

    Operation failed because another operation was already in progress. Try
your request after the current operation is complete.

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

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

  • צריך לוודא ש-Cloud SQL Admin API מופעל במכונה.
  • מוודאים שיש לכם את הרשאת ה-IAM cloudsql.instances.preCheckMajorVersionUpgrade.

ביצוע הבדיקה המקדימה

כדי לבצע את הבדיקה המקדימה לשדרוג הגרסה הראשית:

המסוף

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

    כניסה לדף Cloud SQL Instances

  2. מוצאים את המכונה שרוצים לבצע בה את הבדיקה המקדימה. כדי לפתוח את הדף Overview של המכונה, לוחצים על שם המכונה.
  3. לוחצים על Edit.
  4. בקטע Instance info, לוחצים על Validate Upgrade.
  5. בתיבת הדו-שיח Validate upgrade, בוחרים את גרסת מסד הנתונים שרוצים לשדרג אליה ולוחצים על Validate.

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

  6. בסיום הבדיקה המקדימה, נפתח חלון חדש בשם Validate upgrade results. בחלון הזה מופיעים הממצאים של תהליך הבדיקה המקדימה. התוצאות יכולות להיות אחת מהאפשרויות הבאות:
    • אם אין שגיאות בפעולת הבדיקה המקדימה, לוחצים על Upgrade page כדי להתחיל את תהליך השדרוג.
    • אם פעולת הבדיקה המקדימה מכילה הודעות מסוג info, בודקים את הממצאים. כשתהיו מוכנים לשדרג, לחצו על Upgrade page כדי להתחיל את תהליך השדרוג.
    • אם הבדיקה המקדימה מכילה הודעות מסוג warning, בודקים את הממצאים. מומלץ לטפל באזהרות האלה לפני שממשיכים בשדרוג, אבל ההודעות האלה לא חוסמות את תהליך השדרוג.
    • אם פעולת הבדיקה המקדימה מכילה את הערך errors, בודקים את הממצאים. צריך לפתור את השגיאות ואז להפעיל מחדש את תהליך הבדיקה המקדימה. צריך לפתור את כל השגיאות לפני שמתחילים בתהליך השדרוג.

gcloud

  1. מריצים את הבדיקה המקדימה באמצעות gcloud sql instances pre-check-major-version-upgrade: 

    gcloud  sql instances pre-check-major-version-upgrade INSTANCE_NAME \
  --target-database-version=TARGET_DATABASE_VERSION \
  --project=PROJECT_ID \
  [--async]

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

    • ‫INSTANCE_NAME: שם המכונה.
    • ‫TARGET_DATABASE_VERSION: הגרסה הראשית שאליה רוצים לשדרג את המכונה. כדי למצוא את גרסת מסד הנתונים, עיינו במאמר תכנון שדרוג.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

    אופציונלי: משתמשים בדגל --async כדי להריץ את הפקודה באופן אסינכרוני.

  2. אם אתם משתמשים בדגל --async כדי להריץ את הפקודה pre-check-major-version-upgrade באופן אסינכרוני, בצעו את הפעולות הבאות:

    1. מקבלים את שם הפעולה של הבדיקה המקדימה:

      משתמשים בפקודה gcloud sql operations list עם הדגל --instance:

      gcloud sql operations list --instance=INSTANCE_NAME

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

      • ‫INSTANCE_NAME: שם המכונה.

    2. עוקבים אחרי הסטטוס של הבדיקה המקדימה.

      משתמשים בפקודה gcloud sql operations describe:

      gcloud sql operations describe OPERATION_NAME

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

      • ‫OPERATION_NAME: שם פעולת הבדיקה המקדימה שאוחזר בשלב הקודם.
  3. אם לא מריצים את הפקודה pre-check-major-version-upgrade באופן אסינכרוני, צריך לחכות עד שהבדיקה המקדימה תסתיים כדי לראות את התוצאות.

REST v1

  1. מריצים את הבדיקה המקדימה.

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

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

    ה-method של ה-HTTP וכתובת ה-URL: 

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

    תוכן בקשת JSON: 

    {
  "preCheckMajorVersionUpgradeContext": {
    "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
  }
}

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

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

    {
  "message": "Precheck description of finding",
  "message_type": "ERROR",
  "actions_required": [
    "Precheck action required to fix the finding"
  ]
}

  2. מקבלים את שם פעולת הבדיקה המקדימה.

    משתמשים בבקשה GET עם ה-method‏ operations.list אחרי שמחליפים את PROJECT_ID במזהה הפרויקט.

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

  3. עוקבים אחרי הסטטוס של הבדיקה המקדימה.

    משתמשים בבקשה GET עם השיטה operations.list:

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫OPERATION_NAME: שם פעולת הבדיקה המקדימה שאוחזר בשלב הקודם.

REST v1beta4

  1. מריצים את הבדיקה המקדימה.

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

    • ‫PROJECT_ID: מזהה הפרויקט
    • ‫INSTANCE_ID: מזהה המכונה
    • ‫TARGET_DATABASE_VERSION: הגרסה הראשית שאליה רוצים לשדרג. במאמר תכנון שדרוג מפורטות הגרסאות הזמינות של מסדי הנתונים.

    ה-method של ה-HTTP וכתובת ה-URL: 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

    תוכן בקשת JSON: 

    {
  "preCheckMajorVersionUpgradeContext": {
    "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
  }
}

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

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

    {
  "message": "Precheck description of finding",
  "message_type": "ERROR",
  "actions_required": [
    "Precheck action required to fix the finding"
  ]
}

  2. מקבלים את שם פעולת הבדיקה המקדימה.

    משתמשים בבקשה GET עם ה-method‏ operations.list אחרי שמחליפים את PROJECT_ID במזהה הפרויקט.

    GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

  3. עוקבים אחרי הסטטוס של הבדיקה המקדימה.

    משתמשים בבקשה GET עם השיטה operations.list:

    GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operation/OPERATION_NAME

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫operation_name: שם פעולת הבדיקה המקדימה שאוחזר בשלב הקודם.

בדיקת הממצאים של הבדיקה המקדימה

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

מוכן לשדרוג

אם הבדיקה המקדימה מסתיימת בהצלחה והמערך preCheckResponse ריק, זה אומר שלא נמצאו בעיות או אזהרות. המכונה מוכנה לשדרוג הגרסה הראשית. כדי להמשיך, קראו את המאמר ביצוע שדרוג לגרסה ראשית.

לא מוכן לשדרוג

אם הבדיקה המקדימה בוצעה בהצלחה והמערך preCheckResponse מכיל בעיות, המכונה לא מוכנה לשדרוג ודורשת התייחסות. יכול להיות שהבעיות שזוהו יחסמו את השדרוג, ויכול להיות שלא. הבעיות האלה מצוינות בpreCheckResponse עם סוגי ההודעות הבאים:

סוג תיאור השדרוג נחסם?
INFO הודעת מידע. לא
WARNING נמצאה בעיה פוטנציאלית, אבל היא לא חוסמת את השדרוג. Cloud SQL ממליץ לבדוק את האזהרה ולטפל בה לפני השדרוג כדי להבטיח תאימות מלאה. לא
ERROR נמצאה בעיה קריטית שמונעת את השדרוג. הבעיות האלה עלולות לגרום לשדרוג להיכשל. צריך לפתור אותן לפני שמשדרגים את המכונה. כן
אם במכונה שלכם יש רק הודעות מסוג INFO או WARNING, אתם יכולים לשדרג אותה, אבל יכול להיות שיהיו בעיות אחרי השדרוג. מומלץ לבדוק את פרטי ההודעה ולפתור את הבעיה לפני השדרוג. אם במכונה שלכם מופיעות הודעות מסוג ERROR, אתם צריכים לפתור את הבעיות האלה לפני השדרוג.

כל סוג בעיה כולל שדה message ושדה actions_required. כדאי לבדוק כל בעיה כדי להבין מה הסוג שלה ואיך לפתור אותה. למידע נוסף על בעיות נפוצות והפתרונות שלהן, קראו את המאמר שגיאות נפוצות בבדיקה המקדימה של שדרוג גרסה ראשית.

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

שדרוג הגרסה הראשית

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

שדרוג הגרסה הראשית של מכונה אחת

כשמפעילים פעולת שדרוג למכונה אחת, Cloud SQL מבצע את הפעולות הבאות:

  1. בדיקת ההגדרות של המכונה כדי לוודא שהיא תואמת לשדרוג.
  2. אחרי ש-Cloud SQL מאמת את ההגדרה, המכונה לא זמינה ב-Cloud SQL.
  3. מבצע גיבוי לפני השדרוג.
  4. מבצע את השדרוג במכונה.
  5. הפעלת המכונה.
  6. מבצע גיבוי אחרי השדרוג.

המסוף

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

    כניסה לדף Cloud SQL Instances

  2. כדי לפתוח את הדף Overview של מכונה, לוחצים על שם המכונה.
  3. לוחצים על Edit.
  4. בקטע Instance info, לוחצים על הלחצן Upgrade ומאשרים שרוצים לעבור לדף השדרוג.
  5. בדף Choose a database version, לוחצים על הרשימה Database version for upgrade ובוחרים באחת מהגרסאות הראשיות הזמינות של מסד הנתונים.
  6. לוחצים על Continue.
  7. בתיבה Instance ID, מזינים את שם המכונה ולוחצים על הכפתור Start upgrade.
הפעולה נמשכת כמה דקות.

מוודאים שהגרסה הראשית המשודרגת של מסד הנתונים מופיעה מתחת לשם המכונה בדף Overview של המכונה.

gcloud

  1. מתחילים את השדרוג.

    משתמשים בפקודה gcloud sql instances patch עם הדגל --database-version.

    לפני שמריצים את הפקודה, מחליפים את הערכים הבאים:

    • ‫INSTANCE_NAME: שם המכונה.
    • ‫DATABASE_VERSION: ה-enum של הגרסה הראשית של מסד הנתונים, שצריכה להיות מאוחרת יותר מהגרסה הנוכחית. מציינים גרסה של מסד נתונים לגרסה ראשית שזמינה כיעד לשדרוג של המכונה. אפשר לקבל את ה-enum הזה בשלב הראשון של התכנון לשדרוג. אם אתם צריכים רשימה מלאה של ערכי enum של גרסאות מסדי נתונים, עיינו במאמר SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

    שדרוג של גרסה ראשית נמשך כמה דקות. יכול להיות שתופיע הודעה שהפעולה נמשכת יותר זמן מהצפוי. אתם יכולים להתעלם מההודעה או להריץ את הפקודה gcloud sql operations wait כדי לסגור אותה.

  2. מאתרים את שם פעולת השדרוג.

    משתמשים בפקודה gcloud sql operations list עם הדגל --instance.

    לפני שמריצים את הפקודה, מחליפים את הערכים הבאים: * INSTANCE_NAME: שם המכונה. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. עוקבים אחרי סטטוס השדרוג.

    משתמשים בפקודה gcloud sql operations describe.

    לפני שמריצים את הפקודה, מחליפים את המשתנה OPERATION בשם של פעולת השדרוג שאוחזר בשלב הקודם. 

    gcloud sql operations describe OPERATION

REST v1

  1. מתחילים את השדרוג במקום.

    משתמשים בבקשת PATCH עם ה-method‏ instances:patch.

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

    • ‫PROJECT_ID: מזהה הפרויקט.
    • ‫INSTANCE_NAME: שם המכונה.

    ה-method של ה-HTTP וכתובת ה-URL: 

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

    תוכן בקשת JSON: 

    {
  "databaseVersion": DATABASE_VERSION
}

    מחליפים את DATABASE_VERSION בערך ה-enum של הגרסה הראשית של מסד הנתונים, שחייבת להיות מאוחרת יותר מהגרסה הנוכחית. מציינים גרסה של מסד נתונים לגרסה ראשית שזמינה כיעד לשדרוג של המכונה. אפשר לקבל את ה-enum הזה בשלב הראשון של התכנון לשדרוג. לרשימה המלאה של ערכי ה-enum של גרסאות מסדי הנתונים, ראו SqlDatabaseVersion.

  2. מאתרים את שם פעולת השדרוג.

    משתמשים בבקשת GET עם ה-method‏ operations.list, אחרי שמחליפים את PROJECT_ID במזהה הפרויקט.

    ה-method של ה-HTTP וכתובת ה-URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. עוקבים אחרי סטטוס השדרוג.

    משתמשים בבקשת GET עם השיטה operations.get אחרי שמחליפים את המשתנים הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט.
    • ‫OPERATION_NAME: שם פעולת השדרוג שאוחזר בשלב הקודם.

    ה-method של ה-HTTP וכתובת ה-URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Terraform

כדי לשדרג את הגרסה הראשית של מסד הנתונים באמצעות Terraform, צריך להגדיר את הארגומנט database_version בהגדרה של המשאב google_sql_database_instance לגרסת היעד הראשית. צריך להשתמש בספק Terraform ל- Google Cloud בגרסה 4.34.0 ואילך.

הדוגמאות הבאות ממחישות הגדרה בסיסית של google_sql_database_instance. כדי לשדרג את הגרסה הראשית, מגדירים את הארגומנט database_version לגרסה הראשית הרלוונטית.

resource "google_sql_database_instance" "default" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
}

מבצעים את השינויים הבאים בארגומנטים של Terraform:

  • ‫database_version: מגדירים את הגרסה הראשית של היעד לשדרוג.
  • ‫deletion_protection: מגדיר את אמצעי ההגנה ברמת הבסיס (root) של Terraform מפני מחיקת מכונות.
    • ‫true: מונעת מ-Terraform להרוס את המכונה. כל פעולה של Terraform שמיועדת למחוק את המשאב הזה נחסמת.
    • ‫false: מאפשר ל-Terraform למחוק את המכונה.

בדיקת התוכנית ב-Terraform

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

  • ‫~ עדכון במקום: הסמל הזה מציין ש-Terraform תשנה את המכונה הקיימת. זו התוצאה הצפויה והבטוחה של שדרוג גרסה ראשית במקום כשמשנים את database_version.
  • ‫+/- יצירה מחדש (החלפה כפויה): הסמל הזה מציין ש-Terraform מתכננת להרוס את המכונה הנוכחית וליצור מכונה חדשה.
    • אם הערך של deletion_protection מוגדר ל-true, תופיע שגיאה ב-Terraform וההחלפה המסוכנת הזו תיחסם. תצטרכו להגדיר במפורש את deletion_protection = false בהגדרות ולהריץ שוב את terraform apply כדי לעדכן את המצב, לפני ש-apply הבא יאפשר את ההשמדה והיצירה מחדש.
    • אם המדיניות deletion_protection מוגדרת לערך false, המדיניות terraform apply תמשיך עם אובדן הנתונים.

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

אחרי שבודקים את הפלט של terraform plan כדי לוודא שהוא מציין רק עדכון במקום (~) לשינוי גרסת מסד הנתונים, מחילים את ההגדרות.

כך מחילים את ההגדרות של 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.

כששולחים בקשה לשדרוג במקום, Cloud SQL מבצע קודם בדיקה לפני השדרוג. אם המערכת של Cloud SQL תקבע שהמכונה לא מוכנה לשדרוג, בקשת השדרוג תיכשל ותופיע הודעה עם הצעה לפתרון הבעיה. פתרון בעיות בשדרוג גרסה ראשית

הכללת רפליקות בשדרוג הגרסה הראשית

אם למכונה הראשית יש רפליקות, אפשר לכלול את כולן בשדרוג. ב-Cloud SQL אפשר לשדרג את כל הרפליקות של המכונה הראשית, כולל רפליקות באזורים שונים ורפליקות מדורגות.

כשכוללים רפליקות בשדרוג של גרסה ראשית, Cloud SQL מבצע את הפעולות הבאות:

  1. בדיקה של הגדרות המכונה הראשית והרפליקות כדי לוודא שהן תואמות לשדרוג.
  2. המכונה הראשית לא זמינה.
  3. יצירת גיבוי של המכונה הראשית לפני השדרוג.
  4. הפעולה הזו מפסיקה את השכפול של כל הרפליקות.
  5. מבצע את השדרוג במכונה הראשית.
  6. אם השדרוג של המכונה הראשית מצליח, המכונה הראשית הופכת שוב לזמינה ומתחילה מחדש את הרפליקציה.
  7. המערכת של Cloud SQL יוצרת גיבוי של המכונה הראשית אחרי השדרוג.
  8. מערכת Cloud SQL משדרגת את כל הרפליקות.

גם אם השדרוג של גרסה ראשית של רפליקה נכשל, המכונה הראשית ממשיכה להיות זמינה.

כדי לכלול רפליקות בשדרוג של גרסה ראשית, אי אפשר להשתמש במסוףGoogle Cloud או ב-Terraform. אפשר להשתמש רק ב-CLI של gcloud או ב-Cloud SQL Admin API.

gcloud

  1. מתחילים את השדרוג.

    משתמשים בפקודה gcloud sql instances patch עם הדגלים --database-version ו---include-replicas-for-major-version-upgrade.

    לפני שמריצים את הפקודה, מחליפים את הערכים הבאים:

    • ‫INSTANCE_NAME: השם של המכונה הראשית.
    • ‫DATABASE_VERSION: ה-enum של הגרסה הראשית של מסד הנתונים, שצריכה להיות מאוחרת יותר מהגרסה הנוכחית. מציינים גרסה של מסד נתונים לגרסה ראשית שזמינה כיעד לשדרוג של המכונה. אפשר לקבל את ה-enum הזה בשלב הראשון של התכנון לשדרוג. אם אתם צריכים רשימה מלאה של ערכי enum של גרסאות מסדי נתונים, עיינו במאמר SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
  --database-version=DATABASE_VERSION \
  --include-replicas-for-major-version-upgrade

    שדרוג של גרסה ראשית נמשך כמה דקות. יכול להיות שתופיע הודעה שהפעולה נמשכת יותר זמן מהצפוי. אתם יכולים להתעלם מההודעה או להריץ את הפקודה gcloud sql operations wait כדי לסגור אותה. שדרוג הרפליקות יכול להימשך כמה דקות. כדי לבדוק את סטטוס השדרוג:

  2. מאתרים את שם פעולת השדרוג.

    משתמשים בפקודה gcloud sql operations list עם הדגל --instance.

    לפני שמריצים את הפקודה, מחליפים את המשתנה INSTANCE_NAME בשם המכונה. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. עוקבים אחרי סטטוס השדרוג.

    משתמשים בפקודה gcloud sql operations describe.

    לפני שמריצים את הפקודה, מחליפים את המשתנה OPERATION בשם של פעולת השדרוג שאוחזר בשלב הקודם. 

    gcloud sql operations describe OPERATION

REST

  1. מתחילים את השדרוג במקום.

    משתמשים בבקשת PATCH עם ה-method‏ instances:patch.

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

    • ‫PROJECT_ID: מזהה הפרויקט
    • ‫INSTANCE_NAME: שם המכונה.

    ה-method של ה-HTTP וכתובת ה-URL: 

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

    תוכן בקשת JSON: 

    {
  "databaseVersion": DATABASE_VERSION
  "includeReplicasForMajorVersionUpgrade": true
}
    • מחליפים את DATABASE_VERSION בערך ה-enum של הגרסה הראשית של מסד הנתונים, שחייבת להיות מאוחרת יותר מהגרסה הנוכחית. מציינים גרסה של מסד נתונים לגרסה ראשית שזמינה כיעד לשדרוג של המכונה. אפשר לקבל את ה-enum הזה בשלב הראשון של התכנון לשדרוג. לרשימה המלאה של ערכי ה-enum של גרסאות מסדי הנתונים, ראו SqlDatabaseVersion.
    • בשדה includeReplicasForMajorVersionUpgrade, מציינים את הערך true.

  2. מאתרים את שם פעולת השדרוג.

    משתמשים בבקשת GET עם ה-method‏ operations.list, אחרי שמחליפים את PROJECT_ID במזהה הפרויקט.

    ה-method של ה-HTTP וכתובת ה-URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. עוקבים אחרי סטטוס השדרוג.

    משתמשים בבקשת GET עם השיטה operations.get אחרי שמחליפים את המשתנים הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט
    • ‫OPERATION_NAME: שם פעולת השדרוג שאוחזר בשלב הקודם.

    ה-method של ה-HTTP וכתובת ה-URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

גיבויים של שדרוגים אוטומטיים

כשמבצעים שדרוג גרסה ראשית, Cloud SQL יוצר באופן אוטומטי שני גיבויים על פי דרישה, שנקראים 'גיבויי שדרוג':

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

כשמציגים את רשימת הגיבויים, הגיבויים של השדרוג מופיעים עם הסוג On-demand. הגיבויים של השדרוג מסומנים בתווית כדי שתוכלו לזהות אותם במהירות. לדוגמה, אם משדרגים מ-PostgreSQL 14 ל-PostgreSQL 15, הגיבוי שלפני השדרוג מסומן בתווית Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. והגיבוי שאחרי השדרוג מסומן בתווית Post-upgrade backup, POSTGRES_14 to POSTGRES_15..

כמו גיבויים אחרים על פי דרישה, גיבויי השדרוג נשמרים עד שמוחקים אותם או את המכונה. אם הפעלתם את PITR, אתם לא יכולים למחוק את הגיבויים של השדרוג כל עוד הם נמצאים בחלון השמירה. אם אתם צריכים למחוק את הגיבויים של השדרוג, אתם צריכים להשבית את ה-PITR או לחכות עד שהגיבויים של השדרוג לא יהיו יותר בחלון השמירה.

ביטול השדרוג של הגרסה הראשית

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

חלון זמנים לביטול

שדרוג גרסה ראשית כולל רצף של שלבים. אפשר לבטל רק במהלך שלב השדרוג הראשי.

  1. אתחול: Cloud SQL מכין את המכונה והמשאבים שלה. אי אפשר לבטל את ההעברה בשלב הזה.

  2. שלב השדרוג הראשי: Cloud SQL משדרג באופן פעיל את הנתונים לגרסה הראשית החדשה. אפשר לבטל רק בשלב הזה.

  3. סיום: המכונה משלימה את השדרוג ומבצעת אימותים סופיים.

כדי לדעת מתי המכונה נכנסה לשלב שבו אפשר לבטל את השדרוג, בודקים אם יומני השדרוג זמינים. יומני השדרוג זמינים בכתובת projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log

כשרשומות ביומן מתחילות להופיע בקובץ היומן הזה, שלב השדרוג הראשי פעיל ואפשר לבטל את הפעולה.

ביצוע הביטול

כדי לבטל שדרוג גרסה ראשית במקום, צריך את מזהה הפעולה. צריך לציין את המזהה הזה בפקודה של gcloud או של ה-API בארכיטקטורת REST, כדי ש-Cloud SQL ידע איזו פעולה לבטל.

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

gcloud

  1. משיגים את מזהה פעולת השדרוג.

    משתמשים בפקודה gcloud sql operations list עם הדגל --instance:

    gcloud sql operations list --instance=INSTANCE_NAME

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

    • ‫INSTANCE_NAME: שם המכונה.

  2. לבטל את השדרוג.

    משתמשים בפקודה gcloud sql operations cancel:

    gcloud sql operations cancel OPERATION_ID

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

    • ‫OPERATION_ID: מזהה הפעולה שאוחזר בשלב הקודם.

  3. בודקים את הסטטוס "בוטל".

    משתמשים בפקודה gcloud sql operations describe:

    gcloud sql operations describe OPERATION_ID

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

    • ‫OPERATION_ID: מזהה הפעולה שאוחזר בשלב הראשון.

REST v1

  1. משיגים את מזהה פעולת השדרוג.

    משתמשים בבקשת GET עם ה-method‏ operations.list, אחרי שמחליפים את PROJECT_ID במזהה הפרויקט.

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

  2. לבטל את השדרוג.

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫OPERATION_ID: מזהה הפעולה שאוחזר בשלב הקודם.

    ה-method של ה-HTTP וכתובת ה-URL: 

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID/cancel

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

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

    הקריאה הזו ל-API בארכיטקטורת REST לא מחזירה תשובה.

  3. בודקים את הסטטוס "בוטל".

    משתמשים בבקשת GET עם השיטה operations.list:

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫OPERATION_ID: מזהה הפעולה שאוחזר בשלב הראשון.

REST v1beta4

  1. משיגים את מזהה פעולת השדרוג.

    משתמשים בבקשת GET עם ה-method‏ operations.list, אחרי שמחליפים את PROJECT_ID במזהה הפרויקט.

    GET https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

  2. לבטל את השדרוג.

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫OPERATION_ID: מזהה הפעולה שאוחזר בשלב הקודם.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID/cancel

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

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

הקריאה הזו ל-API בארכיטקטורת REST לא מחזירה תשובה.

  1. בודקים את הסטטוס "בוטל".

    משתמשים בבקשת GET עם השיטה operations.list:

    GET https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫OPERATION_ID: מזהה הפעולה שאוחזר בשלב הראשון.

אם הבקשה לביטול תאושר, Cloud SQL יפסיק את תהליך השדרוג ויחזיר את המכונה למצב המקורי שלה.

פתרון בעיות בביטול

שגיאה פתרון בעיות

הודעת שגיאה: The operation OPERATION_ID cannot be canceled at the moment. Please retry in approximately 5-10 minutes

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

הודעת שגיאה: The operation OPERATION_ID cannot be cancelled as it has passed the cancellable state. The operation is in its final stage and should complete soon.

 תהליך השדרוג עבר את השלב שבו אפשר לבטל אותו. אי אפשר לבטל את השדרוג, והוא אמור להסתיים בקרוב.

הודעת שגיאה: You can't cancel operation OPERATION_ID because it isn't in progress.

 הפעולה כבר הסתיימה, בהצלחה או בכישלון, ואי אפשר לבטל אותה.

הודעות שגיאה:

  • You can't cancel operation OPERATION_ID because Cloud SQL doesn't support the cancellation of this OPERATION_TYPE operation.
  • The operation OPERATION_ID cannot be cancelled.
 השגיאה הזו בדרך כלל מתרחשת כשמעבירים את הערך הלא נכון של OPERATION_ID לפקודת הביטול, ובאופן ספציפי, המזהה של סוג פעולה שלא תומך בביטול. מוודאים שמשתמשים ב-OPERATION_ID שמשויך לשדרוג הגרסה הראשית של מסד הנתונים במקום שרוצים לבטל.

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

השלמת השדרוג של הגרסה הראשית

אחרי שמסיימים לשדרג את המכונה הראשית, מבצעים את השלבים הבאים כדי להשלים את השדרוג:

  1. מרעננים את הנתונים הסטטיסטיים של מסד הנתונים.

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

  2. מבצעים בדיקות קבלה.

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

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

פתרון בעיות בשדרוג גרסה ראשית

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

אם בקשת השדרוג נכשלת, צריך לבדוק את התחביר של בקשת השדרוג. אם מבנה הבקשה תקין, נסו את ההצעות הבאות.

צפייה ביומני השגיאות

אם יש בעיות בבקשת שדרוג תקינה, Cloud SQL מפרסם יומני שגיאות ב-projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log. כל רשומה ביומן מכילה תווית עם מזהה המכונה, כדי לעזור לכם לזהות את המכונה שבה קרתה השגיאה בשדרוג. חפשו שגיאות שדרוג כאלה ופתרו אותן.

כדי לראות את יומני השגיאות, משתמשים במסוף Google Cloud:

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

    כניסה לדף Cloud SQL Instances

  2. כדי לפתוח את הדף Overview של מכונה, לוחצים על שם המכונה.

  3. בחלונית Operations and logs בדף Overview של המכונה, לוחצים על הקישור View PostgreSQL error logs.

    הדף Logs Explorer נפתח.

  4. כדי לראות את היומנים:

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

    מידע נוסף על מסנני שאילתות זמין במאמר שאילתות מתקדמות.

    • כדי לסנן את יומני השגיאות של השדרוג למכונה אחת, מזינים את השאילתה הבאה בתיבה Search all fields, אחרי שמחליפים את DATABASE_ID

    עם מזהה הפרויקט ואחריו שם המכונה בפורמט הזה: project_id:instance_name.

    resource.type="cloudsql_database"
resource.labels.database_id="DATABASE_ID"
logName : "projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

    לדוגמה, כדי לסנן את יומני השגיאות של השדרוג לפי מכונה בשם shopping-db שפועלת בפרויקט buylots, משתמשים במסנן השאילתה הבא:

     resource.type="cloudsql_database"
 resource.labels.database_id="buylots:shopping-db"
 logName : "projects/buylots/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

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

    • מקרה חירום
    • התראה
    • קריטית
    • שגיאה

רשומות ביומן עם הקידומת pg_upgrade_dump מציינות שהייתה שגיאה בשדרוג. לדוגמה:

pg_upgrade_dump: error: query failed: ERROR: out of shared memory
HINT: You might need to increase max_locks_per_transaction.

בנוסף, ברשומות ביומן עם שם קובץ משני .txt יכולות להופיע שגיאות אחרות שכדאי לפתור לפני שמנסים לשדרג שוב.

כל שמות הקבצים נמצאים בקובץ postgres-upgrade.log. כדי לאתר שם קובץ, מעיינים בשדה labels.FILE_NAME.

שמות הקבצים שעשויים להכיל שגיאות שצריך לפתור כוללים:

  • tables_with_oids.txt: הקובץ הזה מכיל טבלאות שרשומות עם מזהי אובייקטים (OID). צריך למחוק את הטבלאות או לשנות אותן כך שלא ישתמשו ב-OID.
  • tables_using_composite.txt: הקובץ הזה מכיל טבלאות שמופיעות ברשימה באמצעות סוגים מורכבים שמוגדרים על ידי המערכת. צריך למחוק את הטבלאות או לשנות אותן כך שלא ישתמשו בסוגים המורכבים האלה.
  • tables_using_unknown.txt: הקובץ הזה מכיל טבלאות שמופיעות ברשימה באמצעות סוג הנתונים UNKNOWN. צריך למחוק את הטבלאות או לשנות אותן כך שלא ישתמשו בסוג הנתונים הזה.
  • tables_using_sql_identifier.txt: הקובץ הזה מכיל טבלאות שרשומות באמצעות סוג הנתונים SQL_IDENTIFIER. צריך למחוק את הטבלאות או לשנות אותן כך שלא ישתמשו בסוג הנתונים הזה.
  • tables_using_reg.txt: הקובץ הזה מכיל טבלאות שמופיעות באמצעות סוג הנתונים REG* (לדוגמה, REGCOLLATION או REGNAMESPACE). צריך למחוק את הטבלאות או לשנות אותן כך שלא ישתמשו בסוג הנתונים הזה.
  • postfix_ops.txt: הקובץ הזה מכיל טבלאות שרשומות באמצעות אופרטורים של סיומת (אונריים ימניים). צריך למחוק את הטבלאות או לשנות אותן כך שלא ישתמשו באופרטורים האלה.

בדיקת הזיכרון

אם למכונה אין מספיק זיכרון משותף, יכול להיות שתופיע הודעת השגיאה הבאה: ERROR: out of shared memory.. השגיאה הזו צפויה להתרחש אם יש לכם יותר מ-10,000 טבלאות.

לפני שמנסים לשדרג, צריך להגדיר את הערך של הדגל max_locks_per_transaction למספר שגדול בערך פי שניים ממספר הטבלאות במכונה. המכונה מופעלת מחדש כשמשנים את הערך של הדגל הזה.

בודקים את קיבולת החיבורים

אם אין מספיק קיבולת חיבור במכונה, יכול להיות שתופיע הודעת השגיאה הבאה: ERROR: Insufficient connections.

ב-Cloud SQL מומלץ להגדיל את הערך של הדגל max_connections במספר מסדי הנתונים במכונה. המכונה מופעלת מחדש כשמשנים את הערך של הדגל הזה.

בודקים אם יש הפניה לא ברורה לעמודה

‫Cloud SQL מבצע באופן אוטומטי בדיקה לפני השדרוג כדי לזהות תצוגות שמוגדרות על ידי המשתמשים ותלויות בתצוגות של קטלוג המערכת, כמו pg_stat_activity או pg_stat_replication. מבנה העמודות של תצוגות קטלוג המערכת האלה יכול להשתנות בין גרסאות עיקריות של PostgreSQL. אם יש לכם תצוגות שselect * או מסתמכות על סדר העמודות של תצוגות המערכת האלה, יכול להיות שהן לא יהיו תואמות אחרי השדרוג, ותתקבל שגיאה כמו ERROR: column reference "column_name" is ambiguous.

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

הודעת שגיאה לדוגמה

  • לבעיות שקשורות ל-pg_stat_activity: 

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_activity before attempting an upgrade:
(database: my_db, schema name: public, view name: my_stat_activity_view)

  • לבעיות שקשורות ל-pg_stat_replication:

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_replication before attempting an upgrade:
(database: my_db, schema name: public, view name: my_replication_stats_view)

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

  1. אפשר להסיר את התצוגות האלה באמצעות DROP VIEW view_name;.

  2. מנסים שוב לשדרג את הגרסה הראשית.

  3. אחרי שהשדרוג מסתיים, יוצרים מחדש את התצוגות. מוודאים שההגדרות של התצוגות החדשות תואמות לסכימה של התצוגות בקטלוג המערכת בגרסה הנוכחית של PostgreSQL. כדי למנוע בעיות בעתיד, יכול להיות שתצטרכו לציין עמודות באופן מפורש במקום להשתמש ב-select *.

לדוגמה מפורטת יותר של הבעיה ולתובנות נוספות, אפשר לעיין בדיון הזה ב-Stack Overflow.

בדיקה אם יש פונקציות שמחזירות קבוצת שורות (SRF) בהצהרות CASE

אם אתם משדרגים את המכונה מ-PostgreSQL 9.6 ומשתמשים בפונקציות להחזרת קבוצות בהצהרות CASE, יכול להיות שתופיע הודעת השגיאה ERROR: set-returning functions are not allowed in CASE. הבעיה הזו מתרחשת כי מגרסה 10 ואילך אסור להשתמש בפונקציות להחזרת קבוצות בהצהרות CASE.

כדי לפתור את הבעיה ולשדרג את המכונה, צריך לוודא שכל הצהרות CASE שמשתמשות בפונקציות להחזרת קבוצות משתנות כדי למנוע את השימוש בהן לפני שמנסים שוב לשדרג. אלה כמה מה-SRF הנפוצים:

  • unnest()‎
  • generate_series()
  • array_agg()
  • regexp_split_to_table()
  • jsonb_array_elements()
  • json_array_elements()
  • sonb_each()
  • json_each()

בדיקת הצפיות שנוצרו בקאסטים בהתאמה אישית

אם יש לכם תצוגה שנוצרה בהמרה מותאמת אישית, תופיע הודעת שגיאה דומה לזו: ERROR: cannot cast type <type_1> to <type_2>. הבעיה הזו נגרמת בגלל בעיות בהרשאות של העברות בהתאמה אישית.

כדי לפתור את הבעיה, צריך לעדכן את המכונה לגרסה [PostgreSQL version].R20240910.01_02

מידע נוסף זמין במאמר תחזוקה בשירות עצמי.

בדיקת הבעלות על הטריגר של האירוע

ב-Cloud SQL, כל הטריגרים של האירועים חייבים להיות בבעלות של משתמש עם התפקיד cloudsqlsuperuser. ב-Cloud SQL מתבצעת בדיקה לפני השדרוג כדי לאמת את הבעלות על כל הטריגרים של האירועים. אם טריגר של אירוע נמצא בבעלות של משתמש שאין לו את התפקיד cloudsqlsuperuser, תהליך השדרוג נעצר ויכול להיות שתופיע הודעת שגיאה, כמו:

Please ensure that the owners of all event triggers have the cloudsqlsuperuser
role assigned to them before attempting an upgrade:
(database: your_db, triggerName your_trigger, owner: non_super_user)

כדי לפתור את הבעיה, צריך לשנות את הבעלים של הטריגר של האירוע למשתמש עם התפקיד cloudsqlsuperuser, כמו postgres, או להקצות את התפקיד cloudsqlsuperuser לבעלים הנוכחי.

כדי לזהות טריגרים של אירועים שהבעלים שלהם לא קיבלו את התפקיד הנדרש, מריצים את הפקודה הבאה:

SELECT
  t.evtname AS trigger_name,
  r.rolname AS current_owner
FROM pg_event_trigger t
JOIN pg_roles r ON t.evtowner = r.oid
WHERE NOT pg_has_role(r.rolname, 'cloudsqlsuperuser', 'member');

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

בדיקת עמודות שנוצרו מטבלאות שלא נרשמו ביומן

אם יש לכם טבלה לא מתועדת עם עמודות שנוצרו, יכול להיות שתופיע הודעת השגיאה ERROR: unexpected request for new relfilenumber in binary upgrade mode. הבעיה הזו מתרחשת בגלל פערים במאפייני השמירה בין הטבלאות לבין הרצפים שלהן בעמודות שנוצרו.

כדי לפתור את הבעיה הזו:

  1. הסרת טבלאות שלא נרשמו ביומן: אם אפשר, הסירו טבלאות שלא נרשמו ביומן ומקושרות לעמודות שנוצרו. לפני שממשיכים, חשוב לוודא שאפשר למנוע אובדן נתונים.
  2. ‫Convert to permanent tables: באופן זמני, ממירים טבלאות שלא נרשמו ביומן לטבלאות קבועות לפי השלבים הבאים:
    1. המרת הטבלה לטבלה מתועדת ALTER TABLE SET LOGGED;
    2. שדרוג לגרסה ראשית
    3. ממירים את הטבלה בחזרה לטבלה שלא נרשמת ביומן ALTER TABLE SET UNLOGGED

כדי לזהות את כל הטבלאות האלה, אפשר להשתמש בשאילתה הבאה :

SELECT
  relnamespace::regnamespace,
  c.relname AS table_name,
  a.attname AS column_name,
  a.attidentity AS identity_type
FROM
  pg_catalog.pg_class c
  JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
WHERE
  a.attidentity IN ('a', 'd') AND c.relkind = 'r' AND c.relpersistence = 'u'
ORDER BY c.relname, a.attname;

בדיקת הדגלים בהתאמה אישית של מכונת PostgreSQL

אם אתם משדרגים למכונה של PostgreSQL, גרסה 14 ומעלה, בדקו את השמות של הדגלים לניהול מסד הנתונים שהגדרתם למכונה. הסיבה לכך היא ש-PostgreSQL הוסיפה הגבלות על השמות המותרים לפרמטרים מותאמים אישית.

התו הראשון של דגל מותאם אישית לניהול מסד נתונים חייב להיות אות (A-Z או a-z). כל התווים הבאים יכולים להיות אלפאנומריים, התו המיוחד קו תחתון (_) או התו המיוחד סימן דולר ($).

הסרת התוספים

אם אתם משדרגים את המכונה של Cloud SQL, יכול להיות שתופיע הודעת השגיאה הבאה: pg_restore: error: could not execute query: ERROR: role "16447" does not exist.

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

  1. מסירים את התוספים pg_stat_statements ו-pgstattuple.
  2. מבצעים את השדרוג.
  3. מתקינים מחדש את התוספים.

פעולת MVU שפועלת במשך זמן רב יותר

יש שתי משימות בסיסיות שקשורות לשדרוג גרסה ראשית:

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

אם במכונה מתבצעת פעולת MAJOR_VERSION_UPGRADE שנמשכת יותר זמן מהצפוי, בדקו את יומני השגיאות של PostgreSQL. יכול להיות שהסיבה לכך היא בעיות נפוצות כמו:

  • מספר גדול של טבלאות, תצוגות או אינדקסים
  • מחסור במשאבים כמו מעבד (CPU) או זיכרון
  • עסקאות גדולות שמונעות את סגירת מסדי הנתונים כדי שתהליך השדרוג יוכל להתחיל. אפשר להשתמש במסוף Google Cloud כדי לבדוק את התהליכים הנוכחיים.

שגיאות נפוצות בבדיקה המקדימה של שדרוג גרסה ראשית

הבעיות שמתגלות בבדיקה המקדימה לשדרוג גרסה ראשית מתחלקות לקטגוריות הבאות:

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

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

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

תוספים לא תואמים

בטבלה הבאה מפורטות שגיאות נפוצות שקשורות לתוספים לא תואמים, שהבדיקה המקדימה לשדרוג הגרסה הראשית עשויה למצוא:

סוג דוגמה לשגיאה רזולוציה
תוסף לא נתמך או שהוצא משימוש Your installation contains unsupported extensions for the new version. These extensions must be removed before attempting an upgrade: (database: %s, Extension name: %s) מסירים את התוסף מכל מסדי הנתונים שמשתמשים בו באמצעות DROP EXTENSION $extension_name;.
גרסת התוסף לא תואמת Your installation contains incompatible version extensions. These extensions must be upgraded to a compatible version before attempting an upgrade: (database: %s, Extension name: %s) מעדכנים את התוסף לגרסה שפועלת עם גרסת היעד של Cloud SQL ל-PostgreSQL. במאמר הגדרת תוספים של Cloud SQL ל-PostgreSQL מפורטות הגרסאות התואמות.
‫PostGIS קבצים לא ארוזים PostGIS version upgrade has not been completed, unpackaged raster files present. Follow the steps at https://postgis.net/documentation/tips/tip-removing-raster-from-2-3/ to fix before major version upgrade. מנקים את קובצי הרסטר שלא נארזו.
PostGIS פונקציות שהוצאו משימוש PostGIS version upgrade has not been completed, deprecated functions present. Please drop all objects using deprecated functions and upgrade to a different version of PostGIS before major version upgrade. לפני שמשדרגים את התוסף PostGIS, צריך למצוא ולהסיר או לשנות את כל האובייקטים במסד הנתונים שמשתמשים בפונקציות PostGIS שהוצאו משימוש.
בעלות על התוסף Please ensure that the owner of the postgres_fdw extension has the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: my_db, extension name: postgres_fdw, owner: some_user) משנים את הבעלים של התוסף באמצעות ALTER EXTENSION postgres_fdw OWNER TO postgres;.

תלויות לא נתמכות

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

סוג דוגמה לשגיאה רזולוציה
בעלות על טריגר לאירוע Please ensure that the owners of all event triggers have the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: your_db, triggerName your_trigger, owner: non_super_user) מתחברים למסד הנתונים שזוהה באמצעות psql או Cloud SQL Studio, ומשנים את הבעלים של הטריגר למשתמש postgres.
הצהרות מוכנות שלא בוצעו Please commit/rollback the following usages of 'Uncommitted Prepared Statements'... (database: my_db, gid: my_prepared_xact) מבצעים commit או מבטלים את ההצהרה המוכנה.
דגלים שיצאו משימוש Your installation contains deprecated flags for the new version . These flags must be removed before attempting an upgrade: (database: %s, Flag name: %s) מסירים את הדגל לניהול מסד הנתונים מהגדרות המכונה.

חוסר תאימות של מסדי נתונים

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

סוג דוגמה לשגיאה רזולוציה
סוג נתונים לא ידוע Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) צריך להסיר את העמודה או הטבלה, או לשנות את סוג הנתונים של הטבלה באמצעות ALTER TABLE my_table ALTER COLUMN my_column TYPE TEXT;.
סוג הנתונים reg* Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) צריך להסיר את העמודה או לשנות את סוג הנתונים שלה.
סוג הנתונים שהוסר Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: ... צריך להמיר ל-TEXT, ל-timestamptz או לסוג נתונים מתאים אחר.
​​aclitem פורמט פנימי Please remove the following usages of 'aclitem' data types before attempting an upgrade: ... להפסיק להשתמש ב-aclitem בהגדרות של טבלאות מסד הנתונים.
סוגי נתונים מורכבים שמוגדרים על ידי המערכת Please remove the following usages of 'composite' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) משנים את העמודות שזוהו כך שישתמשו בסוג מורכב שמוגדר על ידי המשתמש או בסוג נתונים רגיל. יכול להיות שסוגי הקומפוזיט של המערכת לא יהיו עקביים בגרסאות הראשיות.
טבלאות עם OIDS Please remove the following usages of tables with OIDs before attempting an upgrade: (database: my_db, relation: my_table) מעדכנים את הטבלה באמצעות ALTER TABLE my_table SET WITHOUT OIDS;.
אופרטורים של postfix בהגדרת המשתמש Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: my_db, operation id: 12345, operation namespace: public, operation name: !!, type namespace: public, type name: mytype) מסירים את האופרטורים המותאמים אישית של postfix. ‫יכול להיות שתצטרכו לשכתב את הקוד כדי להשתמש באופרטורים של קידומת או בקריאות לפונקציות במקום זאת.
פונקציות פולימורפיות לא תואמות Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: my_db, object kind: function, object name: public.my_poly_func) כדי להסיר פונקציות פולימורפיות לא תואמות, צריך להסיר או לשנות את הפונקציה. יכול להיות שתצטרכו לשנות את החתימות או את הלוגיקה של הפונקציות כדי שהן יפעלו עם Cloud SQL ל-PostgreSQL בגרסה 14 ואילך.
המרות קידוד שמוגדרות על ידי המשתמש Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: my_db, namespace name: public, encoding conversions name: my_encoding_conv) הסרת המרת הקידוד שהוגדרה על ידי המשתמש. יכול להיות שתצטרכו ליצור אותו מחדש אחרי השדרוג עם חתימה שפועלת בגרסה החדשה.
בודקים אם יש הפניה לא ברורה לעמודה מערכת Cloud SQL בודקת באופן אוטומטי תצוגות שהוגדרו על ידי המשתמשים ומסתמכות על תצוגות של קטלוג המערכת. מבנה העמודות של תצוגות קטלוג המערכת האלה עשוי להשתנות בין גרסאות עיקריות.

Please remove the following usages of views that depend on functions returning data types of pg_stat_activity before attempting an upgrade: (database: my_db, schema name: public, view name: my_stat_activity_view) 		מוצאים את התצוגות שמופיעות בהודעת השגיאה ומסירים אותן באמצעות הפקודה DROP VIEW. אחרי השדרוג, צריך ליצור מחדש את התצוגות המפורטות.
טבלאות שלא נרשמו ביומן עם עמודות שנוצרו או רצפים שנרשמו ביומן Please drop the following usages of 'Unlogged Tables with Logged Sequence' before attempting an upgrade: (database: your_db, table name: problematic_table) אפשר להמיר את הטבלה ל-LOGGED או להסיר אותה באמצעות הפקודה DROP TABLE. יוצרים מחדש את הטבלה אחרי השדרוג.
פתרון הבעיה של נתיב חיפוש ריק Please update the search path of the 'll_to_earth' function (database: your_db, search path: ) התוסף earthdistance משתמש ב-earth וב-cube types בלי לציין את נתיב החיפוש של הפונקציה. מעדכנים את נתיב החיפוש באמצעות ALTER FUNCTION ll_to_earth SET search_path = public;.

שחזור המכונה הראשית לגרסה הראשית הקודמת

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

כדי לשחזר מכונה ראשית לגרסה הקודמת, מבצעים את השלבים הבאים:

  1. מזהים את הגיבוי שנוצר לפני השדרוג.

    גיבויים של שדרוגים אוטומטיים

  2. יוצרים מכונה לשחזור.

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

  3. משחזרים את הגיבוי שנוצר לפני השדרוג.

    משחזרים את הגיבוי שנוצר לפני השדרוג למכונה לשחזור. הפעולה עשויה להימשך כמה דקות.

  4. מוסיפים את העותקים לקריאה בלבד.

    אם אתם משתמשים בעותקים לקריאה בלבד, הוסיפו אותם בנפרד.

  5. מקשרים את האפליקציה.

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

שאלות נפוצות

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

האם המכונה שלי לא זמינה במהלך השדרוג?
כן. המכונה לא תהיה זמינה לפרק זמן מסוים בזמן ש-Cloud SQL מבצע את השדרוג.
כמה זמן נמשך השדרוג?

שדרוג של מכונה אחת נמשך בדרך כלל פחות מ-10 דקות. אם למכונה יש מספר קטן של מעבדי vCPU או זיכרון, יכול להיות שהשדרוג יימשך יותר זמן.

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

אפשר לעקוב אחרי כל שלב בתהליך השדרוג?
ב-Cloud SQL אפשר לעקוב אחרי פעולת השדרוג ולראות אם היא עדיין מתבצעת, אבל אי אפשר לעקוב אחרי השלבים הנפרדים בכל שדרוג.
האם אפשר לבטל את השדרוג אחרי שהוא התחיל?
כן, אבל רק בתנאים ספציפיים. אפשר לבטל את הפעולה במהלך שלב השדרוג הראשי. בקטע ביטול השדרוג של הגרסה הראשית מוסבר איך לזהות את חלון הזמן שבו אפשר לבטל את השדרוג. בנוסף, אי אפשר לבטל אם כוללים רפליקות לקריאה בלבד במכונה הראשית. כדי לשמור על האפשרות לבטל, צריך לשדרג בלי לכלול רפליקות לקריאה בלבד.
מה קורה להגדרות שלי במהלך השדרוג?

כשמשדרגים גרסה ראשית במקום, Cloud SQL שומר על הגדרות מסד הנתונים, כולל שם המכונה, כתובת ה-IP, ערכי הדגלים שהוגדרו במפורש ונתוני המשתמשים. עם זאת, יכול להיות שערך ברירת המחדל של משתני המערכת ישתנה. לדוגמה, ערך ברירת המחדל של הדגל password_encryption ב-PostgreSQL 13 ובגרסאות קודמות הוא md5. כשמשדרגים ל-PostgreSQL 14, ערך ברירת המחדל של הדגל הזה משתנה ל-scram-sha-256.

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

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