Comment documenter une base de données

Question

(Note : Je réalise que c'est proche de http://stackoverflow.com/questions/186392/how-do-you-document-your-database-structure mais je ne pense pas que ce soit identique).

J'ai commencé à travailler dans un endroit où la base de données contient littéralement des centaines de tables et de vues, toutes avec des noms cryptiques comportant très peu de voyelles, et aucune documentation. Ils n'autorisent pas non plus les modifications gratuites du schéma de la base de données, et je ne peux toucher à aucune base de données à l'exception de la base de test sur ma propre machine (qui est régulièrement détruite et recréée), ce qui fait que je ne peux pas ajouter de commentaires qui pourraient aider qui que ce soit.

J'ai essayé d'utiliser "Toad" pour créer un diagramme ER, mais après l'avoir laissé tourner pendant 48 heures d'affilée, il n'avait toujours rien produit de visible et j'avais besoin de récupérer mon ordinateur. Je discutais avec d'autres personnes récemment embauchées et nous avons tous suggéré que, chaque fois que nous avons compris la signification d'un tableau particulier ou de certaines de ses colonnes, nous devrions le mettre à jour dans le wiki des développeurs.

Quelle est la meilleure façon de procéder ? Juste lister les tables/vues et leurs colonnes et les remplir au fur et à mesure ? Les outils de base que j'ai sous la main sont Toad, le "SQL Developer" d'Oracle, MS Office et Visio.

Answer 1

D'après mon expérience, les diagrammes ER (ou UML) ne sont pas les artefacts les plus utiles - avec un grand nombre de tables, les diagrammes (en particulier les diagrammes de rétro-ingénierie) sont souvent un grand désordre alambiqué dont personne n'apprend rien.

À mon avis, une bonne documentation lisible par l'homme (éventuellement complétée par des diagrammes de petites parties du système) vous permettra d'obtenir les meilleurs résultats. Cela comprendra, pour chaque table :

• Descriptions de la signification du tableau et de son utilisation fonctionnelle (dans l'interface utilisateur, etc.)
• La description de la signification de chaque attribut, si elle n'est pas évidente.
• Explications des relations (clés étrangères) de cette table vers d'autres, et vice-versa.
• Explications des contraintes et / ou des déclencheurs supplémentaires
• Explication supplémentaire des principales vues et procédures qui touchent la table, si elles ne sont pas déjà bien documentées.

Dans tout ce qui précède, ne documentez pas pour le plaisir de documenter - une documentation qui répète ce qui est évident ne fait que gêner les gens. Au lieu de cela, concentrez-vous sur les éléments qui vous ont troublé au départ et passez quelques minutes à rédiger des explications claires et concises. Cela vous aidera à y réfléchir et à massivement aider les autres développeurs qui rencontrent ces tableaux pour la première fois.

Comme d'autres l'ont mentionné, il existe une grande variété d'outils pour vous aider à gérer cela, tels que Architecte d'entreprise , Doc SQL de la Porte Rouge et les outils intégrés de divers fournisseurs. Mais si l'assistance des outils est utile (et même cruciale, dans les bases de données plus importantes), faire le travail difficile de comprendre et expliquant le modèle conceptuel de la base de données est la véritable victoire. De ce point de vue, vous pouvez même le faire dans un fichier texte (bien que le faire sous la forme d'un Wiki permettrait à plusieurs personnes de collaborer à l'enrichissement progressif de cette documentation - ainsi, chaque fois que quelqu'un découvre quelque chose, il peut l'ajouter instantanément à l'ensemble croissant de la documentation).

Answer 2

Nous utilisons Architecte d'entreprise pour nos définitions de la DB. Nous incluons les procédures stockées, les triggers, et toutes les définitions de tables définies en UML. Les trois caractéristiques brillantes du programme sont :

1. Importer des diagrammes UML à partir d'une connexion ODBC.
2. Générer des scripts SQL (DDL) pour l'ensemble de la BD en une seule fois
3. Générer une documentation personnalisée de votre base de données.

Vous pouvez modifier vos définitions de classes et de tables dans l'outil UML et générer un document descriptif complet avec des images. Le document généré automatiquement peut être dans plusieurs formats, y compris MSWord. Nous avons un peu moins de 100 tables dans notre schéma, et c'est tout à fait gérable.

Je n'ai jamais été aussi impressionné par un autre outil depuis plus de 10 ans que je suis développeur. EA prend en charge Oracle, MySQL, SQL Server (plusieurs versions), PostGreSQL, Interbase, DB2 et Access d'un seul coup. Chaque fois que j'ai eu des problèmes, leurs forums ont répondu rapidement à mes problèmes. Hautement recommandé !

Lorsque des changements sont apportés à la base de données, nous les effectuons dans EA, générons le SQL et l'enregistrons dans notre système de contrôle de version (svn). Nous utilisons Hudson pour la construction, et il construit automatiquement la base de données à partir des scripts lorsqu'il voit que vous avez modifié le sql enregistré.

( Volé en grande partie d'une autre de mes réponses )

Answer 3

Un élément à prendre en compte est la fonction COMMENT intégrée au SGBD. Si vous mettez des commentaires sur toutes les tables et toutes les colonnes du SGBD lui-même, votre documentation se trouvera à l'intérieur du système de base de données.

L'utilisation de la fonction COMMENT n'apporte aucune modification au schéma lui-même, elle ajoute seulement des données à la table de catalogue USER_TAB_COMMENTS.

Answer 4

Voici un bon article sur la façon d'aborder la documentation sur les bases de données : http://www.simple-talk.com/sql/database-administration/database-documentation---lands-of-trolls-why-and-how/

Answer 5

Cette réponse prolonge celle de Kieveli ci-dessus, que j'ai votée. Si votre version d'EA prend en charge la modélisation des rôles d'objets (conception conceptuelle, par opposition à la conception logique = ERD), faites de la rétro-ingénierie en fonction de cette modélisation, puis complétez le modèle avec la richesse expressive qu'elle vous offre.

L'option la moins chère et la plus légère consiste à télécharger gratuitement Visiomodeler sur le site de MS, et à faire de même.

L'ORM (appelez-le ORMDB) est le seul outil que j'ai trouvé qui soutient et encourage les conversations sur la conception de la base de données avec les parties prenantes non-IS au sujet des objets et des relations BL.

Vérification de la réalité - sur le chemin de la génération de votre DDL, il passe par une phase ERD complète où vous pouvez répondre à vos questions pour savoir s'il fait quelque chose de louche. Ce n'est pas le cas. Il vous montrera probablement les faiblesses de l'ERD que vous avez conçu vous-même.

ORMDB est un cas classique du principe selon lequel plus l'outil est conceptuel, plus le marché est petit. Les filles veulent juste s'amuser, et les programmeurs veulent juste coder.