Come documentare un database

Question

(Nota:. Mi rendo conto che questo è vicino a How do you document your database structure?, ma non credo che sia identico)

ho iniziato a lavorare in un posto con un database con centinaia di tavoli e viste, tutte con nomi criptici con pochissime vocali e nessuna documentazione. Inoltre non consentono modifiche gratuite allo schema del database, né posso toccare alcun database tranne quello di test sulla mia macchina (che viene spazzato via e ricreato regolarmente), quindi non posso aggiungere commenti che possano aiutare nessuno.

Ho provato a utilizzare "Rospo" per creare un diagramma ER, ma dopo averlo lasciato funzionare per 48 ore consecutive non aveva ancora prodotto nulla e avevo bisogno del mio computer. Stavo parlando con altre assunzioni recenti e tutti noi abbiamo suggerito che ogni volta che abbiamo sconcertato cosa sia una determinata tabella o cosa significhi una parte delle sue colonne, dovremmo aggiornarla nella wiki degli sviluppatori.

Quindi, qual è il modo migliore per farlo? Basta elencare tabelle/viste e le loro colonne e riempirle come andiamo? Gli strumenti di base che ho a portata di mano sono Toad, Oracle "SQL Developer", MS Office e Visio.

Answer 1

Nella mia esperienza, i diagrammi ER (o UML) non sono l'artefatto più utile: con un gran numero di tabelle, i diagrammi (specialmente quelli in reverse engineering) sono spesso un caos complicato da cui nessuno impara nulla.

Per i miei soldi, una buona documentazione leggibile dall'uomo (magari integrata con diagrammi di parti più piccole del sistema) vi darà il maggior chilometraggio. Ciò includerà, per ogni tabella:

• Descrizioni di cosa significa la tabella e di come è funzionalmente utilizzata (nell'interfaccia utente, ecc.)
• descrizioni di ciò ogni attributo significa che, se non è evidente
• spiegazioni delle relazioni (chiavi esterne) da questa tabella agli altri, e viceversa
• dichiarazioni di ulteriori vincoli e/o trigger
• aggiuntive spiegazione delle principali vedute & procs che toccano il tavolo, se non sono ben documentati già

Con tutto quanto sopra, non documentare per il bene di documentare - la documentazione che ribadisce l'ovvio solo entra nella gente. Invece, concentrati sulle cose che ti hanno confuso all'inizio e trascorri qualche minuto scrivendo spiegazioni chiare e concise. Questo ti aiuterà a riflettere e sarà massicciamente aiutare gli altri sviluppatori che eseguono queste tabelle per la prima volta.

Come altri hanno già menzionato, ci sono una grande varietà di strumenti per aiutarvi a gestire questo, come Enterprise Architect, Red Gate SQL Doc e gli strumenti integrati di vari fornitori. Ma mentre il supporto degli strumenti è utile (e anche critico, in database più grandi), fare il duro lavoro di comprensione e spiegando il modello concettuale del database è la vera vittoria. Da quella prospettiva, puoi anche farlo in un file di testo (anche se farlo in forma Wiki permetterebbe a più persone di collaborare ad aggiungere a quella documentazione in modo incrementale - così, ogni volta che qualcuno capisce qualcosa, può aggiungerlo al corpo in crescita di documentazione all'istante).

Answer 2

Dal momento che si ha il lusso di lavorare con altri sviluppatori che si trovano sulla stessa barca, suggerirei di chiedere loro ciò che ritengono avrebbe trasmesso le informazioni necessarie, più facilmente. La mia azienda ha oltre 100 tavoli e il mio capo mi ha dato un ERD per un set di tabelle specifiche che si connettono tutte. Quindi, potresti voler provare a infrangere 1 ERD di massa in un gruppo di ERD più piccoli e gestibili.

Answer 3

Una cosa da considerare è la funzione COMMENT incorporata nel DBMS. Se si inseriscono commenti su tutte le tabelle e tutte le colonne nel DBMS stesso, la documentazione sarà all'interno del sistema di database.

L'utilizzo della funzione COMMENT non apporta modifiche allo schema stesso, ma aggiunge solo dati alla tabella del catalogo USER_TAB_COMMENTS.

Answer 4

Per le definizioni del DB viene utilizzato Enterprise Architect. Includiamo stored procedure, trigger e tutte le definizioni di tabella definite in UML. Le tre eccezionali caratteristiche del programma sono:

1. Importare diagrammi UML da una connessione ODBC.
2. Genera SQL Scripts (DDL) per l'intero DB in una volta
3. Genera Documentazione Templata personalizzata del DB.

È possibile modificare le definizioni di classe/tabella all'interno dello strumento UML e generare un documento descrittivo completo con immagini incluse. Il documento generato automaticamente può essere in più formati, tra cui MSWord. Abbiamo solo meno di 100 tabelle nel nostro schema ed è abbastanza gestibile.

Non sono mai stato più impressionato da nessun altro strumento nei miei 10 o più anni come sviluppatore. EA supporta Oracle, MySQL, SQL Server (versioni multiple), PostGreSQL, Interbase, DB2 e Access in un colpo solo. Ogni volta che ho avuto problemi, i loro forum hanno risposto prontamente ai miei problemi. Altamente raccomandato!!

Quando le modifiche di DB entrano, facciamo quindi in EA, generare l'SQL e controllarlo nel nostro controllo di versione (svn). Utilizziamo Hudson per la compilazione e il database viene compilato automaticamente dagli script quando viene visualizzato che hai modificato lo sql archiviato.

(Mostly stolen from another answer of mine)

Answer 5

Una soluzione wiki supporta collegamenti ipertestuali e editing collaborativo, ma un wiki è solo buono come le persone che mantengono organizzati e aggiornati. Hai bisogno che qualcuno diventi proprietario del progetto del documento, indipendentemente dallo strumento che usi. Quella persona può coinvolgere altre persone esperte per compilare i dettagli, ma una persona dovrebbe essere responsabile dell'organizzazione delle informazioni.

Se non è possibile utilizzare uno strumento per generare un ERD mediante il reverse engineering, è necessario progettarne uno a mano utilizzando TOAD o VISIO.

Qualsiasi ERD con centinaia di oggetti è probabilmente inutile come guida per gli sviluppatori, perché sarà illeggibile con così tante scatole e linee. In un database con così tanti oggetti, è probabile che ci siano "sottosistemi" di poche decine di tabelle e viste ciascuno. Quindi dovresti creare diagrammi personalizzati di questi sottosistemi, invece di aspettarti che uno strumento lo faccia per te.

È inoltre possibile progettare uno pseudo-ERD, in cui i gruppi di tabelle sono rappresentati da un singolo oggetto in un diagramma e tale gruppo viene espanso in un altro diagramma.

Un singolo ERD o un set di ERD non sono sufficienti per documentare un sistema di questa complessità, così come non sarebbe sufficiente un diagramma di classe per documentare un sistema OO. Dovrai scrivere un documento, usando gli ERD come illustrazioni. Sono necessarie descrizioni testuali del significato e dell'utilizzo di ciascuna tabella, ogni colonna e le relazioni tra tabelle (specialmente laddove tali relazioni sono implicite anziché rappresentate da vincoli di integrità referenziale).

Tutto questo è molto lavoro, ma ne varrà la pena. Se c'è un luogo chiaro e aggiornato in cui lo schema è documentato, l'intero team ne beneficerà.

Answer 6

Questa risposta estende la suddetta di Kieveli, che ho svalutato. Se la tua versione di EA supporta Object Role Modeling (progettazione concettuale, design logico = ERD), esegui il reverse engineering su questo e poi riempi il modello con la ricchezza espressiva che ti offre.

L'opzione economica e più leggera è quella di scaricare Visiomodeler gratuitamente da MS, e fare lo stesso con quello.

L'ORM (chiamalo ORMDB) è l'unico strumento che abbia mai trovato che supporta e incoraggia conversazioni di progettazione di database con soggetti interessati non appartenenti alla IS sugli oggetti e le relazioni BL.

Controllo della realtà: il modo in cui generare il DDL passa attraverso una fase di ERD completa in cui è possibile soddisfare le vostre domande sull'eventualità di fare qualcosa di avvincente. Non è così. Probabilmente ti mostrerà punti deboli nell'ERD che hai progettato tu stesso.

ORMDB è un caso classico del principio che più lo strumento è concettuale, più piccolo è il mercato. Le ragazze vogliono solo divertirsi e i programmatori vogliono solo programmare.

Answer 7

Bene, un'immagine rappresenta più di mille parole, quindi consiglierei di creare diagrammi ER in cui è possibile visualizzare la relazione tra i tavoli a prima vista, qualcosa che è difficile fare con una descrizione di solo testo.

Non è necessario eseguire l'intero database in un diagramma, suddividerlo in sezioni. Usiamo Visual Paradigm al lavoro ma EA è una buona alternativa come ERWIN, e senza dubbio ci sono molti altri che sono altrettanto buoni.

Se si ha la pazienza, quindi l'utilizzo di html per documentare tabelle e colonne facilita l'accesso alla documentazione.

Answer 8

Ecco un buon post su come affrontare la documentazione del database: http://www.simple-talk.com/sql/database-administration/database-documentation---lands-of-trolls-why-and-how/

Answer 9

Nel nostro team siamo venuti a approccio utile a documentare grandi database Oracle e SQL Server legacy. Utilizziamo Dataedo per documentare gli elementi dello schema del database (dizionario dei dati) e creare diagrammi ERD. Dataedo viene fornito con il repository della documentazione in modo che tutto il tuo team possa lavorare sulla documentazione e sulla lettura della documentazione recente online. E non è necessario interferire con il database (commenti Oracle o SQL Server MS_Description).

Prima di importare lo schema (tutte le tabelle, le viste, le stored procedure e le funzioni - con trigger, chiavi esterne, ecc.). Quindi si definiscono domini/moduli logici e raggruppare tutti gli oggetti (trascinare & di rilascio) in essi per poter analizzare e lavorare su blocchi di database più piccoli. Per ogni modulo si crea un diagramma ERD e si scrive una descrizione di livello superiore. Quindi, mentre scopri il significato di tabelle e viste, scrivi una breve descrizione per ciascuno. Fai lo stesso per ogni colonna. Dataedo ti consente di aggiungere titoli significativi per ogni oggetto e colonna: è utile se i nomi degli oggetti sono vaghi o non validi. La versione Pro consente di descrivere chiavi esterne, chiavi/vincoli e trigger univoci, il che è utile ma non essenziale per comprendere un database.

È possibile accedere alla documentazione tramite l'interfaccia utente o esportarla in PDF o HTML interattivo (quest'ultimo è disponibile solo nella versione Pro).

Descritto qui è un processo continuo piuttosto che un lavoro a tempo. Se il tuo database cambia (ad esempio nuove colonne, viste) dovresti sincronizzare la tua documentazione su base regolare (paio di clic con Dataedo).

vedere la documentazione del campione: http://dataedo.com/download/Dataedo%20repository.pdf

alcune linee guida su processo di documentazione:

Diagrammi:

• Tenere i diagrammi piccolo e leggibile - basta includono tavoli importanti, le relazioni e le colonne - solo il uno che ha un qualche significato per capire il quadro generale - chiavi principali/commerciali, attributi e relazioni importanti,
• Usa colori diversi per le tabelle chiave in un diagramma,
• Puoi avere più di un diagramma per modulo,
• Puoi aggiungere un diagramma alla descrizione delle tabelle più importanti/con la maggior parte delle relazioni.

Descrizioni:

• non documentano l'ovvio - non scrivono descrizione “Data documento” per la colonna document.date. Se non c'è niente significativo per aggiungere solo lasciarlo vuoto,
• Se gli oggetti memorizzati nelle tabelle hanno tipi o stati è bene elencarli nella descrizione generale di un tavolo,
• definire il formato che ci si aspetta, ad esempio. "Mm/gg/aa" per una data memorizzata nel campo di testo,
• Elencare tutti i valori noti/importanti e il relativo significato, ad es. per la colonna di stato potrebbe essere qualcosa del tipo: "Stato del documento: A - Attivo, C - Cancellato, D - Cancellato",
• Se c'è qualche API in una tabella - una vista che dovrebbe essere usata per leggere dati e funzioni/procedure inserire/aggiornare i dati - elencarlo nella descrizione della tabella,
• Descrivere da dove provengono i valori di righe/colonne (procedura, modulo, interfaccia ecc.),
• Utilizzare il segno "[deprecato]" (o simile) per le colonne che non dovrebbero essere utilizzate (la colonna del titolo è utile per questo, spiega quale campo dovrebbe essere usato invece nel campo della descrizione).

Answer 10

Se la descrizione dei database per gli utenti finali è il tuo obiettivo principale Ooluk Data Dictionary Manager può rivelarsi utile. Si tratta di un software multiutente basato sul web che consente di allegare descrizioni a tabelle e colonne e consente ricerche di testo complete su tali descrizioni. Consente inoltre di raggruppare le tabelle in modo logico utilizzando etichette e sfoglia tabelle utilizzando tali etichette. Le tabelle e le colonne possono essere taggati per trovare elementi di dati simili nel database/database.

Il software consente di importare informazioni di metadati come nome di tabella, nome colonna, tipo di dati di colonna, chiavi esterne nel proprio repository interno mediante un'API. Il supporto per le origini dati JDBC è integrato e può essere ulteriormente esteso in quanto la sorgente API è distribuita in ASL 2.0. È codificato per leggere i COMMENTI/OSSERVAZIONI di molti RDBMS. È sempre possibile sovrascrivere manualmente le informazioni importate. Le informazioni che è possibile memorizzare su tabelle e colonne possono essere estese utilizzando campi personalizzati.

Il responsabile del dizionario dati utilizza la terminologia "oggetto dati" e "attributo" anziché tabella e colonna perché non è progettato specificamente per i database relazionali.

Note

• Se descrivere gli aspetti tecnici della vostra base di dati quali le clausole, indici, statistiche è importante questo software non è l'opzione migliore. È tuttavia possibile combinare una soluzione tecnica con questo software utilizzando i campi personalizzati di collegamento ipertestuale.
• Il software non produce un disco di ripristino

Disclosure: io lavoro presso la società che sviluppa il prodotto.