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

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

  • bazową bazę danych PostgreSQL z własnym schematem SQL,
  • Data Connect schemat aplikacji (zadeklarowany w plikach .gql);
  • liczbę złączy (zadeklarowanych w plikach .gql i skonfigurowanych w plikach connector.yaml);

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

Gdy wdrażasz usługę Data Connect za pomocą interfejsu wiersza poleceń, migrujesz schemat SQL, a następnie aktualizujesz schemat Data Connect i każdy z łączników.

Ważne pojęcia dotyczące wdrażania

Aby w pełni zrozumieć wdrożenie, warto poznać kluczowe koncepcje dotyczące schematów i łączników.

Wdrożenia schematu

Wdrożenie schematu Data Connect wpływa na schemat SQL bazy danych Cloud SQL. Data Connect pomaga migrować schematy podczas wdrażania, niezależnie od tego, czy pracujesz z nową bazą danych, czy musisz bezinwazyjnie dostosować istniejącą bazę danych.

Migracje schematu Data Connect mają 2 tryby weryfikacji schematu: ścisły i zgodny.

  • Weryfikacja w trybie ścisłym wymaga, aby schemat bazy danych dokładnie pasował do schematu aplikacji, zanim będzie można go zaktualizować. Wszystkie tabele i kolumny, które nie są używane w Twoim Data Connectschemacie, zostaną usunięte z bazy danych.

  • Weryfikacja w trybie zgodności wymaga, aby schemat bazy danych był zgodny ze schematem aplikacji przed jego aktualizacją. Wszelkie dodatkowe zmiany, które powodują usunięcie schematów, tabel lub kolumn, są opcjonalne.

    Oznacza to, że migracje schematu wpływają tylko na tabele i kolumny, do których odwołuje się schemat aplikacji. Elementy w bazie danych, które nie są używane przez schemat aplikacji, pozostają niezmienione. 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 te 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 niezgodność w aktualizacjach łącznika z interfejsem Firebase CLI.

Interfejs CLI analizuje zmiany w każdym łączniku w odniesieniu do Twojego schematu i generuje zestaw komunikatów oceniających zmiany w łączniku, które mogą zmienić zachowanie klienta (komunikaty na poziomie ostrzeżenia) lub mogą lub będą powodować błędy (komunikaty na poziomie zmiany powodującej błędy) w poprzednich wersjach kodu klienta.

Przykład:

  • Zmiany w złączu, które mogą wpłynąć na zachowanie klienta, obejmują usunięcie z zapytania pola dopuszczającego wartość null bez adnotacji schematu @retired.
  • Zmiany w złączu, które mogą lub będą powodować problemy u klientów, to m.in. zmiana zmiennej operacji dopuszczającej wartość null na zmienną niedopuszczającą wartości null bez wartości domyślnej lub zmiana typu danych pola na niezgodny (np. String na Int).

Bardziej szczegółową listę scenariuszy na poziomie ostrzeżenia i przerwania znajdziesz w przewodniku po interfejsie CLI.

Postępuj zgodnie z procesem wdrażania.

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

Zalecany proces wdrażania obejmuje:

  1. Wyświetlanie obecnie wdrożonych schematów i łączników z firebase dataconnect:services:list.
  2. zarządzanie aktualizacjami schematu;
    1. Sprawdź różnice w schemacie SQL między bazą danych Cloud SQL a lokalnym schematem Data Connect za pomocą firebase dataconnect:sql:diff.
    2. W razie potrzeby przeprowadź migrację schematu SQL za pomocą narzędzia dataconnect:sql:migrate.
  3. Przeprowadzanie wdrażania schematu i połączeń przez uruchamianie firebase deploy w przypadku samego schematu, samych łączników 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 środowisku produkcyjnym z interaktywnymi informacjami zwrotnymi.

Używając dowolnego polecenia deploy, możesz za pomocą flagi --only dataconnect oddzielić wdrożenia Data Connect od innych usług w projekcie.

Zwykłe wdrożenie

firebase deploy --only dataconnect

W tym normalnym wdrożeniu interfejs wiersza poleceń Firebase próbuje wdrożyć schemat i złącza.

Sprawdza, czy nowy schemat nie powoduje awarii żadnych istniejących łączników. Wprowadzając zmiany powodujące niezgodność, postępuj zgodnie ze sprawdzonymi metodami.

Sprawdza też, czy schemat SQL został już przeniesiony, zanim zaktualizuje schemat Data Connect. W przeciwnym razie automatycznie wyświetli instrukcje dotyczące migracji schematów.

--force wdrożenie flagi

firebase deploy --only dataconnect --force

Jeśli nie chcesz sprawdzać poprawności łącznika ani schematu SQL, możesz ponownie uruchomić polecenie z parametrem --force, aby je zignorować.

--force Wdrożenie nadal sprawdza, czy schemat SQL jest zgodny ze schematem Data Connect, ostrzega o niezgodności i wyświetla odpowiedni komunikat.

Wdrażanie wybranych zasobów

Aby wdrożyć 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

Na koniec możesz wdrożyć schemat i wszystkie konektory dla jednej usługi.

firebase deploy --only dataconnect:serviceId

Cofanie wdrożenia

Aby ręcznie cofnąć zmiany, wyewidencjonuj poprzednią wersję kodu i wdroż ją. Jeśli pierwotne wdrożenie zawierało destrukcyjne zmiany powodujące niezgodność wsteczną, odzyskanie usuniętych danych może być niemożliwe.

Migracja schematów bazy danych

Jeśli szybko tworzysz prototypy, eksperymentujesz ze schematami i wiesz, że zmiany w schemacie są destrukcyjne, możesz użyć narzędzi Data Connect, aby zweryfikować zmiany i nadzorować sposób ich wprowadzania.

Porównywanie zmian schematu SQL

Możesz sprawdzić zmiany:

firebase dataconnect:sql:diff

Możesz przekazać listę usług rozdzielonych przecinkami.

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

Zastosuj zmiany

Gdy wszystko będzie gotowe i zdecydujesz się wdrożyć zmiany w schemacie instancji Cloud SQL, wydaj polecenie firebase dataconnect:sql:migrate. Otrzymasz prośbę o zatwierdzenie zmian.

firebase dataconnect:sql:migrate [serviceId]

W środowiskach interaktywnych wyświetlane są instrukcje migracji SQL i prompty działań.

Migracja w trybie ścisłym lub zgodnym

W nowym projekcie obowiązuje domyślny tryb weryfikacji schematu. Polecenie migrate powoduje zastosowanie wszystkich zmian schematu bazy danych wymaganych przez schemat aplikacji, a następnie wyświetla prośbę o zatwierdzenie opcjonalnych operacji, które usuwają schematy, tabele lub kolumny, aby wymusić dokładne dopasowanie schematu bazy danych do schematu aplikacji.

Możesz dostosować to działanie, modyfikując plik dataconnect.yaml. Odkomentuj klucz schemaValidation i zadeklaruj COMPATIBLE, aby w migracjach stosować tylko wymagane zmiany.

schemaValidation: "COMPATIBLE"

Możesz też ustawić działanie na STRICT, aby zastosować wszystkie zmiany schematu i wymusić dopasowanie schematu bazy danych do schematu aplikacji.

schemaValidation: "STRICT"

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

Aktualizowanie oprogramowania sprzęgającego

Gdy uruchomisz polecenie firebase deploy, interfejs CLI zainicjuje aktualizację odpowiednich łączników i wyświetli odpowiednie komunikaty oceny na poziomie ostrzeżenia (mogące mieć wpływ na zachowanie klienta) i na poziomie zmiany powodującej niezgodność (prawdopodobnie lub na pewno powodującej niezgodność).

Zarządzanie aktualizacjami łączników za pomocą interfejsu wiersza poleceń

Interfejs CLI działa nieco inaczej w trybie interaktywnym i nieinteraktywnym.

Jak można się spodziewać, w trybie interaktywnym interfejs wiersza poleceń wyświetla prośbę o zaakceptowanie wszystkich komunikatów. 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 interfejs CLI wdroży łącznik, o ile nie ma ocen na poziomie powodującym przerwanie działania. W przeciwnym razie skrypt zostanie zamknięty z dziennikiem zmian powodujących błędy. Możesz zastąpić i wdrożyć ustawienia, 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 CLI.

Sprawdzone metody zarządzania schematami i łącznikami

Firebase zaleca stosowanie w Data Connectprojektach pewnych praktyk.

Minimalizowanie zmian powodujących niezgodność

  • Firebase zaleca przechowywanie plików schematu i łącznika Data Connect w systemie kontroli wersji.
  • W miarę możliwości unikaj zmian powodujących niezgodność. Oto kilka przykładów zmian powodujących niezgodność:
    • Usuwanie pola ze schematu
    • Zmiana pola dopuszczającego wartość null w schemacie na pole niedopuszczające wartości null (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 tej zmiany:
    • Najpierw usuń wszystkie odwołania do pola w łącznikach i wdroż zmiany.
    • Następnie zaktualizuj aplikacje, aby korzystały z nowo wygenerowanych pakietów SDK.
    • Na koniec usuń pole w pliku schematu .gql, przeprowadź migrację schematu SQL i ponownie wdróż.

Korzystanie z trybu ścisłego podczas pracy z nowymi bazami danych

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

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

Używaj trybu zgodności, gdy w bazie danych masz dane produkcyjne

Jeśli wprowadzasz zmiany w bazie danych zawierającej dane produkcyjne, zalecamy przeprowadzenie migracji schematu w trybie zgodności, aby mieć pewność, że istniejące dane nie zostaną usunięte. Możesz określić schemaValidation: "COMPATIBLE" w dataconnect.yaml.

W trybie zgodności do bazy 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 przypadku Twojego planu, nawet jeśli schemat bazy danych zawiera schematy, tabele lub kolumny, które nie są zdefiniowane w schemacie aplikacji.
  • Jeśli tabela bazy danych zawiera kolumnę, która nie może mieć wartości null i 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 łączników.

Co dalej?