מאמר עזר בנושא פקודות Firebase CLI ל-SQL Connect

‫Firebase CLI הוא כלי שמאפשר לכם לנהל ולהגדיר מוצרים ושירותים של Firebase משורת הפקודה.

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

פקודות הגדרה

הוספת SQL Connect לפרויקט Firebase

firebase init

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

firebase init

תהליך העבודה של firebase init כולל הגדרה של שירות ומסד נתונים, ואם רוצים, גם התקנה של אמולטור SQL Connect והגדרה של ערכות SDK שנוצרו.

הגדרת השירות ומסד הנתונים

אם בוחרים באפשרות dataconnect להגדרת המוצר, ה-CLI יבקש שם ומיקום חדשים לשירות, וישאל אם לקשר מופע קיים של Cloud SQL ל-PostgreSQL או ליצור מופע חדש.

אם מחובר מופע קיים, ממשק ה-CLI בודק אם יש הגדרות תואמות, כמו אימות IAM וכתובות IP ציבוריות.

הגדרת Local Emulator Suite

תהליך ה-CLI מציע להגדיר אמולטורים, כולל אמולטור SQL Connect.

פקודות אמולטור SQL Connect

הפעלת האמולטור SQL Connect

emulators:start/exec

firebase emulators:start/exec

משתמשים בגרסה Local Emulator Suite של אמולטור SQL Connect במצב אינטראקטיבי עם start או במצב לא אינטראקטיבי מבוסס-סקריפט עם exec.

ייצוא וייבוא של נתונים מקומיים ב-PostgreSQL

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

הייצוא מאוחסן כתמונות מצב של מסד הנתונים המקומי של PostgreSQL.

‫SQL Connect מציע שלוש גישות לייצוא או לייבוא:

  • ייצוא אוטומטי/ייבוא אוטומטי שהוגדרו ב-firebase.json כדי לספק גיבויים של תמונות מצב כשמפסיקים ומפעילים את האמולטור
  • ייצוא או ייבוא ידניים באמצעות ה-CLI
  • ייצוא או ייבוא ידניים באמצעות הממשק של התוסף SQL Connect VS Code

ייצוא וייבוא אוטומטיים שהוגדרו ב-firebase.json

כדי לגבות נתונים בין סשנים של פיתוח, צריך לציין מיקום לגיבוי אוטומטי במהלך רצף הפעולות firebase init. המיקום הזה נשמר בfirebase.json בשדה emulators.dataconnect.dataDir. כל שינוי בנתונים שתבצעו יישמר כאן באופן אוטומטי בין הפעלות של האמולטור, ולכן הוא שימושי במהלך בדיקות מקומיות.

ייצוא ידני: emulators:export ו-emulators:start/exec --import

בזמן שהאמולטור SQL Connect פועל, במסוף נפרד, מריצים את הפקודה firebase emulators:export כדי לשמור תמונת מצב של הנתונים. אחר כך תוכלו להפעיל את האמולטור מתמונת המצב הזו באמצעות הדגל --import.

‫
# Export data from local emulator from a separate terminal
firebase emulators:export --only dataconnect <export_directory>

# Import data from local directory, here using emulators:exec
firebase emulators:exec ./<your-test-script>.sh --only dataconnect --import <import_directory>

ייצוא או ייבוא ידני: תוסף SQL Connect VS Code

בממשק המשתמש של התוסף SQL Connect ל-VS Code, בזמן שהאמולטור פועל, משתמשים בלחצן Export emulator data כדי לייצא נתונים לייצוא התוכן הנוכחי של מסד הנתונים. מיקום הייצוא שמוגדר כברירת מחדל הוא הספרייה exportedData בתיקיית הבסיס של תיקיית הפרויקט.

אפשר לייבא את הנתונים האלה באמצעות ה-CLI, כמו שמתואר בקטע הקודם. אפשר גם לייבא את הנתונים האלה לפני שמפעילים את האמולטור דרך VS Code. לשם כך, לוחצים על הקישור Configure emulator ומגדירים את Import Path.

פקודות לניהול סכימות ומחברים

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

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

פריסת סכימות ומחברים

לפרוס

firebase deploy

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

Command תיאור

firebase deploy

Flag תיאור

–-only dataconnect

פריסת סכימות ומחברים לכל שירותי SQL Connect בפרויקט הזה, אבל לא פריסת משאבים של מוצרי Firebase אחרים.

‪–-only dataconnect:serviceId

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

‫–-only dataconnect:serviceId:connectorId

פריסת מחבר יחיד לשירות SQL Connect שצוין.

‫–-only dataconnect:serviceId:schema

פריסת הסכימה עבור שירות SQL Connect שצוין.

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

firebase deploy --only dataconnect:service1:schema,dataconnect:service2

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

dataconnect:services:list

firebase dataconnect:services:list

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

השוואה והעברה של סכימות SQL

כשמריצים את הפקודה firebase deploy, ה-CLI מבצע השוואה של סכימת SQL לפני פריסת העדכונים. אפשר גם לבצע את ההשוואה ולעדכן ישירות באמצעות קבוצה של פקודות dataconnect:sql.

dataconnect:sql:diff

firebase dataconnect:sql:diff

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

Command תיאור

‫firebase dataconnect:sql:diff

דגל/פרמטר תיאור

serviceId

מציינים את השירות. אם לא מציינים שירותים, יודפס ההבדל בין כל השירותים בקובץ firebase.json.

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

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

כשמגדירים פרויקט מקומי חדש של SQL Connect עם קובץ dataconnect.yaml שמוגדר כברירת מחדל, הפקודה dataconnect:sql:migrate מציגה בקשה לביצוע שינויים נדרשים, ואז בקשה לביצוע שינויים אופציונליים, לפני שהיא מבצעת את השינויים. אפשר לשנות את ההתנהגות הזו כך שתמיד יכללו שינויים אופציונליים או יתעלמו מהם. לשם כך, צריך לעדכן את ההגדרה של dataconnect.yaml, כמו שמוסבר במאמר העברת סכימה במצב מחמיר או במצב תואם.

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

בסביבות לא אינטראקטיביות:

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

firebase dataconnect:sql:migrate

Flag תיאור

serviceId

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

‫‎–-force

אישור אוטומטי של הנחיות.

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

העברת סכימה במצב קפדני או במצב תאימות

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

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

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

ניהול שינויים במחברים

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

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

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

בסביבות לא אינטראקטיביות:

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

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

‫SQL Connect עוזר לכם לבדוק את אסטרטגיית ההרשאות שלכם על ידי ניתוח קוד המחבר כשאתם מבצעים פריסה לשרת באמצעות firebase deploy מ-Firebase CLI. אתם יכולים להשתמש בביקורת הזו כדי לבדוק את בסיס הקוד.

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

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

אזהרות והנחיות תמיד מופיעות במקרים הבאים:

  • PUBLIC

בנוסף, אם לא מוסיפים מסננים לרמות הגישה הבאות באמצעות auth.uid, יוצגו אזהרות והנחיות:

  • USER
  • USER_ANON
  • USER_EMAIL_VERIFIED

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

פקודות SDK

יצירת ערכות SDK

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

הפקודה הזו יוצרת את ערכות ה-SDK עם ההקלדה שהוגדרו בקובץ connector.yaml.

אפשר גם לעיין במדריכים לעבודה עם ערכות ה-SDK לאינטרנט, ערכות ה-SDK ל-Android וערכות ה-SDK ל-iOS.

Command תיאור

firebase dataconnect:sdk:generate

Flag תיאור

–-watch

התהליך ממשיך לפעול ונוצרים ערכות SDK חדשות בכל פעם ששומרים שינויים בקובצי הסכימה והמחבר GQL.

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

‫–-only connectorId:platform

אפשר ליצור ערכות SDK רק לפלטפורמה אחת ולמחבר אחד.

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

firebase dataconnect:sdk:generate –-only connector1, connector1:kotlin

פקודות ניהול של Cloud SQL

הקצאת תפקידי SQL ל-Cloud SQL

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

dataconnect:sql:setup

firebase dataconnect:sql:setup

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

זרימת ההקצאה והניהול של מסד הנתונים שמוגדרת כברירת מחדל מניחה שהפרויקט שלכם משתמש במסד נתונים חדש (greenfield), וכשמפעילים את firebase deploy, המערכת מציגה את השינויים בסכימת מסד הנתונים שצריך לבצע ומבצעת את ההעברות אחרי שמאשרים.SQL Connect אם זה התהליך המועדף עליכם, dataconnect:sql:setup יבקש מכם להעניק הרשאות, כולל בעלות על סכימות superuser.

אם יש לכם מסדי נתונים קיימים (brownfield), יכול להיות שיש לכם תהליך עבודה משלכם להעברת סכימות, ואתם רוצים לשמור על הבעלות על הסכימות בעצמכם. אם זה התהליך המועדף עליכם, הקפידו לסרב להצעה של SQL Connect לטפל בהעברות של SQL בשבילכם בהנחיה dataconnect:sql:setup. אם תדחו את ההצעה, ל-SQL Connect תהיה גישה רק ל-read ול-write בטבלאות של מסד הנתונים, אבל האחריות על בעלות על סכימות והעברות תישאר שלכם.

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

dataconnect:sql:grant

firebase dataconnect:sql:grant

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

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

תפקיד תפקיד SQL הרשאות שימוש ניתן להעניק הרשאה
בעל הרשאת קריאה firebasereader_<db_name>_<schema_name> הרשאת קריאה בלבד למסד הנתונים.

יכול לבצע פעולות SELECT בכל הטבלאות בסכימה שצוינה.		 מתאים במיוחד למשתמשים או לשירותים שנדרש להם אחזור נתונים אבל לא שינוי שלהם. כן
בעל הרשאת כתיבה firebasewriter_<db_name>_<schema_name> גישת קריאה וכתיבה למסד הנתונים.

יכול לבצע פעולות SELECT, INSERT, UPDATE, DELETE ו-TRUNCATE בכל הטבלאות בסכימה.		 מתאים למשתמשים או לשירותים שצריכים לשנות נתונים במסד הנתונים. כן
בעלים firebaseowner_<db_name>_<schema_name> הבעלים של הסכימה.

יש לו את כל ההרשאות בכל הטבלאות והרצפים בסכימה.		 התפקיד הזה, בשילוב עם התפקיד roles/cloudsql.client ב-IAM, מעניק הרשאה לביצוע העברה במסד הנתונים.

לדוגמה, כשמתקשרים אל firebase dataconnect:sql:migrate.		 כן
משתמש-על cloudsqlsuperuser תפקיד מובנה של משתמש על עם הרשאות מלאות במסד הנתונים.

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

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

אם משתמש שאינו אדמין צריך הרשאות סופר-משתמש, ההעברה תיכשל והמשתמש יתבקש לבקש מאדמין מסד הנתונים (כלומר, משתמש עם הרשאה roles/cloudsql.admin) להריץ את פקודות ה-SQL עם ההרשאות.		 ההרשאה ניתנת למשתמשים עם roles/cloudsql.admin ואי אפשר להעניק אותה ישירות מ-Firebase CLI
Command תיאור

‫firebase dataconnect:sql:grant

דגל/פרמטר תיאור

‫‎-R,‏ ‎--role role

תפקיד ה-SQL להענקה, אחד מהתפקידים הבאים: בעלים, כתיבה או קריאה.

‫‎-E, --email email_address

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

אפשרויות כלליות

ההגדרות הגלובליות הבאות חלות על כל הפקודות:

  • ‫--json מעביר את הפלט של ה-CLI ל-JSON לצורך ניתוח על ידי כלים אחרים.
  • האפשרויות --noninteractive ו---interactive מבטלות, לפי הצורך, את הזיהוי האוטומטי של סביבות שאינן TTY.