Comment documenter une firebase database

(Note: je me rends compte que c’est proche de Comment documentez-vous la structure de votre firebase database?, Mais je ne pense pas que ce soit identique.)

J’ai commencé à travailler à un endroit avec une firebase database avec des centaines de tables et de vues, toutes avec des noms cryptiques avec très peu de voyelles et sans documentation. Ils ne permettent pas non plus de modifier gratuitement le schéma de la firebase database, ni de toucher une firebase database autre que celle de test sur ma propre machine (qui est régulièrement détruite et recréée).

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, rien n’avait encore été visible et j’avais besoin de mon ordinateur. Je parlais à d’autres recrues récentes et nous avons tous suggéré que chaque fois que nous devions nous interroger sur ce qu’est une table particulière ou sur certaines colonnes, nous devrions la mettre à jour dans le wiki des développeurs.

Alors, comment faire ça? Juste énumérer des tables / vues et leurs colonnes et les remplir comme nous allons? Les outils de base que je peux utiliser sont Toad, Oracle “SQL Developer”, MS Office et Visio.

Dans mon expérience, les diagrammes ER (ou UML) ne sont pas les artefacts les plus utiles – avec un grand nombre de tableaux, les diagrammes (en particulier ceux à rétro-ingénierie) sont souvent un désordre compliqué dont personne n’apprend rien.

Pour mon argent, une bonne documentation lisible par l’homme (peut-être complétée par des schémas de petites portions du système) vous donnera le plus de kilométrage. Cela inclura, pour chaque table:

  • Descriptions de la signification de la table et de son utilisation fonctionnelle (dans l’interface utilisateur, etc.)
  • Description de ce que signifie chaque atsortingbut, si ce n’est pas évident
  • Explications des relations (clés étrangères) de cette table à d’autres et vice-versa
  • Explications de contraintes et / ou de déclencheurs supplémentaires
  • Explication supplémentaire des vues principales et des 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 dans le but de documenter – la documentation qui réitère l’évidence ne fait que gagner du terrain. Au lieu de cela, concentrez-vous sur les choses qui vous ont 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 aidera massivement les autres développeurs qui rencontrent 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. Cependant, même si le support des outils est utile (et même essentiel dans les bases de données plus importantes), il est essentiel de comprendre et d’ expliquer le modèle conceptuel de la firebase database. De ce sharepoint vue, vous pouvez même le faire dans un fichier texte (bien que le faire sous forme de wiki permettrait à plusieurs personnes de collaborer pour append de la documentation de manière incrémentale). de la documentation instantanément).

Une chose à considérer est la fonction COMMENT intégrée dans le SGBD. Si vous placez des commentaires sur toutes les tables et toutes les colonnes du SGBD, votre documentation se trouvera dans le système de firebase database.

L’utilisation de la fonction COMMENT 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 firebase database. Nous incluons les procédures stockées, les déclencheurs et toutes les définitions de table définies dans UML. Les trois caractéristiques shinyes du programme sont:

  1. Importer des diagrammes UML à partir d’une connexion ODBC.
  2. Générer des scripts SQL (DDL) pour la totalité de la firebase database en une fois
  3. Générer une documentation personnalisée basée sur des modèles de votre firebase database.

Vous pouvez éditer vos définitions de classe / table dans l’outil UML et générer un document entièrement descriptif avec les 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 maniable.

Je n’ai jamais été aussi impressionné par aucun autre outil au cours de mes 10 ans et plus en tant que développeur. EA prend en charge Oracle, MySQL, SQL Server (plusieurs versions), PostGreSQL, Interbase, DB2 et Access. 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 firebase database arrivent, nous créons alors dans EA, générons le code SQL et le vérifions dans notre contrôle de version (svn). Nous utilisons Hudson pour la construction, et il construit automatiquement la firebase database à partir de scripts lorsque vous voyez que vous avez modifié le fichier SQL installé.

( Surtout volé à une autre de mes réponses )

Dans notre équipe, nous avons découvert une approche utile pour documenter les grandes bases de données Oracle et SQL Server. Nous utilisons Dataedo pour documenter les éléments du schéma de firebase database (dictionnaire de données) et créer des diagrammes ERD. Dataedo est livré avec un référentiel de documentation afin 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 firebase database (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 des déclencheurs, des clés étrangères, etc.). Ensuite, vous définissez des domaines / modules logiques et regroupez tous les objects (drag & drop) pour pouvoir parsingr et travailler sur de plus petits blocs de firebase database. Pour chaque module, vous créez un diagramme ERD et écrivez la description de haut niveau. Ensuite, lorsque vous découvrez le sens des tableaux et des vues, écrivez une courte description pour chacun. Faites la même chose pour chaque colonne. Dataedo vous permet d’append un titre significatif pour chaque object et chaque colonne – il est utile que les noms d’object soient vagues ou non valides. La version Pro vous permet de décrire les clés étrangères, les clés / contraintes et les déclencheurs uniques, ce qui est utile mais pas essentiel pour comprendre une firebase database.

Vous pouvez accéder à la documentation via l’interface utilisateur ou l’exporter au format PDF ou HTML interactif (ce dernier est disponible uniquement dans la version Pro).

Décrit ici est un processus continu plutôt qu’un travail ponctuel. Si votre firebase database change (par exemple, nouvelles colonnes, vues), vous devez synchroniser votre documentation régulièrement (en quelques clics avec Dataedo).

Voir exemple de documentation: http://dataedo.com/download/Dataedo%20repository.pdf

Quelques lignes direcsortingces sur le processus de documentation:

Diagrammes:

  • Gardez vos diagrammes petits et lisibles – incluez seulement des tables, des relations et des colonnes importantes – seulement celui qui a un sens pour comprendre la grande image – clés primaires / commerciales, atsortingbuts et relations importants,
  • Utiliser des couleurs différentes pour les tableaux de clés dans un diagramme,
  • Vous pouvez avoir plus d’un diagramme par module,
  • Vous pouvez append 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 «Date du document» pour la colonne document.date. S’il n’y a rien d’important à append, laissez le champ vide.
  • Si les objects stockés dans les tables ont des types ou des états, il est bon de les répertorier dans la description générale d’une table,
  • Définir le format attendu, par exemple. «Mm / jj / aa» pour une date enregistrée dans un champ de texte,
  • Énumérez toutes les valeurs connues / importantes et leur signification, par exemple pour que la colonne d’état puisse être quelque chose comme ceci: «État du document: A – Actif, C – Annulé, D – Supprimé»,
  • S’il y a une API dans une table – une vue qui devrait être utilisée pour lire des données et des fonctions / procédures pour insérer / mettre à jour des données – listez-la dans la description du tableau,
  • 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).

Voici un bon post sur la manière d’aborder la documentation de la firebase database: http://www.simple-talk.com/sql/database-administration/database-documentation—lands-of-trolls-why-and-how/

Une solution wiki prend en charge les liens hypertextes et l’édition collaborative, mais un wiki est aussi efficace que les personnes qui le maintiennent organisé et à jour. Vous avez besoin de quelqu’un pour prendre possession du projet de document, quel que soit l’outil que vous utilisez. Cette personne peut faire appel à d’autres personnes compétentes pour renseigner les détails, mais une personne doit être responsable de l’organisation des informations.

Si vous ne pouvez pas utiliser un outil pour générer un ERD par reverse engineering, vous devrez en concevoir un à la main en utilisant TOAD ou VISIO.

Tout ERD avec des centaines d’objects est probablement inutile comme guide pour les développeurs, car il sera illisible avec autant de boîtes et de lignes. Dans une firebase database contenant autant d’objects, il existe probablement des “sous-systèmes” de quelques dizaines de tables et de vues chacun. Vous devriez donc créer des diagrammes personnalisés de ces sous-systèmes, au lieu d’attendre d’un outil qu’il le fasse pour vous.

Vous pouvez également concevoir un pseudo-ERD, où les groupes de tables sont représentés par un seul object dans un diagramme, et ce groupe est développé dans un autre diagramme.

Un seul DRE ou ensemble de DRE ne suffit pas à documenter un système de cette complexité, pas plus qu’un diagramme de classes ne suffirait à 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 et non représentées par des contraintes d’intégrité référentielle).

Tout cela demande beaucoup de travail, mais ça en vaudra la peine. S’il y a un endroit clair et à jour où le schéma est documenté, toute l’équipe en bénéficiera.

Cette réponse prolonge celle de Kieveli, que j’ai votée. Si votre version d’EA prend en charge la modélisation des rôles d’object (conception conceptuelle ou conception logique = ERD), effectuez une ingénierie inverse et remplissez ensuite le modèle avec la richesse expressive qu’il vous apporte.

L’option bon marché et plus légère consiste à télécharger gratuitement Visiomodeler à partir de MS et à faire de même.

L’ORM (appelez-le ORMDB) est le seul outil que j’ai trouvé qui prend en charge et encourage les conversations de conception de firebase database avec des parties prenantes non-IS sur les objects et les relations BL.

Réalité: sur le chemin de la génération de votre DDL, il passe par une phase ERD à l’arrêt complet au cours de laquelle vous pouvez répondre à vos questions, à savoir si tout est vicieux. Ce n’est pas le cas. Cela vous montrera probablement des faiblesses dans la DRE que vous avez conçue 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.

Étant donné que vous avez le luxe de travailler avec d’autres développeurs qui sont dans le même bateau, je vous suggère de leur demander ce qui, selon eux, transmettrait les informations nécessaires, le plus facilement possible. Mon entreprise a plus de 100 tables et mon patron m’a donné un DER pour des tables spécifiques qui se connectent toutes. Ainsi, vous pourriez essayer de briser 1 ERD massive en une série de DRE plus petites et plus faciles à gérer.

Si la description de vos bases de données à vos utilisateurs finaux est votre objective 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 à des tableaux et des colonnes et d’autoriser des recherches en texte intégral dans ces descriptions. Il vous permet également de regrouper logiquement des tables à l’aide d’étiquettes et de parcourir des tables à l’aide de ces étiquettes. Les tableaux ainsi que les colonnes peuvent être balisés pour trouver des éléments de données similaires dans votre firebase database / 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 de l’API est dissortingbuée sous ASL 2.0. Il est codé pour lire les commentaires / remarques de nombreux SGBDR. Vous pouvez toujours remplacer manuellement les informations imscopes. 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 “object de données” et “atsortingbut” 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 firebase database, tels que les déclencheurs, les index et les statistiques, est importante, ce logiciel n’est pas la meilleure option. Il est toutefois possible de combiner une solution technique avec ce logiciel en utilisant des champs personnalisés de lien hypertexte.
  • Le logiciel ne produit pas de DRE

Divulgation: Je travaille dans l’entreprise qui développe ce produit.

Eh bien, une image en dit long, alors je vous recommande de créer des diagrammes ER où vous pouvez voir la relation entre les tables d’un coup d’œil, ce qui est difficile à faire avec une description textuelle.

Vous n’êtes pas obligé de faire toute la firebase database dans un diagramme, divisez-le en sections. Nous utilisons Visual Paradigm au travail, mais EA est une bonne alternative, tout comme ERWIN, et sans aucun doute, il y en a beaucoup d’autres qui sont aussi bons.

Si vous avez la patience, utiliser HTML pour documenter les tableaux et les colonnes facilite l’access à votre documentation.