Skrypty SQL użytkownika
Elementem aplikacji zbudowanej na platformie archITekt mogą być dedykowane skrypty SQL aplikacji wykonywane w ramach wdrożenia danej wersji aplikacji. Skrypty te mogą dodawać wymaganą, specyficzną funkcjonalność aplikacji, lub zapewniać migrację danych z poprzedniej wersji do aktualnej.
Skrypty SQL aplikacji są zapisywane bezpośrednio w serwerze wersji.
Tworząc skrypt SQL możemy korzystać ze zmiennych, które używamy analogicznie jak zmienne w SQLCMD:
APP_CODENAME– nazwa techniczna aplikacjiDATA_DATABASE, CONFIG_DATABASE, SCHEDULER_DATABASE, VIP_DATABASE, VERSION_SERVER_DATABASE– nazwy baz danych aplikacji
Przykład użycia zmiennych:
SELECT '$(APP_CODENAME)' AS APP_NAME, $(DATA_DATABASE) AS DB_NAME
Skrypty SQL aplikacji nazywane są według ustalonej konwencji:
U.0001.sql
gdzie:
- 0001 – unikalny numer skryptu
Każdy skrypt (plik *.sql) musi być nazwany według powyższej konwencji. W przypadku znalezienia pliku niespełniającego konwencji sygnalizowany jest błąd uniemożliwiający wykonanie eksportu środowiska oraz podmiany środowiska. Patrz: Weryfikacja skryptów.
Każdy skrypt musi mieć unikalny numer, przy czym nie jest badana ciągłość numeracji. W przypadku znalezienia dwóch skryptów o takim samym numerze sygnalizowany jest błąd uniemożliwiający wykonanie eksportu środowiska oraz podmiany środowiska.
Mechanizm unikalności numerów skryptów zabezpiecza przed sytuacjami, gdy dwóch członków zespołu na raz doda skrypty SQL aplikacji do wspólnego repozytorium – gdy nie wiadomo w jakiej kolejności powinny zostać wykonane. Sytuacja zostanie wykryta, bo będą one posiadać te same numery skryptów, a po zasygnalizowaniu sytuacji zespół będzie mógł ją rozwiązać zmieniając numer jednego z tych skryptów.
Wykonywanie „nowych” skryptów
W ramach procedury aktualizacji aplikacji na bazie danych wykonywane są wyłącznie „nowe” skrypty, czyli skrypty o numerach większych niż numer ostatnio wykonanego skryptu, który zakończył się sukcesem.
Jeżeli wykonanie skryptu zakończy się błędem, kolejne uruchomienie procedury aktualizacji rozpocznie działanie od ponownego wykonania tego samego skryptu. W takim przypadku należy dostarczyć paczkę aplikacji zawierającą poprawioną treść tego skryptu.
Każdy skrypt powinien być idempotentny – czyli umożliwiać wielokrotne uruchomienie – i powinien działać w taki sposób, by w przypadku błędu można było naprawić jego działanie (np. być obłożony transakcją).
Śledzenie wykonania skryptów
Informacje o wykonanych skryptach są zapisywane w tabeli _DATABASE_JOURNAL. W trakcie wykonywania skryptów badany jest wyłącznie ostatni zapis w tej tabeli dotyczący wykonania skryptów SQL aplikacji – cała historia wykonania nie jest analizowana.
Cofanie wykonania skryptów
Takie podejście pozwala na „cofanie” licznika wykonania skryptów. Za pomocą polecenia administracyjnego skrypt RewindApplicationSqlScript.ps1 można awaryjnie przesunąć wskaźnik wykonania przed wskazany skrypt SQL – cofnąć go, lub przesunąć w przód, omijając kilka skryptów. Ten sam mechanizm dostępny jest także z poziomu interfejsu VSoft archITekt Launcher, patrz: Zarządzanie skryptami w VSoft archITek Launcher.
Więcej o uruchomieniu polecenia patrz: Opis skryptu do administracyjnego przesuwania wskaźnika wykonania skryptu użytkownika.
Dodawanie skryptów w archITekt Studio
W celu dodania skryptu:
- W oknie głównym wybierz ikonę dodawania w lewym górnym rogu lub z menu głównego Plik>Nowy lub z menu kontekstowego serwera wersji Nowy element.
- Następnie w oknie popup wybierz Skrypt SQL użytkownika.
- W kolejnym oknie wprowadź dane skryptu oraz wybierz jaki skrypt chcesz dodać:
- Różnicowy skrypt aktualizujący struktury danych w stosunku do aktualnego stanu środowiska- wkleja skrypt aktualizujący tylko zmodyfikowane struktury danych
- Pełny skrypt aktualizujący struktury danych- wklej skrypt aktualizujący wszystkie struktury danych
- Skrypt użytkownika- nie dodawaj skryptu struktur danych.
Jeżeli zaznaczysz opcję Różnicowy lub Pełny w powyższym polu, wówczas przed skryptem, który zdefiniujesz, zostanie również dodany plik aktualizujący bazę danych (pełny lub przyrostowy w zależności od wyboru).
- W kolejnym oknie wprowadź skrypt.
Ręczne zarządzanie aktualizacją bazy danych
VSoft archITekt w trakcie procedury podmiany automatycznie generuje i uruchamia skrypty aktualizujące słowniki i strukturę bazy danych. W przypadku pracy z bardzo dużymi projektami czas wykonania skryptów aktualizujących całą strukturę bazy danych może być odczuwalny. W takim przypadku low-code deweloper może zdecydować się na samodzielne, ręczne zarządzanie strukturą bazy danych i/lub słowników.
W celu włączenia ręcznego zarządzania strukturą bazy danych należy:
- Wyłączyć mechanizm automatycznego generowania skryptów SQL aktualizujących słowniki i/lub bazę danych. W tym celu należy utworzyć w serwerze wersji pliki (w dowolnym katalogu):
A.5050.DICT.sql– jeśli chcesz wyłączyć automatyczne generowanie pliku aktualizującego słownikiZ.5050.EDMX.sql– jeśli chcesz wyłączyć automatyczne generowanie pliku aktualizującego strukturę bazy danych
- Dołączać po zmianach struktury danych i/lub słowników skryptu użytkownika zawierające wprowadzone zmiany:
-
W przypadku aktualizacji struktury danych możesz tworząc nowy skrypt użytkownika wybrać wygenerowanie skryptów przyrostowych, lub wygenerowanie pełnego skryptu dla struktur danych. Możesz też przygotować skrypt SQL korzystając z funkcjonalności aktualizacji struktur danych wybierając samodzielnie interesujące Cię obiekty modelu danych w menu Narzędzia>Aktualizacja struktur danych patrz: Aktualizacja struktur danych.
-
W przypadku aktualizacji słowników możesz przygotować skrypt SQL korzystając z funkcjonalności aktualizacji słowników wybierając samodzielnie interesujące Cię słowniki w menu Narzędzia>aktualizacja słowników - patrz: Aktualizowanie słowników w bazie danych.
Mechanizm generowania skryptów przyrostowych
Mechanizm generowania skryptów przyrostowych działa na podstawie analizy istniejących skryptów SQL użytkownika i ich zawartości (a dokładniej aktualności tej ich części, która jest odpowiedzialna za aktualizację struktur danych).
Podczas generowania skryptu SQL dla każdej struktury danych generowany jest także wpis, w którym zawarty jest identyfikator tej struktury i suma kontrolna (MD5) dla wygenerowanego skryptu:
-- TABLE ID: ac9cc77f-b7c2-4901-9c54-84f4dd285017, MD5: 39f8f2c375ee37ac4204f5d75e4a2617 –
(w przypadku, gdy dla danej struktury wpisy występują w wielu plikach skryptów SQL użytkownika, wówczas brany jest pod uwagę najnowszy wpis)
Wartość ta jest porównywana z sumą kontrolną wygenerowaną dla bieżącego stanu obiektu. Jeśli się one różnią, wówczas dla danej struktury generowany jest skrypt SQL.
Weryfikacja skryptów
- W celu weryfikacji dodanych skryptów wybierz z menu Narzędzia opcję Zweryfikuj skrypty SQL użytkownika.
- W kolejnym oknie wybierz Start. Poza informacją czy skrypt jest poprawny bądź nie, uzyskasz także informację czy skrypt został już wykonany dla środowiska czy nie. Wykonywanie skryptów odbywa się w VSoft archITekt Launcher patrz: Zarządzanie skryptami w VSoft archITek Launcher.
Zarządzanie skryptami w VSoft archITek Launcher
Zarządzanie skryptami dodanymi przez użytkownika, odbywa się w VSoft archITekt Launcher.
- Jeżeli dodałeś skrypt w archITekt Studio i chcesz go wykonać (uruchomić), wówczas w VSoft archITekt Launcher rozwiń przycisk Manage przy danym projekcie, w sekcji MAINTENANCE rozwiń opcję Upgrade i wybierz Upgrade project. Wraz z aktualizacją środowiska zostaną wykonane wszystkie nowo dodane skrypty.
- W celu przejścia do okna zarządzania skryptami rozwiń przycisk Manage przy danym projekcie i w sekcji DATA wybierz opcję Manage user SQL scripts.
Na liście prezentowane są wszystkie skrypty dodane przez użytkownika wraz z informacją czy zostały wykonane czy nie.
- Opcja Rewind (cofnięcie) przesuwa wskaźnik wykonania na pozycję tuż przed zaznaczonym skryptem - po aktualizacji projektu ten skrypt oraz wszystkie o numerach wyższych zostaną (ponownie) wykonane.
- Nie można cofnąć się do skryptu, który nie został jeszcze uruchomiony, lub którego numer jest wyższy niż ostatnio wykonanego skryptu.
- W tym przypadku ostatnio wykonany skrypt to U.0040.
- Zaznacz skrypt U.0020.CreateView.sql i wybierz przycisk Rewind.
- Wskaźnik wykonania zostanie ustawiony tuż przed skryptem U.0020.CreateView.sql - teraz to skrypt U.0010.InitialScript.sql jest traktowany jako ostatnio wykonany, a wszystkie skrypty od U.0020 wzwyż otrzymają status WaitingToRun i zostaną uruchomione podczas kolejnej aktualizacji projektu.
W ramach procedury aktualizacji aplikacji na bazie danych wykonywane są wyłącznie „nowe” skrypty. „Nowe skrypty”, to skrypty o numerach większych niż numer ostatnio wykonanego skryptu, który zakończył się sukcesem.