Comment documenter une base de données
(Remarque: je me rends compte que cela est proche de Comment documentez-vous la structure de votre base de données? , mais je ne pense pas qu'elle soit identique.)
J'ai commencé à travailler dans un endroit avec une base de données avec littéralement des centaines de tables et de vues, toutes avec des noms cryptiques avec 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 pas toucher à une autre base de données à l'exception de celle de test sur ma propre machine (qui est époustouflée et recréée régulièrement), donc je ne peux pas ajouter de commentaires qui aideraient qui que ce soit.
J'ai essayé d'utiliser "Toad" pour créer un diagramme ER, mais après l'avoir laissé fonctionner pendant 48 heures d'affilée, il n'avait toujours rien produit de visible et j'avais besoin de mon ordinateur. Je parlais à d'autres embauches récentes et nous avons tous suggéré que chaque fois que nous devinions ce qu'une table particulière ou ce que certaines de ses colonnes signifient, nous devrions la mettre à jour dans le wiki des développeurs.
Alors, quelle est la bonne façon de procéder? Énumérez simplement les tableaux/vues et leurs colonnes et remplissez-les au fur et à mesure? Les outils de base que j'ai à ma disposition sont Toad, Oracle "SQL Developer", MS Office et Visio.
D'après mon expérience, les diagrammes ER (ou UML) ne sont pas l'artefact le plus utile - avec un grand nombre de tableaux, les diagrammes (en particulier ceux à ingénierie inverse) sont souvent un gros gâchis alambiqué dont personne n'apprend rien.
Pour mon argent, une bonne documentation lisible par l'homme (peut-être complétée par des diagrammes de petites parties du système) vous donnera le plus de kilométrage. Cela comprendra, pour chaque tableau:
- Descriptions de la signification de la table et de son utilisation fonctionnelle (dans l'interface utilisateur, etc.)
- Descriptions de la signification de chaque attribut, si ce n'est pas évident
- Explications des relations (clés étrangères) de cette table aux autres, et vice-versa
- Explications des contraintes et/ou déclencheurs supplémentaires
- Explication supplémentaire des principaux points de vue et processus qui touchent la table, s'ils ne sont pas déjà bien documentés
Avec tout ce qui précède, ne documentez pas à des fins de documentation - une documentation qui réaffirme l'évidence ne fait qu'empêcher les gens. Au lieu de cela, concentrez-vous sur ce qui vous a dérouté au début et passez quelques minutes à écrire des explications très claires et concises. Cela vous aidera à y réfléchir et cela massivement aidera les autres développeurs qui accèdent à ces tables 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, comme Enterprise Architect , Red Gate SQL Doc , et les outils intégrés de divers fournisseurs . Mais bien que la prise en charge des outils soit utile (et même critique, dans les grandes bases de données), faire le travail acharné de comprendre et expliquer le modèle conceptuel de la base de données est la vraie victoire. De ce point de vue, vous pouvez même le faire dans un fichier texte (bien que le faire sous forme Wiki permettrait à plusieurs personnes de collaborer pour ajouter à cette documentation de manière incrémentielle - donc, chaque fois que quelqu'un comprend quelque chose, il peut l'ajouter au corps en pleine croissance). de la documentation instantanément).
Dans notre équipe, nous avons trouvé une approche utile pour documenter les grandes bases de données Oracle et SQL Server héritées. Nous utilisons Dataedo pour documenter les éléments de schéma de base de données (dictionnaire de données) et créer des diagrammes ERD. Dataedo est livré avec un référentiel de documentation pour que toute votre équipe puisse travailler sur la documentation et la lecture de la documentation récente en ligne. Et vous n'avez pas besoin d'interférer avec la base de données (commentaires Oracle ou SQL Server MS_Description).
Vous importez d'abord le schéma (toutes les tables, vues, procédures stockées et fonctions - avec déclencheurs, clés étrangères, etc.). Ensuite, vous définissez des domaines/modules logiques et regroupez tous les objets (glisser-déposer) afin de pouvoir analyser et travailler sur de plus petits morceaux de base de données. Pour chaque module, vous créez un diagramme ERD et rédigez une description de niveau supérieur. Ensuite, pendant que vous découvrez la signification des tableaux et des vues, écrivez une brève description pour chacun. Faites de même pour chaque colonne. Dataedo vous permet d'ajouter un titre significatif pour chaque objet et colonne - il est utile si les noms d'objets sont vagues ou invalides. La version Pro vous permet de décrire les clés étrangères, les clés/contraintes uniques et les déclencheurs - ce qui est utile mais pas essentiel pour comprendre une base de données.
Vous pouvez accéder à la documentation via l'interface utilisateur ou l'exporter vers PDF ou HTML interactif (ce dernier n'est disponible qu'en version Pro).
Décrit ici est un processus continu plutôt qu'un emploi unique. Si votre base de données change (par exemple, nouvelles colonnes, vues), vous devez synchroniser votre documentation régulièrement (quelques clics avec Dataedo).
Voir un exemple de documentation: http://dataedo.com/download/Dataedo%20repository.pdf
Quelques directives sur le processus de documentation:
Diagrammes:
- Gardez vos diagrammes petits et lisibles - incluez simplement les tableaux, relations et colonnes importants - uniquement ceux qui ont une signification pour comprendre la vue d'ensemble - clés primaires/commerciales, attributs et relations importants,
- Utilisez une couleur différente pour les tableaux clés dans un diagramme,
- Vous pouvez avoir plus d'un diagramme par module,
- Vous pouvez ajouter un diagramme à la description des tables les plus importantes/avec la plupart des relations.
Descriptions:
- Ne documentez pas l'évidence - n'écrivez pas la description "Document date" pour la colonne document.date. S'il n'y a rien de significatif à ajouter, laissez-le vide,
- Si les objets stockés dans des tables ont des types ou des statuts, il est bon de les répertorier dans la description générale d'une table,
- Définissez le format attendu, par exemple. "Mm/jj/aa" pour une date stockée dans le champ de texte,
- Énumérez toutes les valeurs connues/importantes et leur signification, par ex. pour la colonne d'état pourrait ressembler à ceci: "État du document: A - Actif, C - Annulé, D - Supprimé",
- S'il existe une API dans une table - une vue qui doit être utilisée pour lire les données et les fonctions/procédures pour insérer/mettre à jour des données - répertoriez-la dans la description de la table,
- Décrire d'où viennent les valeurs des lignes/colonnes (procédure, formulaire, interface, etc.),
- Utilisez la marque "[obsolète]" (ou similaire) pour les colonnes qui ne doivent pas être utilisées (la colonne de titre est utile pour cela, expliquez quel champ doit être utilisé à la place dans le champ de description).
Une chose à considérer 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 dans le système de base de données.
L'utilisation de la fonction COMMENTAIRE n'apporte aucune modification au schéma lui-même, il ajoute uniquement des données à la table de catalogue USER_TAB_COMMENTS.
Nous utilisons Enterprise Architect pour nos définitions de base de données. Nous incluons les procédures stockées, les déclencheurs et toutes les définitions de table définies dans UML. Les trois fonctionnalités brillantes du programme sont:
- Importez des diagrammes UML à partir d'une connexion ODBC.
- Générer des scripts SQL (DDL) pour la base de données entière à la fois
- Générez une documentation sur mesure de votre base de données.
Vous pouvez modifier vos définitions de classe/table dans l'outil UML et générer un document entièrement descriptif avec des images incluses. 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 assez gérable.
Je n'ai jamais été plus impressionné par un autre outil depuis plus de 10 ans en tant que 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 à mes problèmes rapidement. Hautement recommandé!!
Lorsque les modifications de la base de données arrivent, nous les effectuons dans EA, générons le SQL et le vérifions dans notre contrôle de version (svn). Nous utilisons Hudson pour la construction, et il construit automatiquement la base de données à partir de scripts lorsqu'il voit que vous avez modifié le sql enregistré.
Voici un bon article sur la façon d'aborder la documentation de la base de données: http://www.simple-talk.com/sql/database-administration/database-documentation---lands-of-trolls-why-and -comment /
Une solution wiki prend en charge les liens hypertexte et l'édition collaborative, mais un wiki n'est aussi bon que les personnes qui le maintiennent organisé et à jour. Vous avez besoin de quelqu'un pour s'approprier le projet de document, quel que soit l'outil que vous utilisez. Cette personne peut impliquer d'autres personnes bien informées pour remplir les détails, mais une personne devrait être responsable de l'organisation des informations.
Si vous ne pouvez pas utiliser un outil pour générer un ERD par rétro-ingénierie, vous devrez en concevoir un à la main à l'aide de TOAD ou VISIO.
Tout ERD avec des centaines d'objets est probablement inutile comme guide pour les développeurs, car il sera illisible avec autant de boîtes et de lignes. Dans une base de données avec autant d'objets, il est probable qu'il existe des "sous-systèmes" de quelques dizaines de tables et de vues chacun. Vous devez donc créer des diagrammes personnalisés de ces sous-systèmes, au lieu d'attendre qu'un outil le fasse pour vous.
Vous pouvez également concevoir une pseudo-ERD, où les groupes de tables sont représentés par un seul objet dans un diagramme, et ce groupe est développé dans un autre diagramme.
Un seul ERD ou un ensemble d'ERD ne sont pas suffisants pour documenter un système de cette complexité, pas plus qu'un diagramme de classes ne serait suffisant pour documenter un système OO. Vous devrez écrire un document , en utilisant les ERD comme illustrations. Vous avez besoin de descriptions textuelles de la signification et de l'utilisation de chaque table, de chaque colonne et des relations entre les tables (en particulier lorsque ces relations sont implicites au lieu d'être représentées par des contraintes d'intégrité référentielle).
Tout cela représente beaucoup de travail, mais cela en vaudra la peine. S'il existe un endroit clair et à jour où le schéma est documenté, toute l'équipe en bénéficiera.
Cette réponse prolonge Kieveli ci-dessus, que j'ai surévalué. Si votre version d'EA prend en charge la modélisation de rôle d'objet (conception conceptuelle ou conception logique = ERD), procédez à une ingénierie inverse, puis remplissez le modèle avec la richesse expressive qu'il vous donne.
L'option bon marché et plus légère consiste à télécharger Visiomodeler gratuitement depuis MS, et à faire de même avec cela.
L'ORM (appelez-le ORMDB) est le seul outil que j'ai jamais trouvé qui supporte et encourage les conversations de conception de base de données avec des parties prenantes non-SI sur les objets BL et les relations.
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 quant à savoir s'il fait quelque chose de délicat. Ce n'est pas le cas. Cela vous montrera probablement des faiblesses dans 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.
Si la description de vos bases de données à vos utilisateurs finaux est votre objectif principal Ooluk Data Dictionary Manager peut s'avérer utile. Il s'agit d'un logiciel multi-utilisateurs basé sur le Web qui vous permet de joindre des descriptions aux tableaux et colonnes et permet des recherches en texte intégral sur ces descriptions. Il vous permet également de grouper logiquement des tables à l'aide d'étiquettes et de parcourir les tables à l'aide de ces étiquettes. Les tableaux ainsi que les colonnes peuvent être étiquetés pour trouver des éléments de données similaires dans votre base de données/bases de données.
Le logiciel vous permet d'importer des informations de métadonnées telles que le nom de la table, le nom de la colonne, le type de données de la colonne, les clés étrangères dans son référentiel interne à l'aide d'une API. La prise en charge des sources de données JDBC est intégrée et peut être étendue à mesure que la source API est distribuée sous ASL 2.0. Il est codé pour lire les COMMENTAIRES/REMARQUES de nombreux SGBDR. Vous pouvez toujours remplacer manuellement les informations importées. Les informations que vous pouvez stocker sur les tables et les colonnes peuvent être étendues à l'aide de champs personnalisés.
Le gestionnaire de dictionnaire de données utilise la terminologie "objet de données" et "attribut" au lieu de la table et de la colonne car il n'est pas conçu spécifiquement pour les bases de données relationnelles.
Remarques
- Si la description des aspects techniques de votre base de données tels que les déclencheurs, les index et les statistiques est importante, ce logiciel n'est pas la meilleure option. Il est cependant possible de combiner une solution technique avec ce logiciel en utilisant des champs hyperliens personnalisés.
- Le logiciel ne produit pas d'ERD
Divulgation: je travaille dans l'entreprise qui développe ce produit.
Étant donné que vous avez le luxe de travailler avec d'autres développeurs qui sont dans le même bateau, je suggère de leur demander ce qui, selon eux, transmettrait les informations nécessaires, le plus facilement. Mon entreprise possède plus de 100 tables, et mon patron m'a donné un ERD pour un ensemble spécifique de tables qui se connectent toutes. De même, vous voudrez peut-être essayer de diviser 1 ERD massif en un groupe d'ERD plus petits et plus faciles à gérer.
Eh bien, une image dit mille mots, donc je recommanderais de créer des diagrammes ER où vous pouvez voir la relation entre les tableaux en un coup d'œil, ce qui est difficile à faire avec une description en texte uniquement.
Vous n'avez pas à regrouper toute la base de données dans un seul diagramme, divisez-la en sections. Nous utilisons Visual Paradigm au travail, mais EA est une bonne alternative tout comme ERWIN, et il y a sans aucun doute beaucoup d'autres qui sont tout aussi bons.
Si vous avez la patience, l'utilisation de html pour documenter les tableaux et les colonnes facilite l'accès à votre documentation.