פריסה וניהול של סכימות ומחברים של 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 עוזר להעביר את הסכימות במהלך הפריסה, בין שאתם עובדים עם מסד נתונים חדש ובין שאתם צריכים להתאים מסד נתונים קיים ללא השמדת נתונים.

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

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

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

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

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

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

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

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

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

לדוגמה:

  • שינויים במחבר שעשויים לשנות את התנהגות הלקוח כוללים הסרה של שדה nullable משאילתה ללא הערה של הסכימה @retired.
  • שינויים במחבר שעלול לגרום לשגיאות בלקוחות או שגורמים לשגיאות בלקוחות כוללים שינוי של משתנה פעולה עם אפשרות ל-null למשתנה ללא ערך 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, רק עבור הסכימה, רק עבור המחברים או שילובים של משאבים.

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

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

firebase dataconnect:services:list

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

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

פריסה רגילה

firebase deploy --only dataconnect

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

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

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

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

firebase deploy --only dataconnect --force

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

הפריסה של --force עדיין בודקת אם הסכימה של 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"

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

עדכון המחברים

כשמריצים את 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 פורס את המחבר כל עוד אין הערכות ברמת ה-breaking. אחרת, הסקריפט ייצא עם יומן של שינויים שגורמים לשגיאות. אפשר לשנות את ההגדרה ולפרוס אותה על ידי הגדרת הדגל --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 במערכת בקרת הגרסאות של Firebase.
  • אם אפשר, כדאי להימנע משינויים שגורמים לשיבושים. דוגמאות נפוצות לשינויים שגורמים לשגיאות:
    • הסרת שדה מהסכימה
    • שינוי שדה nullable בסכימה לשדה שאינו nullable (כלומר Int -> Int!)
    • שינוי השם של שדה בסכימה.
  • אם אתם צריכים להסיר שדה מהסכימה, כדאי לפצל אותו לכמה פריסות כדי למזער את ההשפעה:
    • קודם כול, מסירים את כל ההפניות לשדה במחברים ופורסים את השינוי.
    • לאחר מכן, עליכם לעדכן את האפליקציות כדי להשתמש ב-SDKs החדשים שנוצרו.
    • לבסוף, מסירים את השדה בקובץ .gql של הסכימה, מעבירים את הסכימה של SQL ופורסים אותה שוב.

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

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

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

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

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

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

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

מה השלב הבא?