פריסה וניהול של סכימות ומחברים של SQL Connect

שירות Firebase SQL Connect מורכב משלושה רכיבים עיקריים:

  • מסד נתונים בסיסי של PostgreSQL עם סכימת SQL משלו
  • SQL Connect סכימת אפליקציה (מוצהרת בקובצי .gql)
  • מספר מחברים (מוצהרים בקובצי .gql ומוגדרים בקובצי connector.yaml).

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

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

מושגים חשובים בנושא פריסה

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

פריסות של סכימות

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

להעברות של סכימות יש שני מצבים שונים של אימות סכימות: strict ו-compatible.SQL Connect

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

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

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

    • סכימות
    • טבלאות
    • עמודות

פריסות של מחברים

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

‫SQL Connect משלב ניתוח של שינויים משמעותיים בעדכוני המחברים ב-CLI של Firebase.

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

לדוגמה:

  • שינויים במחבר שעשויים לשנות את התנהגות הלקוח כוללים הסרה של שדה שאפשר להשאיר ריק משאילתה ללא הערת סכימה של @retired.
  • שינויים במחבר שעלולים לגרום לבעיות בלקוחות כוללים שינוי של משתנה פעולה שניתן להגדיר כ-nullable ל-non-null ללא ערך ברירת מחדל, או שינוי של סוג הנתונים של שדה למשהו לא תואם (לדוגמה, String ל-Int).

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

פועלים לפי תהליך העבודה של הפריסה

אפשר לעבוד על פרויקט SQL Connect גם בספריית פרויקטים מקומית וגם במסוף Firebase.

תהליך פריסה מומלץ כולל:

  1. הצגת סכימות ומחברים שכרגע בפריסה עם firebase dataconnect:services:list.
  2. ניהול עדכוני סכימה.
    1. בודקים את ההבדלים בסכימת SQL בין מסד הנתונים Cloud SQL לבין הסכימה המקומית SQL Connect באמצעות firebase dataconnect:sql:diff.
    2. אם צריך, מבצעים מיגרציה של סכימת SQL באמצעות dataconnect:sql:migrate.
  3. ביצוע פריסות של סכימות וחיבורים על ידי הפעלת firebase deploy, לסכימה בלבד, למחברים בלבד או לשילובים של משאבים.

פריסה וניהול של משאבי SQL Connect

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

firebase dataconnect:services:list

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

כשמשתמשים בפקודה deploy, הדגל --only dataconnect מאפשר להפריד בין פריסות של SQL Connect לבין מוצרים אחרים בפרויקט.

פריסה רגילה

firebase deploy --only dataconnect

בפריסה רגילה, כלי ה-CLI של Firebase מנסה לפרוס את הסכימה ואת המחברים.

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

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

--force פריסת דגלים

firebase deploy --only dataconnect --force

אם אין בעיה עם אימות המחבר או סכימת ה-SQL, אפשר להריץ מחדש את הפקודה עם --force כדי להתעלם מהם.

הפקודה --force deploy עדיין בודקת אם סכימת ה-SQL תואמת לסכימת SQL Connect, מציגה אזהרה על חוסר תאימות ומציגה הנחיה.

פריסת המשאבים שנבחרו

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

firebase deploy --only dataconnect:serviceId:schema

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

firebase deploy --only dataconnect:serviceId:connectorId

לבסוף, אפשר לפרוס את הסכימה ואת כל המחברים לשירות יחיד.

firebase deploy --only dataconnect:serviceId

החזרה של פריסה

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

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

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

השוואת שינויים בסכימת SQL

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

firebase dataconnect:sql:diff

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

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

החל שינויים

כשמרוצים ומוכנים לפרוס את השינויים בסכימה Cloud SQLבמופע, מריצים את הפקודה firebase dataconnect:sql:migrate. תוצג לך בקשה לאשר את השינויים.

firebase dataconnect:sql:migrate [serviceId]

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

מעבר למצב קפדני או למצב תאימות

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

אפשר לשנות את ההתנהגות הזו על ידי שינוי קובץ dataconnect.yaml. מבטלים את ההערה של המפתח schemaValidation ומצהירים על COMPATIBLE כדי שרק השינויים הנדרשים יחולו בהעברות.

schemaValidation: "COMPATIBLE"

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

schemaValidation: "STRICT"

מידע נוסף זמין SQL Connectבמאמר בנושא הפניה ל-CLI.

עדכון מחברים

כשמריצים את הפקודה firebase deploy, ה-CLI מתחיל לעדכן את המחברים הרלוונטיים ומציג הודעות הערכה רלוונטיות ברמת אזהרה (עשויות להשפיע על התנהגות הלקוח) וברמת שינוי משמעותי (עשויות לגרום לשינוי משמעותי או בטוח שיגרם שינוי משמעותי).

ניהול עדכונים של מחברים באמצעות CLI

ההתנהגות של ה-CLI שונה מעט במצב אינטראקטיבי ובמצב לא אינטראקטיבי.

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

# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force

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

# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force

מידע נוסף זמין במדריך העזר ל-CLI.

שיטות מומלצות לניהול סכימות ומחברים

ב-Firebase מומלץ לפעול לפי כמה שיטות מומלצות בפרויקטים.SQL Connect

צמצום הסיכוי לשינויים שעלולים לגרום לכשל

  • מומלץ לשמור את קובצי הסכימה והמחבר של SQL Connect בבקרת מקור.
  • מומלץ להימנע משינויים שעלולים לשבור את התאימות, אם אפשר. דוגמאות נפוצות לשינויים שעלולים לשבור את התאימות:
    • הסרת שדה מהסכימה
    • הפיכת שדה שניתן להגדיר בו ערך null בסכימה לשדה שלא ניתן להגדיר בו ערך null (כלומר Int -> Int!)
    • שינוי השם של שדה בסכימה.
  • אם אתם צריכים להסיר שדה מהסכימה, כדאי לפצל את ההסרה לכמה פריסות כדי למזער את ההשפעה:
    • קודם צריך להסיר את כל ההפניות לשדה במחברים, ואז לפרוס את השינוי.
    • לאחר מכן, מעדכנים את האפליקציות כדי להשתמש ב-SDK החדש שנוצר.
    • לבסוף, מסירים את השדה מקובץ הסכימה .gql, מעבירים את סכימת ה-SQL ומבצעים פריסה נוספת.

שימוש במצב קפדני כשעובדים עם מסדי נתונים חדשים

אם אתם משתמשים ב-SQL Connect עם מסד נתונים חדש ומפתחים באופן פעיל את סכימת האפליקציה, ואתם רוצים לוודא שסכימת מסד הנתונים תהיה זהה לסכימת האפליקציה, אתם יכולים לציין schemaValidation: "STRICT" ב-dataconnect.yaml.

כך תוכלו לוודא שגם שינויים אופציונליים יחולו.

שימוש במצב תאימות כשבמסד הנתונים יש נתוני ייצור

אם אתם מבצעים שינויים במסד נתונים שמכיל נתוני ייצור, מומלץ להריץ את העברות הסכימה במצב תאימות, כדי לוודא שנתונים קיימים לא יימחקו. אפשר לציין את schemaValidation: "COMPATIBLE" ב-dataconnect.yaml.

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

  • ההצהרות DROP SCHEMA, DROP TABLE ו-DROP COLUMN נחשבות להצהרות אופציונליות, והן לא ייווצרו עבור התוכנית שלכם, גם אם סכימת מסד הנתונים שלכם מכילה סכימות, טבלאות או עמודות שלא מוגדרות בסכימת האפליקציה שלכם.
  • אם טבלת מסד הנתונים מכילה עמודה שאינה null ולא נכללת בסכימת האפליקציה, אילוץ NOT NULL יוסר, כך שעדיין ניתן יהיה להוסיף נתונים לטבלה באמצעות המחברים שהגדרתם.

מה השלב הבא?