Comment documentez-vous vos bases de données?

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.

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

Voir cette présentation: # 41-Obtenez un levier et choisissez n'importe quelle tortue: lever avec des métadonnées

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

Microsoft Visio Pro de (jusqu'à Visio 2010) peut désosser une base de données peut CA 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 de Red Gate pour générer la documentation au format HTML.

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

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

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 Create tablecommande, des clés primaires et des index. 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, il nécessite l'authentification du serveur SQL.

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'

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 cherchez. SchemaCrawler génère un fichier texte avec tous les objets du 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 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.

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.

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

C'est marrant, je me demandais comment les autres faisaient ça 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! :)

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

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.

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

Documentation SQL Server & Windows Utilisation de 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, ainsi que 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.

DB Dictionnaire 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.

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 aussi (espérons-le un jour) par des outils fournissant "intellisense", par exemple l'excellent assistant SQL de Softtree http://www.softtreetech.com/ isql.htm (la dernière fois que j'ai vérifié, ils ne l'ont pas fait) ou intégré à Intellisense (depuis sql2008) de SQL Server Management Management

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 une personne à qui l'apprentissage a été enseigné. 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'infos ici si vous êtes intéressé: http://www.livedoco.com/why-livedoco

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 des descriptions supplémentaires sur 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.

Site Web de l'outil

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.

Vous pouvez utiliser des --commentaires standard pré-préfixés dans le .sqlfichier.

Parmi les avantages, citons le fait que la documentation contient le code du schéma de base de données et que vous pouvez facilement l'enregistrer dans un système de contrôle de version tel que Git .

Exemple:

-- Table to store details about people.
-- See also: The customer table.
-- Note: Keep this data safe!
-- Todo: Add a email column.
CREATE TABLE Persons ( -- People in the registry
    PersonID int,
    LastName varchar(255), -- The person's last name
    FirstName varchar(255), -- The person's first name
    Address varchar(255), -- Address of residence
    City varchar(255) -- City of residence
);

Peut-être que vous pourriez aussi utiliser XML.

-- <summary>
-- Table to store details about people.
-- </summary>
-- <column name="PersonID">The id column.</column>
-- <column name="LastName">The person's last name.</column>
-- <column name="FirstName">The person's first name.</column>
-- <column name="Address">Address of residence.</column>
-- <column name="City">City of residence.</column>
CREATE TABLE Persons (
    PersonID int,
    LastName varchar(255),
    FirstName varchar(255),
    Address varchar(255),
    City varchar(255)
);

Vous pouvez également utiliser une syntaxe avec la ressemblance de jsDoc / phpDoc .

-- Table to store details about people.
-- @column {int} PersonID - The id column.
-- @column {varchar} LastName - The person's last name.
-- @column {varchar} FirstName - The person's first name.
-- @column {varchar} Address - Address of residence.
-- @column {varchar} City - City of residence.
-- @see {@link https://example.com/|Example}
-- @author Jane Smith <[email protected]>
-- @copyright Acme 2018
-- @license BSD-2-Clause
-- @todo Add a column for email address.
-- @since 1.0.1
-- @version 1.2.3
CREATE TABLE Persons (
    PersonID int,
    LastName varchar(255),
    FirstName varchar(255),
    Address varchar(255),
    City varchar(255)
);

Ou vous pouvez utiliser la syntaxe MarkDown.

-- # Persons
-- Table to store details about **people**.
-- * `PersonID` - The id column.
-- * `LastName` - The person's _last_ name.
-- * `FirstName` - The person's _first_ name.
-- * `Address` - Address of residence.
-- * `City` - City of residence.
--
-- [I'm an inline-style link](https://www.example.com/)
--
-- | PersonID | LastName | FirstName | Address | City |
-- | ---------| -------- | --------- | ------- | ---- |
-- | 1        | Smith    | Jane      | N/A     | N/A  |
CREATE TABLE Persons (
    PersonID int,
    LastName varchar(255),
    FirstName varchar(255),
    Address varchar(255),
    City varchar(255)
);

Les diagrammes ERD (Database Diagrams) ont toujours été les plus utiles pour mon équipe

Mais il existe une règle pour écrire " Decription " dans les propriétés de chaque table et colonne que nous créons.

Ensuite , nous utilisons un nom de logiciel est Enterprise Architect pour documenter Tablesavec tous Indexes, Foreign Keyset Columnsavec Typeet description .

Pour MySQL en particulier, nous utilisons toujours MySQL Workbench . Nous créons nos conceptions de base de données dans le concepteur, puis nous l'exportons sous la forme d'un script SQL exécutable. L'application de toutes les modifications apportées à la conception, puis l'exécution du script généré garantissent que la conception et la base de données réelle sont parfaitement synchronisées les unes avec les autres et que la documentation ne deviendra pas aussi obsolète.