Come documentate la struttura del vostro database? [chiuso]

Question

Molti sistemi di database non consentono commenti o descrizioni di tabelle e campi, quindi come si fa a documentare lo scopo di una tabella / campo oltre all'ovvio di avere buone convenzioni di denominazione?

(Supponiamo per ora che i nomi di tabella e campo "eccellenti" non siano sufficienti per documentare il significato completo di ogni tabella, campo e relazione nel database.)

So che molte persone usano i diagrammi UML per visualizzare il database, ma raramente, se mai, ho visto un diagramma UML che include commenti sul campo. Tuttavia, ho una buona esperienza nell'uso dei commenti all'interno dei file .sql . L'aspetto negativo di questo approccio è che richiede che i file .sql siano tenuti aggiornati manualmente quando la struttura del database cambia nel tempo, ma se lo fai, puoi anche averlo sotto il controllo della versione .

Alcune altre tecniche che ho visto sono documenti separati che descrivono la struttura e le relazioni del database e i commenti gestiti manualmente all'interno del codice ORM o di altro codice di mappatura del database.

Come hai risolto questo problema in passato? Quali metodi esistono e quali sono i vari pro e contro associati ad essi? Come vorresti che fosse risolto in "un mondo perfetto"?

Aggiorna

Come altri hanno sottolineato, la maggior parte dei popolari motori SQL consente infatti commenti, il che è fantastico. Stranamente, le persone non sembrano usare molto queste funzionalità. Almeno non sui progetti in cui sono stato coinvolto in passato.

Answer 1

MySQL consente commenti su tabelle e righe. Anche PostgreSQL funziona . Da altre risposte, anche Oracle e MSSQL hanno commenti.

Per me, una combinazione di diagramma UML per un rapido aggiornamento di nomi di campo, tipi e vincoli e un documento esterno (TeX, ma potrebbe essere qualsiasi formato) con una descrizione estesa di tutto ciò che riguarda il database - valori speciali, campo commenti, note d'accesso, qualunque cosa funzioni meglio.

Answer 2

In ritardo ma, si spera, utile & # 8230; Ecco un processo che abbiamo usato durante lo sviluppo di database relativamente grandi (circa 100 tabelle e circa 350 oggetti in totale)

• Gli sviluppatori dovevano utilizzare le proprietà estese per aggiungere dettagli a tutti gli oggetti.
• Gli amministratori hanno rifiutato qualsiasi DDL che non avesse proprietà estese
• Lo strumento di terze parti è stato utilizzato ogni giorno per generare automaticamente documentazione visiva tramite l'interfaccia della riga di comando. Abbiamo usato ApexSQL Doc e ha funzionato bene, ma ho anche usato con successo SQL Doc di Red Gate in altri azienda.

Questo processo ha garantito che tutti gli oggetti siano documentati e documentati aggiornati.

La cosa difficile, però, era convincere gli sviluppatori a scrivere buoni commenti in modo coerente;)

Answer 3

SQL Server ha proprietà estese che possono occuparsene.

Questo articolo descrive come configurarli in SQL Sever http://www.developer.com/db/article.php/3677766

Riferimento MSDN

Può essere utilizzato insieme a RedGate SQL Doc per creare un bel dizionario dei dati.

Answer 4

Uso i commenti allegati a tabelle e colonne. SchemaSpy è un ottimo strumento per generare file di documentazione html dal tuo schema, inclusi i commenti.

Answer 5

A un certo punto ho scritto un parser SQL di base che analizzerebbe le istruzioni CREATE TABLE e eliminerebbe i commenti appositamente formattati. Questi sono stati quindi post-elaborati nel sorgente LaTeX e resi in PDF. Questo è stato ispirato da Javadoc ed è stato utilizzato per creare la documentazione per Questo prodotto . Successivamente è stata integrata una funzione del dizionario dei dati nel gestore del magazzino e una versione modificata del generatore LaTeX è stata utilizzata per eseguire il rendering del dizionario dei dati dal gestore del magazzino.

In un altro progetto ho usato Visio: la versione fornita con Visual Studio Enterprise Architect inoltrerà un database. L'SQL così generato aveva il rendering dei commenti di tabella e colonna in stringhe di commenti che erano abbastanza semplici da analizzare. Lo strumento che ho scritto ha generato file MIF che sono stati inclusi in un documento di specifica creato con FrameMaker.

Se si dispone di uno strumento di repository come Powerdesigner è possibile mantenere i modelli di dati in e ottenere rapporti sul repository che includono la documentazione che hai inserito. Se hai bisogno di una più profonda integrazione del dizionario dei dati con le specifiche funzionali (abbastanza utile per i sistemi di data warehouse in cui l'ETL è complesso e comporta un calcolo significativo dei valori derivati) puoi comunque estrarre i metadati e scrivere un'utilità per generare qualcosa che integri i dati dizionario in un documento di specifica. Ciò consente anche riferimenti incrociati tra voci del dizionario dei dati e altri documenti di specifica e generazione di indici che coprono le definizioni del dizionario dei dati e la relativa documentazione come una specifica di come viene calcolato qualcosa con esempi.

Answer 6

Abbiamo scritto un documento word che elenca le tabelle, i campi e cosa fa tutto. Questo è supportato da un diagramma che mostra come tutto si collega / si collega l'un l'altro. È davvero un documento piuttosto semplice, solo un sacco di tabelle con Field Name > Tipo di dati > Scopo

Answer 7

Sto usando Firebird che ha un campo di descrizione per tutti gli oggetti di sistema (tabelle, colonne, viste, procedure e parametri, trigger, ecc.) È bello perché puoi facilmente condividerlo con altri (i documenti vanno con il database, non separatamente) e non lo perdi mai.

La maggior parte degli amministratori. gli strumenti per Firebird ti consentono di modificare queste descrizioni e ci sono alcuni strumenti specializzati (come IBDesc, per esempio) che creano simpatici report HTML o PDF che puoi stampare (per alcune o tutte le tabelle) facilmente.

Answer 8

È un approccio davvero semplicistico, ma utilizzo un paio di pagine wiki: una con il mysqldump del database e una scritta in un formato leggermente più inglese.

Per i progetti a cui ho lavorato, è stato sufficiente (attraverso le decine di tabelle). Non so quanto potrebbe adattarsi a progetti più grandi (diciamo nelle centinaia di tabelle), ma finora è stato buono.

Answer 9

Commento i miei database mentre commento i miei programmi. Scrivendo buoni (spero) commenti nel codice sorgente (il file SQL contenente le istruzioni DDL).

L'uso di SQL COMMENT è un'altra possibilità. La cosa buona con loro è che sono sempre con i tuoi oggetti, sono sottoposti a backup con loro, ecc. La cosa brutta è che sono più limitati (per esempio in lunghezza).

Answer 10

Poiché utilizziamo Rational Software Architect, utilizziamo le sue funzionalità di rilevamento dei dati per documentare i nostri database e quindi annotarli da lì.

Answer 11

In Oracle puoi commentare le tabelle e memorizzarle nel dizionario dei dati.

Tuttavia, memorizzo tutti i miei commenti di tabella, colonna e indice in una versione molto vecchia di ERWin. È la principale fonte di verità e genera il DDL per creare tabelle, ecc. Da lì, posso estrarlo in un documento word o pdf.

Answer 12

Di recente ho iniziato a scrivere la documentazione di markdown, che include il collegamento ai singoli file .sql della tabella (dove si spera che le tabelle e i campi siano nominati in modo intuitivo con molti commenti).

Mantengo i singoli schemi di tabella nel controllo versione, usando il seguente comando:

mysqldump --no-data --tab =. / tables dbname

Lo schema di una singola tabella ti permette di vedere commenti, indici, chiavi univoche ecc. quindi è abbastanza autoesplicativo (almeno questa è l'idea).

La documentazione principale del markdown ha collegamenti ipertestuali come la tabella degli utenti in tutto il mondo, in modo che il lettore possa facilmente passare alle diverse tabelle.