استقرار و مدیریت طرحواره ها و اتصال دهنده های Data Connect

یک سرویس Firebase Data Connect سه جزء اصلی دارد:

  • یک پایگاه داده PostgreSQL اساسی با طرحواره SQL خاص خود
  • یک طرحواره برنامه Data Connect (که در فایل‌های .gql شما تعریف شده است)
  • تعدادی کانکتور (که در فایل‌های .gql شما تعریف شده‌اند و در فایل‌های connector.yaml پیکربندی شده‌اند).

طرحواره SQL منبع حقیقت برای داده‌های شماست، طرحواره Data Connect نحوه مشاهده داده‌ها توسط رابط‌های شما را مشخص می‌کند و رابط‌ها APIهایی را که کلاینت‌های شما می‌توانند برای دسترسی به داده‌ها از آنها استفاده کنند، تعریف می‌کنند.

وقتی سرویس Data Connect خود را با CLI مستقر می‌کنید، طرحواره SQL خود را منتقل می‌کنید، سپس طرحواره Data Connect خود را به‌روزرسانی می‌کنید، و در نهایت هر یک از کانکتورهای خود را به‌روزرسانی می‌کنید.

مفاهیم مهم استقرار

برای درک کامل استقرار، توجه به مفاهیم کلیدی در مورد طرحواره‌ها و رابط‌ها (connectors) مهم است.

استقرار طرحواره

استقرار یک طرحواره Data Connect بر طرحواره SQL برای پایگاه داده Cloud SQL شما تأثیر می‌گذارد. Data Connect به شما کمک می‌کند تا طرحواره‌های خود را در حین استقرار، چه در حال کار با یک پایگاه داده جدید باشید و چه نیاز به تطبیق غیر مخرب یک پایگاه داده موجود داشته باشید، منتقل کنید .

مهاجرت‌های طرحواره Data Connect دو حالت اعتبارسنجی طرحواره مختلف دارند: strict و compatible .

  • اعتبارسنجی حالت سختگیرانه مستلزم آن است که طرحواره پایگاه داده دقیقاً با طرحواره برنامه مطابقت داشته باشد تا بتوان طرحواره برنامه را به‌روزرسانی کرد. هر جدول یا ستونی که در طرحواره Data Connect شما استفاده نشود، از پایگاه داده حذف خواهد شد.

  • اعتبارسنجی حالت سازگار مستلزم آن است که طرحواره پایگاه داده قبل از به‌روزرسانی طرحواره برنامه، با طرحواره برنامه سازگار باشد؛ هرگونه تغییر اضافی که طرحواره‌ها، جداول یا ستون‌ها را حذف کند، اختیاری است.

    سازگار به این معنی است که مهاجرت‌های طرحواره فقط بر جداول و ستون‌هایی که در طرحواره برنامه شما ارجاع داده شده‌اند، تأثیر می‌گذارند. عناصری در پایگاه داده شما که توسط طرحواره برنامه شما استفاده نمی‌شوند، بدون تغییر باقی می‌مانند. بنابراین، پس از استقرار، پایگاه داده شما ممکن است شامل موارد استفاده نشده زیر باشد:

    • طرحواره‌ها
    • جداول
    • ستون‌ها

استقرار کانکتورها

کوئری‌ها و جهش‌های Data Connect توسط کد کلاینت ارسال و روی سرور اجرا نمی‌شوند. در عوض، هنگام استقرار، این عملیات Data Connect مانند Cloud Functions روی سرور ذخیره می‌شوند. این بدان معناست که استقرار ممکن است کاربران موجود را از کار بیندازد.

Data Connect تجزیه و تحلیل تغییرات جزئی در به‌روزرسانی‌های کانکتور شما را در Firebase CLI ادغام می‌کند.

رابط خط فرمان (CLI) تغییرات هر کانکتور را با توجه به طرحواره شما تجزیه و تحلیل می‌کند و مجموعه‌ای از پیام‌های ارزیابی را با توجه به تغییرات کانکتور که ممکن است رفتار کلاینت را تغییر دهد (پیام‌ها در سطح هشدار هستند) یا ممکن است نسخه‌های قبلی کد کلاینت را خراب کند یا خراب کند (پیام‌ها در سطح شکستن هستند) صادر می‌کند .

برای مثال:

  • تغییرات رابط که ممکن است رفتار کلاینت را تغییر دهد شامل حذف یک فیلد nullable از یک کوئری بدون حاشیه‌نویسی schema @retired است.
  • تغییرات رابط که ممکن است یا باعث خرابی کلاینت‌ها می‌شوند شامل تغییر یک متغیر عملیاتی nullable به غیر 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 برای استقرار طرحواره و کانکتورهای خود در محیط عملیاتی، با بازخورد تعاملی، استفاده خواهید کرد.

با استفاده از هر دستور deploy ، پرچم --only dataconnect به شما امکان می‌دهد تا استقرارهای Data Connect را از سایر محصولات پروژه خود جدا کنید.

استقرار عادی 

firebase deploy --only dataconnect

در این استقرار عادی، رابط خط فرمان Firebase تلاش می‌کند تا طرحواره و کانکتورهای شما را مستقر کند.

این تأیید می‌کند که طرحواره جدید هیچ یک از کانکتورهای موجود را از کار نمی‌اندازد. هنگام ایجاد تغییرات در مورد از کار انداختن، از بهترین شیوه‌ها پیروی کنید.

همچنین قبل از به‌روزرسانی طرحواره Data Connect ، تأیید می‌کند که طرحواره SQL از قبل منتقل شده است. در غیر این صورت، به طور خودکار شما را از انجام هرگونه گام لازم برای مهاجرت طرحواره‌ها مطلع می‌کند.

--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 را که برای رفع آن اختلاف اجرا می‌شوند، چاپ می‌کند.

اعمال تغییرات

وقتی از تغییرات راضی بودید و آماده‌ی اعمال آنها در نمونه‌ی schema Cloud SQL بودید، دستور firebase dataconnect:sql:migrate را اجرا کنید. از شما خواسته می‌شود تغییرات را تأیید کنید.

firebase dataconnect:sql:migrate [serviceId]

در محیط‌های تعاملی، دستورات مهاجرت SQL و اعلان‌های اقدام نمایش داده می‌شوند.

مهاجرت در حالت strict یا compatible

در یک پروژه کاملاً جدید، حالت اعتبارسنجی پیش‌فرض طرحواره اعمال می‌شود. عملکرد دستور migrate این است که تمام تغییرات طرحواره پایگاه داده مورد نیاز طرحواره برنامه شما را اعمال می‌کند، سپس از شما می‌خواهد عملیات اختیاری را که طرحواره‌ها، جداول یا ستون‌ها را حذف می‌کنند، تأیید کنید تا طرحواره پایگاه داده شما دقیقاً با طرحواره برنامه شما مطابقت داشته باشد.

شما می‌توانید این رفتار را با تغییر فایل dataconnect.yaml خود تنظیم کنید. کلید schemaValidation را از حالت کامنت خارج کنید و COMPATIBLE را تعریف کنید تا فقط تغییرات مورد نیاز در migrations اعمال شوند.

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 مراجعه کنید.

بهترین شیوه‌ها برای مدیریت طرحواره‌ها و رابط‌ها

فایربیس برخی از شیوه‌ها را برای دنبال کردن در پروژه‌های Data Connect شما توصیه می‌کند.

تغییرات ناگهانی را به حداقل برسانید

  • فایربیس توصیه می‌کند که طرحواره Data Connect و فایل‌های کانکتور خود را در کنترل منبع نگه دارید.
  • در صورت امکان از شکستن تغییرات خودداری کنید. برخی از نمونه‌های رایج شکستن تغییرات عبارتند از:
    • حذف یک فیلد از طرحواره شما
    • تبدیل یک فیلد nullable در schema به nonnullable (مثلاً Int -> Int! )
    • تغییر نام یک فیلد در طرحواره شما.
  • اگر نیاز به حذف یک فیلد از طرحواره خود دارید، برای به حداقل رساندن تأثیر، تقسیم آن به چند استقرار را در نظر بگیرید:
    • ابتدا، هرگونه ارجاع به فیلد را در کانکتورهای خود حذف کنید و تغییر را اعمال کنید.
    • در مرحله بعد، برنامه‌های خود را برای استفاده از SDK های تازه تولید شده به‌روزرسانی کنید.
    • در نهایت، فیلد را در فایل schema .gql خود حذف کنید، طرح SQL خود را منتقل کنید و یک بار دیگر آن را مستقر کنید.

هنگام کار با پایگاه‌های داده جدید از حالت strict استفاده کنید

اگر از Data Connect با یک پایگاه داده جدید استفاده می‌کنید و به طور فعال طرحواره برنامه خود را توسعه می‌دهید، و می‌خواهید مطمئن شوید که طرحواره پایگاه داده شما دقیقاً با طرحواره برنامه شما مطابقت دارد، می‌توانید schemaValidation: "STRICT" را در dataconnect.yaml خود مشخص کنید.

این کار تضمین می‌کند که تغییرات اختیاری نیز اعمال شوند.

وقتی داده‌های عملیاتی در پایگاه داده خود دارید، از حالت سازگار استفاده کنید

اگر در حال ایجاد تغییراتی در پایگاه داده‌ای هستید که حاوی داده‌های عملیاتی است، توصیه می‌کنیم مهاجرت‌های طرحواره خود را در حالت سازگار اجرا کنید تا مطمئن شوید داده‌های موجود از بین نمی‌روند. می‌توانید schemaValidation: "COMPATIBLE" در dataconnect.yaml خود مشخص کنید.

در حالت سازگار، فقط تغییرات مورد نیاز برای مهاجرت طرحواره به پایگاه داده شما اعمال می‌شود.

  • دستورات DROP SCHEMA ، DROP TABLE و DROP COLUMN اختیاری در نظر گرفته می‌شوند و برای طرح شما ایجاد نخواهند شد، حتی اگر طرح پایگاه داده شما حاوی طرح‌ها، جداول یا ستون‌هایی باشد که در طرح برنامه شما تعریف نشده‌اند.
  • اگر جدول پایگاه داده شما حاوی ستونی غیر تهی باشد که در طرحواره برنامه شما گنجانده نشده باشد، محدودیت NOT NULL حذف خواهد شد، به طوری که داده‌ها همچنان می‌توانند با کانکتورهای تعریف شده شما به جدول اضافه شوند.

بعدش چی؟