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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

לדוגמה:

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

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

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

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

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

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

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

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

firebase dataconnect:services:list

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

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

פריסה רגילה

firebase deploy --only dataconnect

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

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

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

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

firebase deploy --only dataconnect --force

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

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

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

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

firebase deploy --only dataconnect:serviceId:schema

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

firebase deploy --only dataconnect:serviceId:connectorId

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

firebase deploy --only dataconnect:serviceId

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

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

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

אם אתם יוצרים אב טיפוס במהירות, מתנסים בסכימות ויודעים ששינויי הסכימה שלכם הם הרסניים, אתם יכולים לתכנן שימוש בכלי Data 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"

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

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

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

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

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

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

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

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

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

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

מה השלב הבא?