Strona główna > Inne > Dokumentacja struktury bazy

Dokumentacja struktury bazy

Trochę o generowaniu dokumentacji, czyli dobrze kiedy znaczną jej cześć można właśnie wygenerować.
Miałem za zadanie stworzyć dokumentacje struktury bazy dla klienta. Mogłem zakasać rękawy i mozolnie pokrótce opisać każdą z tabel oraz jej powiązania z innymi tabelami (dokument głównie to miało zawierać). Całość przy około 250 tabelach mogło mi zająć około 3 dni🙂. Ponieważ nie było to naglące i miałem trochę luzu postanowiłem poszukać sposobów na automatyzacje tego. Ostatecznie zajęło mi to ponad 5 dni😉 (ale nie w całości poświęconych temu), no ale dzięki temu wykonanie ewentualnej aktualizacji jest teraz o wiele szybsze.

Co było przedmiotem dokumentacji?
Jak już wspomniałem główne oczekiwania co do dokumentacji to:

  • krótki opis do czego służy każda z tabel;
  • opis powiązań pomiędzy tabelami (odpowiedź na pytanie: klucz obcy w tabeli do jakiej innej tabeli prowadzi?).

Pierwsze założenie trudno zautomatyzować. Jest to zwykły tekst, który trzeba umieścić w wygodnym miejscu dla potrzeb przyszłej aktualizacji. Drugie założenie jest już czymś czym można się zająć. Tu ręczne pisanie tego w dokumencie byłoby monotonne i uciążliwe, a przez to podatne na pomyłki.

Użycie skryptów instalacyjnych
Jako że baza jest instalowana ze skryptów, to opis poszczególnych tabel wylądował tu. W głównym skrypcie instalacyjnym zostały umieszczone komentarze przy poszczególnych odwołaniach do właściwych skryptów tworzących każdą z tabel. Dokument (html) był generowany przez osobny program, który to czytał ten plik i odszukiwał tabele oraz powiązane z nim komentarze.
Takie było początkowe założenie i ono też ukierunkowało resztę wysiłków. Co może oznaczać, że w obranym podejściu mogłem zabrnąć w jakąś ślepą uliczkę i (na pewno) zapewne da się to lepiej zrobić.
Poprzez parsowanie plików chciałem także dobrać się do informacji o powiązaniach pomiędzy tabelami. Jeśli w pierwszym przypadku, przeszukiwanie jednego pliku i łączenie nazwy tabeli z odpowiednim komentarzem, było jeszcze proste, to parsowanie instrukcji sql i budowanie w pamięci relacji pomiędzy tabelami było większym wyzwaniem i po krótkich próbach odechciało mi się tej ścieżki.

Użycie narzędzi
No to zwróciłem się w kierunku narzędzi.
Miałem pod ręką kombajn z rodziny CASE, więc spróbowałem zaimportować definicje tabel i na podstawie tego stworzyć coś użytecznego. Dzięki temu dostałem możliwość generowania pięknych schematów i oczywiście dokumentacji. Zawierała ona informacje o tabelach i powiązaniach pomiędzy nimi, ale oprócz tego masę innych rzeczy, których do końca nie chciałem.
Postanowiłem zapoznać się lepiej z narzędziem i dopasować początkowy wynik do tego co chcę. Odkryłem że wymagałoby to:

  • stworzenia nowego szablonu, ponieważ dostępna jest tylko wersja angielska! Gdybym miał możliwość delegowania tej pracy na kogoś innego, to może warto byłoby to zrobić. Prosta generacja sztampowej dokumentacji przydatna byłaby nie tylko dla jednego projektu.
  • Trzeba jeszcze dodać opisy tabel. Można to zrobić poprzez modyfikacje wynikowego dokumentu, co może być zbyt mozolne i wrażliwe na ewentualne zmian. Można także przenieś opis do definicji tabel – zawarcia tego jako normalne komentarza na poziomie tabel (baza Oracle na to pozwala).
    To ostanie wydawało się sensowne, ale musiałbym zawrzeć (edytować) opisy w wielu plikach (skryptach). Nie było to aż takie kłopotliwe, jednak zostało odrzucone. Powodem tego było to, że skutkowałoby to wprowadzeniem zmian w zbyt wielu plikach (no i nie maił mi kto przetłumaczyć szablonu :D).
    Choć teraz już po fakcie myślę, że nie byłoby to takie głupie😉. Ale i tak rozmiar pracy, tworzony przez narzędzie, zniechęcił mnie. W skrócie byłoby to: zaznajomienie się z nim i przygotowanie własnego szablonu do generowania rozdmuchanej dokumentacji, którą później i tak bym musiała zawęzić.

Użycie bazy
Utknąłem. Sprawdziłem narzędzie i odkryciu że mimo swego bogactwa nie oferuje ono prostego rozwiązania dla wygenerowania dokumentu, który ma zawierać informacje o powiązaniach pomiędzy tabelami.
Jenak po uświadomieniu sobie, że potrzebuję właśnie tylko pewnej informacji, a nie gotowej dokumentacji, wróciłem do kontynuacji początkowego rozwiązania. Wtedy próbowałem wyciągnąć ją parsując pliki, ale dobrym spostrzeżeniem jest to, że tą samą informacje łatwiej można wyciągnąć z bazy. Po prostu należy zadać odpowiednie zapytanie, które zwróci informacje o strukturze bazy.
Odkrywcze było to, że można nie tylko pytać o dane w bazie, ale także o struktury w jakich są one trzymane. Dzięki temu wygenerowałem pośredni pliczek/raport z pożądaną informacją, to z kolei umożliwiło dokończyć proces generowania dokumentacji w sposób jaki chciałem.

Kluczowe jest właśnie to, że bazy oferują mechanizmy do zbierania takich rzeczy i że użycie tych rozwiązań może być pomocne w różnych sytuacjach.

Użyte zapytanie, zwracające informacje o wszystkich tabelach w schemacie zalogowanego użytkownika, to:

SELECT DISTINCT tab.table_name "Tabela", tab.column_name "kolumna",
                tab.nullable "Null?",
                CONCAT (CONCAT (CONCAT (tab.data_type, '('), tab.data_length), ')') "type",
                next_cons.table_name "zwiazek z tabela",
                next_cons.column_name "zwiazek z kolumna"
           FROM user_tab_columns tab LEFT OUTER JOIN user_cons_columns cons
                ON tab.table_name = cons.table_name
              AND tab.column_name = cons.column_name
                LEFT OUTER JOIN user_constraints cd
                ON cons.constraint_name = cd.constraint_name
                LEFT OUTER JOIN user_constraints next_cd
                ON next_cd.constraint_name = cd.r_constraint_name
                LEFT OUTER JOIN user_cons_columns next_cons
                ON next_cd.constraint_name = next_cons.constraint_name
          WHERE tab.table_name IN (SELECT table_name
                                     FROM user_tables)
ORDER BY        tab.table_name, tab.column_name

Wnioski na koniec
Spojrzenie jeszcze raz na ten temat (napisanie tego tekstu), doprowadziło mnie do stwierdzenia, że powinienem opisy tabel zawrzeć jako komentarze do nich poprze zwykłe instrukcje sql. Odpadłaby wtedy potrzeba wyciągania informacji poprzez parsowanie pliku. Wszystko sprowadziłoby się do następnego zapytania.
W przyszłości może się tak zrobi🙂.
Co do narzędzi to nie krytykuje ich. Jednak sens użycia ich w tym przypadku byłby bardziej celowy, kiedy całe to wytwarzanie dokumentacji było procesem długofalowym, a nie czymś co ma być już/zaraz.

  1. Brak komentarzy.
  1. No trackbacks yet.

Skomentuj

Wprowadź swoje dane lub kliknij jedną z tych ikon, aby się zalogować:

Logo WordPress.com

Komentujesz korzystając z konta WordPress.com. Log Out / Zmień )

Zdjęcie z Twittera

Komentujesz korzystając z konta Twitter. Log Out / Zmień )

Facebook photo

Komentujesz korzystając z konta Facebook. Log Out / Zmień )

Google+ photo

Komentujesz korzystając z konta Google+. Log Out / Zmień )

Connecting to %s

%d bloggers like this: