Wdrażanie schematów i łączników SQL Connect oraz zarządzanie nimi

Usługa Firebase SQL Connect ma 3 główne komponenty:

  • bazę danych PostgreSQL z własnym schematem SQL;
  • SQL Connect schemat aplikacji (zadeklarowany w plikach .gql)
  • liczbę oprogramowań sprzęgających (zadeklarowanych w plikach .gql i skonfigurowanych w plikach connector.yaml).

Schemat SQL jest źródłem informacji o Twoich danych, schemat SQL 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 wdrożysz usługę SQL Connect za pomocą interfejsu wiersza poleceń, najpierw przeniesiesz schemat SQL, a potem zaktualizujesz schemat SQL Connect i każde oprogramowanie sprzęgające.

Ważne pojęcia związane z wdrażaniem

Aby w pełni zrozumieć wdrażanie, musisz poznać kluczowe pojęcia dotyczące schematów i oprogramowania sprzęgającego.

Wdrażanie schematu

Wdrożenie schematu SQL Connect wpływa na schemat SQL bazy danych Cloud SQL. SQL Connect pomaga przenieść schematy podczas wdrażania, niezależnie od tego, czy pracujesz z nową bazą danych, czy musisz w sposób nieniszczący dostosować istniejącą bazę danych.

SQL Connect migracje schematu mają 2 różne tryby weryfikacji schematu: ścisły i zgodny.

  • Weryfikacja w trybie ścisłym wymaga, aby schemat bazy danych dokładnie odpowiadał schematowi aplikacji, zanim będzie można go zaktualizować. Wszystkie tabele lub kolumny, które nie są używane w schemacie SQL Connect zostaną usunięte z bazy danych.

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

    Zgodność oznacza, ż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.

Wdrażanie oprogramowania sprzęgającego

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

SQL Connect integruje analizę zmian powodujących niezgodność w aktualizacjach oprogramowania sprzęgającego z interfejsem wiersza poleceń Firebase.

Interfejs wiersza poleceń analizuje zmiany w każdym oprogramowaniu sprzęgającym w odniesieniu do schematu i wyświetla zestaw komunikatów oceniających zmiany w oprogramowaniu sprzęgającym, które mogą zmienić zachowanie klienta (komunikaty są na poziomie ostrzeżenia) lub mogą lub spowodują problemy (komunikaty są na poziomie niezgodności) w poprzednich wersjach kodu klienta.

Przykład:

  • Zmiany w oprogramowaniu sprzęgającym, które mogą zmienić zachowanie klienta, obejmują usunięcie pola dopuszczającego wartość null z zapytania bez adnotacji schematu @retired.
  • Zmiany w oprogramowaniu sprzęgającym, które mogą lub spowodują problemy u klientów, obejmują zmianę zmiennej operacji dopuszczającej wartość null na niedopuszczającą wartości null bez wartości domyślnej lub zmianę typu danych pola na niezgodny (np. String na Int).

Bardziej szczegółową listę scenariuszy na poziomie ostrzeżenia i niezgodności znajdziesz w przewodniku po interfejsie wiersza poleceń.

Przepływ pracy wdrożenia

Możesz pracować nad projektem SQL Connect zarówno w lokalnym katalogu projektu , jak i w konsoli Firebase.

Zalecany przepływ pracy wdrożenia obejmuje:

  1. Wyświetlanie obecnie wdrożonych schematów i oprogramowania sprzęgającego za pomocą polecenia firebase dataconnect:services:list.
  2. Zarządzanie aktualizacjami schematu.
    1. Sprawdź różnice w schemacie SQL między Cloud SQL bazą danych a lokalnym schematem SQL Connect za pomocą firebase dataconnect:sql:diff.
    2. W razie potrzeby przeprowadź migrację schematu SQL za pomocą polecenia dataconnect:sql:migrate.
  3. Wykonywanie wdrożeń schematu i oprogramowania sprzęgającego przez uruchomienie polecenia firebase deploy w przypadku samego schematu, samego oprogramowania sprzęgającego lub kombinacji zasobów.

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

Przed wdrożeniem warto sprawdzić zasoby produkcyjne.

firebase dataconnect:services:list

Podczas pracy w lokalnym katalogu projektu do wdrożenia schematu i oprogramowania sprzęgającego w środowisku produkcyjnym będziesz zwykle używać polecenia firebase deploy z interaktywnymi informacjami zwrotnymi.

Użycie dowolnego deploy polecenia z flagą --only dataconnect umożliwia oddzielenie SQL Connect wdrożeń od innych produktów w projekcie.

Normalne wdrożenie

firebase deploy --only dataconnect

W tym normalnym wdrożeniu interfejs wiersza poleceń Firebase próbuje wdrożyć schemat i oprogramowanie sprzęgające.

Sprawdza, czy nowy schemat nie powoduje problemów z żadnym z istniejących oprogramowań sprzęgających. Podczas wprowadzania zmian powodujących niezgodność postępuj zgodnie ze sprawdzonymi metodami.

Sprawdza też, czy schemat SQL został już przeniesiony, zanim zaktualizuje schemat SQL Connect. Jeśli nie, automatycznie wyświetli prośbę o wykonanie niezbędnych czynności w celu przeniesienia schematów.

Wdrożenie z flagą --force

firebase deploy --only dataconnect --force

Jeśli weryfikacje oprogramowania sprzęgającego lub schematu SQL nie są problemem, możesz ponownie uruchomić polecenie z flagą --force, aby je zignorować.

Wdrożenie z flagą --force nadal sprawdza, czy schemat SQL jest zgodny ze schematem SQL Connect, ostrzega o niezgodności i wyświetla prośbę.

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 oprogramowania sprzęgającego i usługi.

firebase deploy --only dataconnect:serviceId:connectorId

Na koniec możesz wdrożyć schemat i wszystkie oprogramowania sprzęgające dla jednej usługi.

firebase deploy --only dataconnect:serviceId

Cofanie wdrożenia

Aby ręcznie cofnąć wdrożenie, pobierz poprzednią wersję kodu i ją wdróż. Jeśli pierwotne wdrożenie obejmowało zmiany powodujące niezgodność, które spowodowały usunięcie danych, odzyskanie wszystkich usuniętych danych może być niemożliwe.

Migrowanie schematów bazy danych

Jeśli szybko tworzysz prototypy, eksperymentujesz ze schematami i wiesz, że zmiany schematu są destrukcyjne, możesz użyć narzędzi SQL Connect aby zweryfikować zmiany i nadzorować sposób przeprowadzania aktualizacji.

Porównywanie zmian schematu SQL

Możesz sprawdzić zmiany:

firebase dataconnect:sql:diff

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

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

Stosowanie zmian

Gdy wszystko będzie gotowe do wdrożenia zmian w schemacie Cloud SQL instancji, uruchom polecenie firebase dataconnect:sql:migrate. Zostanie wyświetlona prośba o zatwierdzenie zmian.

firebase dataconnect:sql:migrate [serviceId]

W środowiskach interaktywnych wyświetlane są instrukcje migracji SQL i prośby o działanie.

Migrowanie w trybie ścisłym lub zgodnym

W nowym projekcie stosowany jest domyślny tryb weryfikacji schematu. Polecenie migrate stosuje wszystkie zmiany schematu bazy danych wymagane przez schemat aplikacji, a następnie wyświetla prośbę o zatwierdzenie opcjonalnych operacji, które powodują usunięcie schematów, tabel lub kolumn, aby schemat bazy danych dokładnie odpowiadał schematowi aplikacji.

To zachowanie możesz dostosować, modyfikując plik dataconnect.yaml. Odkomentuj klucz schemaValidation i zadeklaruj COMPATIBLE, aby podczas migracji stosowane były tylko wymagane zmiany.

schemaValidation: "COMPATIBLE"

Możesz też ustawić zachowanie na STRICT, aby stosowane były wszystkie zmiany schematu, a schemat bazy danych był zgodny ze schematem aplikacji.

schemaValidation: "STRICT"

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

Aktualizowanie oprogramowania sprzęgającego

Gdy uruchomisz polecenie firebase deploy, interfejs wiersza poleceń rozpocznie aktualizację odpowiednich oprogramowań sprzęgających i wyświetli odpowiednie komunikaty oceniające na poziomie ostrzeżenia (mogące mieć wpływ na zachowanie klienta) i niezgodności (mogące lub na pewno powodujące problemy).

Zarządzanie aktualizacjami oprogramowania sprzęgającego 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ń wyświetla prośbę o zaakceptowanie wszystkich komunikatów. Możesz zastąpić i wymusić wdrożenie oprogramowania sprzęgającego 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 wiersza poleceń wdroży oprogramowanie sprzęgające, o ile nie ma ocen na poziomie niezgodności. W przeciwnym razie skrypt zostanie zakończony z dziennikiem zmian powodujących niezgodność. Możesz 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 oprogramowaniem sprzęgającym

Firebase zaleca stosowanie w projektach SQL Connect kilku sprawdzonych metod.

Minimalizowanie zmian powodujących niezgodność

  • Firebase zaleca przechowywanie plików schematu SQL Connect i oprogramowania sprzęgającego w systemie kontroli wersji.
  • Jeśli to możliwe, unikaj zmian powodujących niezgodność. Oto kilka typowych przykładów zmian powodujących niezgodność:
    • Usuwanie pola ze schematu.
    • Zmienianie pola dopuszczającego wartość null w schemacie na niedopuszczające wartości null (np. Int -> Int!)
    • Zmienianie nazwy pola w schemacie.
  • Jeśli musisz usunąć pole ze schematu, rozważ podzielenie go na kilka wdrożeń, aby zminimalizować wpływ:
    • Najpierw usuń wszystkie odwołania do pola w oprogramowaniu sprzęgającym i wdróż zmianę.
    • Następnie zaktualizuj aplikacje, aby korzystały z nowo wygenerowanych pakietów SDK.
    • Na koniec usuń pole w pliku schematu .gql, przenieś schemat SQL i ponownie wdróż.

Używanie trybu ścisłego podczas pracy z nowymi bazami danych

Jeśli używasz SQL 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 określić schemaValidation: "STRICT" w pliku dataconnect.yaml.

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

Używanie trybu zgodnego, gdy w bazie danych znajdują się dane produkcyjne

Jeśli wprowadzasz zmiany w bazie danych zawierającej dane produkcyjne, zalecamy przeprowadzenie migracji schematu w trybie zgodnym, aby nie usunąć istniejących danych. Możesz określić schemaValidation: "COMPATIBLE" w pliku dataconnect.yaml.

W trybie zgodnym w bazie danych stosowane są tylko wymagane zmiany migracji schematu.

  • DROP SCHEMA, DROP TABLE i DROP COLUMN są uważane za instrukcje opcjonalne i nie będą generowane w Twoim planie, 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ę niedopuszczającą wartości 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ą zdefiniowanego oprogramowania sprzęgającego.

Co dalej?

  • Wdrażanie i zarządzanie kodem klienta opracowanym za pomocą wygenerowanych pakietów SDK opisujemy w przewodnikach po Androidzie, iOS, internecie i Flutterze.
  • Więcej informacji o narzędziach do wdrażania znajdziesz w dokumentacji interfejsu wiersza poleceń SQL Connect i dokumentacji pliku konfiguracyjnego SQL Connect.