Wdrażanie schematów i łączników Data Connectors oraz zarządzanie nimi

Usługa Firebase Data Connect składa się z 3 głównych komponentów:

  • podstawowa baza danych PostgreSQL ze swoim własnym schematem SQL.
  • Data Connect schemat aplikacji (zadeklarowany w plikach .gql);
  • kilka złączy (deklarowanych w plikach .gql i skonfigurowanych w plikach connector.yaml).

Schemat SQL jest źródłem informacji o Twoich danych, a schemat Data Connect określa, jak oprogramowanie sprzęgające może wyświetlać te dane. Oprogramowanie sprzęgające deklaruje interfejsy API, których klienci mogą używać do uzyskiwania dostępu do tych danych.

Podczas wdrażania usługi Data Connect za pomocą interfejsu wiersza poleceń musisz najpierw przenieść schemat SQL, a następnie zaktualizować schemat Data Connect i każdy z oprogramowań sprzęgających.

Ważne pojęcia związane z wdrożeniem

Aby w pełni zrozumieć wdrożenie, musisz poznać podstawowe pojęcia dotyczące schematów i złączy.

Wdrożenia schematu

Wdrażanie schematu Data Connect wpływa na schemat SQL bazy danych Cloud SQL. Data Connect ułatwia migrację schematów podczas wdrażania, niezależnie od tego, czy pracujesz z nową bazą danych, czy musisz bez utraty danych dostosować istniejącą bazę danych.

Migracje schematu Data Connect mają 2 różne tryby sprawdzania poprawności schematu: ścisły i zgodny.

  • Walidacja w trybie ścisłym wymaga, aby schemat bazy danych ściśle odpowiadał schematowi aplikacji, zanim będzie można zaktualizować schemat aplikacji. Wszystkie tabele i kolumny, które nie są używane w schemacie Data Connect, zostaną usunięte z bazy danych.

  • Weryfikacja w trybie zgodności wymaga, aby schemat bazy danych był zgodny ze schematem aplikacji, zanim będzie można zaktualizować schemat aplikacji. Dodatkowe zmiany, które powodują usunięcie schematów, tabel lub kolumn, są opcjonalne.

    Zgodność oznacza, że migracje schematu dotyczą tylko tabel i kolumn, do których odwołuje się schemat aplikacji. Elementy w bazie danych, które nie są używane przez schemat aplikacji, pozostają niezmodyfikowane. Dlatego po wdrożeniu baza danych może zawierać nieużywane:

    • Schematy
    • Tabele
    • Kolumny

Wdrożenia oprogramowania sprzęgającego

Zapytania i mutacje Data Connect nie są przesyłane przez kod klienta i wykonywane na serwerze. Zamiast tego po wdrożeniu operacje Data Connect są przechowywane na serwerze, np. Cloud Functions. Oznacza to, że wdrożenie może spowodować problemy u obecnych użytkowników.

Data Connect integruje analizę zmian powodujących przerwanie w funkcjonalności w Twoich aktualizacjach funkcji łącznika z interfejsem wiersza poleceń Firebase.

CLI analizuje zmiany w każdym z połączeń w odniesieniu do Twojego schematu i wysyła zestaw komunikatów oceny dotyczących zmian w połączeniach, które mogą zmienić zachowanie klienta (komunikaty są na poziomie ostrzeżenia) lub mogą lub będą powodować błąd w poprzednich wersjach kodu klienta (komunikaty są na poziomie błędu).

Przykład:

  • Zmiany w połączeniu, które mogą zmienić działanie klienta, obejmują usunięcie pola z wartością null z zapytania bez adnotacji schematu @retired.
  • Zmiany w połączeniu, które mogą spowodować awarię klienta, obejmują zmianę zmiennej operacji z możliwością null na nienull bez wartości domyślnej lub zmianę typu danych pola na niezgodny (np. String na Int).

Pełną listę scenariuszy na poziomie ostrzeżenia i awarii znajdziesz w przewodniku po interfejsie wiersza poleceń.

Wykonywanie procesu wdrażania

Nad projektem Data Connect możesz pracować zarówno w lokalnym katalogu projektu, jak i w konsoli Firebase.

Zalecane wdrożenie obejmuje:

  1. Wyświetlanie obecnie wdrożonych schematów i łączników za pomocą firebase dataconnect:services:list.
  2. zarządzanie aktualizacjami schematu.
    1. Sprawdź, czy schemat SQL w bazie danych Cloud SQL różni się od lokalnego schematu Data Connect (firebase dataconnect:sql:diff).
    2. W razie potrzeby przeprowadź migrację schematu SQL za pomocą narzędzia dataconnect:sql:migrate.
  3. Wykonywanie wdrożeń schematu i połączeń przez uruchomienie firebase deploy, tylko schematu, tylko połączeń lub kombinacji zasobów.

Wdrażanie zasobów Data Connect i zarządzanie nimi

Przed wdrożeniem warto sprawdzić zasoby produkcyjne.

firebase dataconnect:services:list

Podczas pracy w lokalnym katalogu projektu zwykle używasz polecenia firebase deploy, aby wdrożyć schemat i złącza w produkcji, z interaktywnymi informacjami zwrotnymi.

Flaga --only dataconnect umożliwia oddzielenie wdrożeń Data Connect od innych usług w projekcie.deploy

Normalne wdrażanie

firebase deploy --only dataconnect

Podczas zwykłego wdrażania interfejs wiersza poleceń Firebase próbuje wdrożyć schemat i złącza.

Sprawdzanie, czy nowy schemat nie powoduje przerwania działania dotychczasowych złączy. Stosuj sprawdzone metody podczas wprowadzania zmian powodujących przerwanie działania.

Przed zaktualizowaniem schematu Data Connect sprawdza też, czy schemat SQL został już przeniesiony. Jeśli nie, automatycznie wyświetli Ci instrukcje dotyczące migacji schematów.

--force wdrożenie flagi

firebase deploy --only dataconnect --force

Jeśli nie masz wątpliwości co do poprawności łącznika ani schematu SQL, możesz ponownie uruchomić polecenie z opcją --force, aby je zignorować.

Rozmieszczanie --force nadal sprawdza, czy schemat SQL jest zgodny ze schematem Data Connect, ostrzega o niezgodności i wyświetla odpowiednie komunikaty.

Wdrażanie wybranych zasobów

Aby wdrożyć aplikację z większą kontrolą, użyj flagi --only z argumentem serviceId. Aby wdrożyć tylko zmiany schematu w przypadku konkretnej usługi:

firebase deploy --only dataconnect:serviceId:schema

Możesz też wdrożyć wszystkie zasoby dla określonego łącznika i usługi.

firebase deploy --only dataconnect:serviceId:connectorId

W tym celu możesz wdrożyć schemat i wszystkie łączniki dla jednej usługi.

firebase deploy --only dataconnect:serviceId

Cofanie wdrożenia

Aby wykonać ręczne wycofanie, wybierz poprzednią wersję kodu i wdróż ją. Jeśli pierwotne wdrożenie zawierało zmiany, które spowodowały zniszczenie danych, może się okazać, że nie będzie można w pełni przywrócić usuniętych danych.

Migracja schematów baz danych

Jeśli szybko tworzysz prototypy i eksperymentujesz ze schematami, a zmiany w schemacie są niszczące, możesz zaplanować użycie narzędzi Data Connect do weryfikacji zmian i nadzoru nad ich wprowadzaniem.

Różnice w zmianach schematu SQL

Możesz zweryfikować zmiany:

firebase dataconnect:sql:diff

Możesz podać listę usług oddzielonych przecinkami.

Polecenie porównuje schemat lokalny usługi ze schematem bieżącym odpowiedniej bazy danych Cloud SQL. Jeśli występuje różnica, wypisuje polecenia SQL, które należy wykonać, aby ją skorygować.

Zastosuj zmiany

Gdy wszystko będzie gotowe i będziesz gotowy do wdrożenia zmian w schemacie instancji Cloud SQL, uruchom polecenie firebase dataconnect:sql:migrate. Pojawi się prośba o zatwierdzenie zmian.

firebase dataconnect:sql:migrate [serviceId]

W środowiskach interaktywnych wyświetlają się instrukcje migracji SQL i wytyczne dotyczące działań.

Przeprowadź migrację w trybie ścisłym lub zgodnym

W nowym projekcie obowiązuje domyślny tryb walidacji schematu. Polecenie migrate stosuje wszystkie zmiany schematu bazy danych, które są wymagane przez schemat aplikacji, a potem prosi o zatwierdzenie operacji opcjonalnych, które usuwają schematy, tabele lub kolumny, aby wymusić dokładne dopasowanie schematu bazy danych do schematu aplikacji.

Możesz zmienić to zachowanie, modyfikując plik dataconnect.yaml. Odkomentuj klucz schemaValidation i ogłoś COMPATIBLE, aby podczas migracji były stosowane tylko wymagane zmiany.

schemaValidation: "COMPATIBLE"

Możesz też ustawić zachowanie na STRICT, aby zastosować wszystkie zmiany schematu, a schemat bazy danych był dopasowywany do schematu aplikacji.

schemaValidation: "STRICT"

Więcej informacji znajdziesz w dokumentacji interfejsu wiersza poleceń Data Connect.

Aktualizowanie oprogramowania sprzęgającego

Gdy uruchomisz firebase deploy, CLI inicjuje aktualizację odpowiednich połączeń i wysyła odpowiednie komunikaty o ocenie na poziomie ostrzeżenia (mogą wpływać na działanie klienta) i na poziomie naruszenia (mogą lub z pewnością naruszają)

Zarządzanie aktualizacjami łącznika za pomocą interfejsu wiersza poleceń

Interfejs wiersza poleceń działa nieco inaczej w trybie interaktywnym i nieinteraktywnym.

Jak można się spodziewać, w trybie interaktywnym interfejs wiersza poleceń prosi o akceptację wszystkich wiadomości. Możesz zastąpić i wymusić wdrożenie łącznika za pomocą flagi --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

W trybie nieinteraktywnym narzędzie wiersza poleceń wdraża złącze, o ile nie ma żadnych oceny na poziomie naruszenia. W przeciwnym razie skrypt zakończy działanie z logiem zmian powodujących błędy. Możesz je zastąpić i wdrożyć, ustawiając flagę --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

Więcej informacji znajdziesz w przewodniku po interfejsie wiersza poleceń.

Sprawdzone metody zarządzania schematami i złączami

Firebase zaleca stosowanie w projektach Data Connectpewnych sprawdzonych metod.

Minimalizowanie zmian powodujących niezgodności

  • Firebase zaleca przechowywanie schematu Data Connect i plików złącza w kontroli źródłowej.
  • W miarę możliwości unikaj zmian powodujących niezgodność. Oto kilka typowych przykładów zmian naruszających zasady:
    • Usuwanie pola ze schematu
    • Ustawienie pola, które może być puste, na pole, które nie może być puste (np. Int -> Int!).
    • zmiana nazwy pola w schemacie.
  • Jeśli musisz usunąć pole ze schematu, rozważ podzielenie go na kilka wdrożeń, aby zminimalizować wpływ zmian:
    • Najpierw usuń wszystkie odwołania do tego pola w swoich sprzęgach i wdróż zmiany.
    • Następnie zaktualizuj aplikacje, aby korzystały z nowo wygenerowanych pakietów SDK.
    • Na koniec usuń to pole w pliku schematu .gql, przeprowadź migrację schematu SQL i jeszcze raz wdróż schemat.

Używanie trybu rygorystycznego podczas pracy z nowymi bazami danych

Jeśli używasz Data Connect z nową bazą danych i aktywnie rozwijasz schemat aplikacji, a chcesz mieć pewność, że schemat bazy danych jest zgodny ze schematem aplikacji, możesz w sekcji dataconnect.yaml podać wartość schemaValidation: "STRICT".

Dzięki temu zostaną zastosowane również opcjonalne zmiany.

Korzystanie z trybu zgodności, gdy w bazie danych masz dane produkcyjne

Jeśli wprowadzasz zmiany w bazie danych zawierającej dane produkcyjne, zalecamy wykonanie migracji schematu w trybie zgodności, aby nie usunąć dotychczasowych danych. Możesz określić schemaValidation: "COMPATIBLE" w dataconnect.yaml.

W trybie zgodności w bazie danych są stosowane tylko wymagane zmiany migracji schematu.

  • DROP SCHEMA, DROP TABLE i DROP COLUMN są uważane za opcjonalne instrukcje i nie będą generowane w planie, nawet jeśli schemat bazy danych zawiera schematy, tabele lub kolumny nie zdefiniowane w schemacie aplikacji.
  • Jeśli tabela bazy danych zawiera kolumnę inną niż null, która nie jest uwzględniona w schemacie aplikacji, ograniczenie NOT NULL zostanie usunięte, aby można było nadal dodawać dane do tabeli za pomocą zdefiniowanych przez Ciebie złączeń.

Co dalej?

  • Wdrożenie kodu klienta utworzonego za pomocą wygenerowanych pakietów SDK i zarządzanie nim omówiono w przewodnikach dotyczących Androida, iOS, sieci i Fluttera.
  • Więcej informacji o narzędziach do wdrażania znajdziesz w dokumentacji interfejsu wiersza poleceń Data Connect i pliku konfiguracyjnego Data Connect.