Comment documentez-vous vos bases de données?


202

Je trouve que la plupart de mes clients ne documentent pas du tout leurs bases de données et je trouve cela plutôt effrayant.Pour introduire de meilleures pratiques, j'aimerais savoir quels outils/processus les gens utilisent.

  • Comment documentez-vous votre base de données?(Serveur SQL)
  • Quel outil utilisez-vous?
  • Format de stockage de documentation pour schéma de base de données/métadonnées?
    • Documents Word
    • Feuille de calcul Excel
    • Texte brut
  • Processus ou politiques de documentation?

Je ne parle pas de l’ingénierie inverse/de la documentation d’une base de données existante, mais principalement des meilleures pratiques en matière de documentation pendant le développement de votre système/base de données.

+3

@TML: À quoi devrait ressembler la documentation * de la base de données, vous pouvez le lire dans [Mathématiques appliquées pour les professionnels de la base de données] (http://apress.com/book/view/1590597451) de Lex de Haan et Toon Koppelaars (au fait, une très beau livre avec un titre trompeur), mais je doute que de nombreuses personnes le fassent de cette façon. 18 janv.. 112011-01-18 15:32:06

64

J'utilise des propriétés étendues car elles sont très flexibles.La plupart des outils de documentation standard peuvent être utilisésMS_Descriptionet vous pouvez ensuite utiliser les vôtres avec des outils personnalisés.

Voir cette présentation:#41-Get a Lever and Pick Any Turtle: Lifting with Metadata

Et ce code:http://code.google.com/p/caderoux/wiki/LeversAndTurtles

+2

Vous pouvez modifier quelque chose et oublier de modifier vos propriétés étendues en conséquence, en les rendant incorrectes.Pouvez-vous détecter automatiquement de telles différences? 25 mars. 132013-03-25 00:43:35

+1

À tout le moins, vous pouvez interroger le schéma de la base de données (sys.tables/sys.columns) et le laisser rejoindre ses propriétés étendues (sys.extended_properties) pour identifier les champs non documentés, puis transformer ce script en test à exécuter lors du déploiement. 18 févr.. 162016-02-18 21:11:31


17

Si elle est écrite, la documentation consiste en un document Word.Deux diagrammes de relation seront inclus.Listes des tables et brève description de ce que chaque table contient et de sa relation avec les autres tables.Un chapitre de la documentation inclut les paramètres de sécurité: de quelles autorisations l’utilisateur at-il besoin?

Généralement, dans les entreprises pour lesquelles j'ai travaillé, la documentation de base de données n'est écrite que lorsque le client est celui qui effectue les audits, ce qui tend à en limiter l'utilisation aux clients financiers et gouvernementaux.

Clause de non-responsabilité: beaucoup trop de développeurs pensent que le code est la documentation , et je m'en suis aussi rendu coupable.

+9

Un gros problème que je trouve avec une documentation qui n'est pas étroitement liée au code (par exemple, un document Word séparé, par opposition à un diagramme de schéma généré automatiquement et à des objets de base de données bien nommés) est que cette documentation est garantie comme étant fausse le temps passe.La raison est simple: un document séparé duplique efficacement les informations.Sans un * moyen * automatisé de le synchroniser avec la source, il deviendra rapidement obsolète.Comparez cela à un outil qui génère un diagramme de schéma en temps réel à partir de la base de données et extrait les commentaires appropriés dans le code. 19 août. 112011-08-19 20:24:40


50

Microsoft Visio Pro (jusqu'à Visio 2010) peut Visio Pro à l'ingénierie inverse d'une base de données, de la même manière que le ERwin .Visio est l'option la moins chère, mais ERwin est l'option la plus détaillée et la plus complète.Les propriétés étendues sont bien, si les gens prennent la peine de les regarder.Vous pouvez également utiliser quelque chose comme SQL Doc Red Gate pour produire une documentation au format HTML.

Je trouve que les conventions de nommage et la configuration correcte des clés étrangères conduisent à unepresquebase de données auto-documentée.Vous devriez toujours avoir des documents externes pour une meilleure compréhension du but.

  0

Ce qui manque souvent à un schéma simple (même dans une base de données bien nommée et à clé étrangère), ce sont les descriptions des champs.D'après mon expérience, il est inhabituel que tous les champs soient suffisamment simples pour s'intégrer au nom de la colonne. 17 mai. 162016-05-17 19:54:18


21

Essayez SchemaSpy: http://schemaspy.sourceforge.net/


18

Jetez un coup d’œil à SchemaCrawler - c’est mon outil gratuit en ligne de commande que j’ai conçu pour faire ce que vous recherchez.SchemaCrawler génère un fichier texte avec tous les objets de schéma de base de données.Cette sortie texte est conçue pour être à la fois lisible par l'homme et différable par rapport à une sortie similaire d'un autre serveur.

En pratique, j'ai constaté que la sortie d'un fichier texte du schéma de la base de données est utile, lorsqu'elle est effectuée dans le cadre de la construction.De cette façon, vous pouvez archiver le fichier texte dans votre système de contrôle de code source et disposer d'un historique des versions de l'évolution de votre schéma.SchemaCrawler est conçu pour automatiser cela aussi, à partir de la ligne de commande.


10

Drôle, je me demandais comment les autres faisaient cela aussi ..

Lors du développement de mon premier grand projet de base de données, j’ai constaté que Microsoft SQL Server Management Studio 10.0.1600.22 prenait en charge les diagrammes de base de données que vous pouviez exporter vers un document Word ou un autre logiciel de documentation dans lequel vous pouviez ajouter autant de détails que vous le souhaitez.Développez simplement la base de données à laquelle vous vous êtes connecté sur SQL Management Studio, cliquez avec le bouton droit de la souris sur "diagrammes de base de données" dans l'explorateur d'objets et sélectionnez "Nouveau diagramme de base de données" pour générer un diagramme interactif montrant toutes les relations entre les différentes tables.Vous pouvez même spécifier les tables que vous souhaitez inclure dans les diagrammes, de sorte que l'image ne devienne pas indécente si vous essayez simplement de la documenter pièce par pièce.Exportez l'image vers un autre logiciel de montage et commentez autant que vous le souhaitez.

Je recommande également beaucoup de/comments/dans le script qui génère votre base de données.

Généralement, c'est beaucoup de travail d'écrire ce que c'est, mais c'est une bonne idée pour le long terme, comme lorsque vous ou une autre pauvre âme revenez pour mettre à jour votre création quelques années plus tard!:)

+1

Je n'utilise pas les diagrammes SQL Server, car les contraintes de clé étrangère sont simplement connectées quelque part aux tables, comme cela est fait dans [diagrammes ER] (https://en.wikipedia.org/wiki/Entity%E2%80 % 93relationship_model).Je préfère avoir les connecteurs reliant les champs de clé primaire et étrangère. 15 juil.. 162016-07-15 11:43:39


19

Pour SQL Server, j'utilise des propriétés étendues.

Avec le script PowerShell suivant, je peux générer des scripts de création de table pour une seule table ou pour toutes les tables du schéma dbo.

Le script contient une commande, des clés primaires et des index Create table .Les clés étrangères sont ajoutées en tant que commentaires. Les propriétés étendues des tables et des colonnes de table sont ajoutées en tant que commentaires.Oui, les propriétés multilignes sont prises en charge.

Le script est adapté à mon style de codage personnel.

  • pas de classement individuel pour les colonnes simples.

  • actuellement, Sql ServerAuthentication est requis.

Voici le code complet pour transformer les propriétés étendues en un bon vieux document ASCII (BTW, il est valide pour recréer vos tables):

function Get-ScriptForTable
{
   param (
    $server,$ dbname,
    $user,$ password,
    $filter
   )

[System.reflection.assembly]::LoadWithPartialName("Microsoft.SqlServer.Smo") | out-null
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SqlServer.ConnectionInfo") | out-null$ conn = new-object "Microsoft.SqlServer.Management.Common.ServerConnection" 
 $conn.ServerInstance =$ server
 $conn.LoginSecure =$ false
 $conn.Login =$ user
 $conn.Password =$ password
 $conn.ConnectAsUser =$ false
 $srv = New-Object "Microsoft.SqlServer.Management.Smo.Server"$ conn

 $Scripter = new-object ("Microsoft.SqlServer.Management.Smo.Scripter")
#$ Scripter.Options.DriAll = $false$ Scripter.Options.NoCollation = $True$ Scripter.Options.NoFileGroup = $true$ scripter.Options.DriAll = $True$ Scripter.Options.IncludeIfNotExists = $False$ Scripter.Options.ExtendedProperties = $false$ Scripter.Server = $srv$ database = $srv.databases[$ dbname]
 $obj =$ database.tables

 $cnt = 1$ obj | % {

   if (! $filter -or$ _.Name -match $filter)
  {$ lines = @()
    $header = "----------{0, 3}{1, -30}----------" -f$ cnt, $_.Name
    Write-Host$ header 

    "/* ----------------- {0, 3} {1, -30} -----------------" -f $cnt,$ _.Name
    foreach( $i in$ _.ExtendedProperties)
    {
     "{0}: {1}" -f $i.Name,$ i.value
    }
    ""
    $colinfo = @{}
    foreach($ i in $_.columns)
   {$ info = ""
     foreach ( $ep in$ i.ExtendedProperties)
     {
      if ( $ep.value -match "'n")
     {
       "----- Column:{0}{1}-----" -f$ i.name, $ep.name$ ep.value
      }
      else
      {
       $info += "{0}:{1}" -f$ ep.name, $ep.value
      }
     }
     if ($ info)
     {
      $colinfo[$ i.name] = $info
     }
    }
    ""
    "SELECT COUNT(*) FROM{0}" -f$ _.Name
    "SELECT * FROM {0} ORDER BY 1" -f $_.Name
    "---------------------{0, 3}{1, -30}----------------- */" -f$ cnt, $_.Name
    ""$ raw = $Scripter.Script($ _)
    #Write-host $raw$ cont = 0
    $skip =$ false 
    foreach ( $line in$ raw -split "\r\n")
    {
     if ( $cont -gt 0)
    {
      if ($ line -match "^\)WITH ")
      {
       $line = ")"
      }$ linebuf += ' ' + $line -replace " ASC", ""$ cont--
      if ( $cont -gt 0){ continue }
     }
     elseif ($ line -match "^ CONSTRAINT ")
     {
      $cont = 3$ linebuf = $line
      continue
     }
     elseif ($ line -match "^UNIQUE ")
     {
      $cont = 3$ linebuf = $line$ skip = $true
      continue
     }
     elseif ($ line -match "^ALTER TABLE.*WITH CHECK ")
     {
      $cont = 1$ linebuf = "-- " + $line
      continue
     }
     elseif ($ line -match "^ALTER TABLE.* CHECK ")
     {
      continue
     }
     else
     {
      $linebuf =$ line
     }
     if ( $linebuf -notmatch "^SET ")
    {
      if ($ linebuf -match "^\)WITH ")
      {
       $lines += ")"
      }
      elseif ($ skip)
      {
       $skip =$ false
      }
      elseif ( $linebuf -notmatch "^\s*$ ")
      {
       $linebuf =$ linebuf -replace "\]|\[", ""
       $comment =$ colinfo[( $linebuf.Trim() -split " ")[0]]
       if ($ comment) { $comment = ' -- ' +$ comment }
       $lines +=$ linebuf + $comment
      }
     }
    }$ lines += "go"
    $lines += ""$ block = $lines -join "'r'n"$ block
    $cnt++$ used = $false
    foreach($ i in $_.Indexes)
   {$ out = ''
     $raw =$ Scripter.Script( $i)
     #Write-host$ raw
     foreach ( $line in$ raw -split "\r\n")
     {
      if ( $line -match "^\)WITH ")
     {$ out += ")"
      }
      elseif ( $line -match "^ALTER TABLE.* PRIMARY KEY")
     {
       break
      }
      elseif ($ line -match "^ALTER TABLE.* ADD UNIQUE")
      {
       $out +=$ line -replace "\]|\[", "" -replace " NONCLUSTERED", "" 
      }
      elseif ( $line -notmatch "^\s*$ ")
      {
       $out +=$ line -replace "\]|\[", "" -replace "^\s*", "" '
       -replace " ASC,", ", " -replace " ASC $", "" '
       <#-replace "\bdbo\.\b", "" #> '
       -replace " NONCLUSTERED", "" 
      }$ used = $true
     }$ block = " $out;'r'ngo'r'n"$ out
    }
    if ($used)
    {
     "go"
    }
   }
} 
}

Vous pouvez soit écrire le schéma complet du schéma dbo d’une base de données donnée.

Get-ScriptForTable 'localhost' 'MyDB' 'sa' 'toipsecret' | Out-File "C:\temp\Create_commented_tables.sql"

Ou filtrer pour une seule table

Get-ScriptForTable 'localhost' 'MyDB' 'sa' 'toipsecret' 'OnlyThisTable'

9

J'utilise des propriétés étendues et Red Gates SQL Doc.Fonctionne très bien!


7

DB Dictionary Creator

est un outil de documentation de base de données open source avec une interface graphique et des options d'exportation/importation décentes.Il utilise les propriétés étendues pour stocker la documentation.Il va également générer des descriptions automatiques pour les colonnes de clé primaire et les colonnes de clé étrangère.

+1

nécessite .NET Framework 4.0 et ne fonctionne qu'avec SQL Server et SQL Express 07 oct.. 122012-10-07 15:55:26


9

J'utilise des outils de modélisation de données, car ils me permettent de documenter des informations importantes sur la base de données autres que celles "insérées" dans une base de données.Les métadonnées telles que les problèmes de confidentialité/sécurité/sensibilité, la gérance, la gouvernance, etc.

Cela peut aller au-delà de ce dont certains ont besoin pour documenter une base de données, mais ces éléments sont importants pour les entreprises et les aident à gérer leurs données.

Les outils formels m'aident également à gérer les données stockées dans plusieurs bases de données/instances/serveurs.Cela n'a jamais été aussi vrai que dans notre monde d'applications packagées.


5

En effet, les propriétés étendues (MS_Description) sont la voie à suivre.Disposer facilement de ces descriptions dans les métadonnées pourrait être utilisé non seulement par les générateurs de documents, mais également (heureusement un jour) par des outils fournissant "intellisense", par exemple l'excellent Assistant SQL de http://www.softtreetech.com/isql.htm (la dernière fois que j'ai vérifié)) ou intégré à Intellisense (depuis sql2008) de SQL Sever Management Studio

Je pense également que les développeurs et les administrateurs de bases de données devraient pouvoir facilement ajouter ces notes car, comme Tangurena et Nick Chammas l'ont correctement souligné, les développeurs hésitent beaucoup à tenir les docs à jour et à détester le travail en double, ce qui est juste assez pour un apprenti optimiser les choses tout au long de leur vie professionnelle.Donc, à moins que ce ne soit vraiment facile de mettre à jour des documents à un endroit proche du code source - cela ne fonctionnera pas.À un moment donné, j'ai cherché sur le Web et je n'ai pas trouvé de solution. J'ai donc écrit LiveDoco (pas gratuit, désolé) pour tenter de le rendre facile.Plus d'informations ici si vous êtes intéressé: http://www.livedoco.com/why-livedoco


10

J'ai défini la propriété étendue MS_description pour tous les objets, puis documenté la base de données entière à l'aide de ApexSQL Doc utilisé pour créer des documents HTML plus tôt, mais dernièrement, je préfère les PDF.


5

Vous pouvez également consulter wsSqlSrvDoc .C'est un joli petit outil qui fonctionne avec les propriétés étendues de SQL Server et crée un document MS Word.

L’impression de toutes les propriétés de la colonne (avec des relations de clé étrangère) s’effectue par défaut.Pour une description plus détaillée de chaque champ, vous devez configurer les propriétés étendues de ces colonnes dans SQL Server Management Studio.

Ce n'est pas gratuit mais assez abordable.Si vous avez juste besoin de créer une documentation pour une base de données "pas de travail en cours" qui est plus ou moins terminée que ce serait suffisant pour utiliser la version d'essai gratuite.

Tool Website


8

Pour Documenting sql server, je recommande vivement la publication récente:

SQL Server & Windows Documentation Using Windows PowerShellécrit par Kendal Van Dyke

Brève description du lien:

SQL Power Doc est un ensemble de scripts et de modules Windows PowerShell permettant de découvrir, de documenter et de diagnostiquer les instances SQL Server et leurs configurations sous-jacentes de système d'exploitation Windows et de machine. SQL Power Doc fonctionne avec toutes les versions de SQL Server de SQL Server 2000 à 2012, et toutes les versions de Windows Server et les systèmes d'exploitation Windows grand public de Windows 2000 et Windows XP à Windows Server 2012 et Windows 8. SQL Power Doc est également capable de documenter Bases de données SQL Windows Azure.


2

Nous utilisons Dataedo pour créer un dictionnaire de données, documenter des procédures stockées et des fonctions.Nous collons les DER créées dans Visio.Toute la documentation est stockée dans le référentiel de métadonnées Dataedo (texte formaté) et nous l'exportons au format HTML pour un usage interne ou au PDF pour un document imprimé.

Nous assignons chaque objet à un module et assignons chaque module à une personne.Dataedo est fourni avec des rapports sur l'état de la documentation afin que nous puissions savoir s'il existe une nouvelle colonne ou un nouveau tableau à documenter.