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 assez effrayant. Pour introduire une meilleure pratique, je voudrais 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 la documentation pour le schéma de base de données/métadonnées?
- Documents Word
- Feuille de calcul Excel
- Texte brut
- Processus de documentation ou politiques?
Je ne parle pas de rétro-ingénierie/documenter une base de données existante, mais principalement des meilleures pratiques de documentation pendant que vous développez 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 désactivés MS_Description, puis vous pouvez utiliser le vôtre 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
Visio Pro (jusqu'à Visio 2010) de Microsoft peut inverser l'ingénierie d'une base de données comme le peut ERwin de l'autorité de certification. 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 agréables, si les gens prennent la peine de les regarder. Vous pouvez également utiliser quelque chose comme Red Gate SQL Doc pour produire de la documentation au format HTML.
Je trouve que les conventions de dénomination et la configuration correcte des clés étrangères conduisent à une base de données auto-documentée presque . Vous devriez toujours avoir des documents externes pour une meilleure compréhension de l'objectif.
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 un Create table commande, clés primaires et 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 réglé sur mon style de codage personnel.
aucun classement individuel pour les colonnes uniques.
actuellement, il requiert l'authentification du serveur SQL.
Voici le code complet pour transformer les propriétés étendues en un bon vieux ASCII document (BTW c'est du SQL 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 scripter le schéma dbo complet d'une base de données donnée
Get-ScriptForTable 'localhost' 'MyDB' 'sa' 'toipsecret' | Out-File "C:\temp\Create_commented_tables.sql"
Ou filtre pour une seule table
Get-ScriptForTable 'localhost' 'MyDB' 'sa' 'toipsecret' 'OnlyThisTable'
Jetez un oeil à SchemaCrawler - c'est mon outil gratuit en ligne de commande que j'ai conçu pour faire ce que vous cherchez. SchemaCrawler produit 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, ce que j'ai trouvé, c'est 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 avoir un historique des versions de l'évolution de votre schéma au fil du temps. SchemaCrawler est conçu pour automatiser cela également, à partir de la ligne de commande.
Si elle est écrite, la documentation est constituée d'un document Word. Quelques diagrammes de relations seront inclus. Listes des tableaux et une brève description de ce que chaque tableau contient et comment il se rapporte aux autres tableaux. Un chapitre de la documentation comprend les paramètres de sécurité: de quelles autorisations "l'utilisateur" a-t-il besoin pour l'application?
Généralement, dans les entreprises pour lesquelles j'ai travaillé, la documentation de la base de données n'est écrite que lorsque le client est celui qui effectue les audits, ce qui tend à limiter son utilisation aux clients financiers et gouvernementaux.
Avertissement: beaucoup trop de développeurs adoptent l'attitude que le code est la documentation, et j'en suis aussi coupable.
J'utilise des propriétés étendues et Red Gates SQL Doc. Fonctionne très bien!
C'est drôle, 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 prend en charge les diagrammes de base de données que vous pouvez exporter vers un document Word ou un autre logiciel de documentation où vous pouvez ajouter autant de détails de documentation que vous le souhaitez. Développez simplement la base de données à laquelle vous vous êtes connecté sur SQL Management Studio et faites un clic droit 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 qui montrera toutes les relations entre les différentes tables. Vous pouvez même spécifier les tableaux que vous souhaitez inclure dans les diagrammes, afin que l'image ne soit pas désordonnée si vous essayez simplement de la documenter pièce par pièce. Exportez l'image vers n'importe quel autre logiciel d'édition et commentez autant que vous le souhaitez.
Je recommande également beaucoup de/commentaires/dans le script qui génère votre base de données.
Généralement, c'est beaucoup de travail d'écrire à quoi cela sert, mais une bonne idée à 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é la base de données entière à l'aide de ApexSQL Doc . J'avais l'habitude de créer des documents HTML plus tôt, mais dernièrement, je préfère le 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 ce qui "tient" dans une base de données. Métadonnées telles que les problèmes de confidentialité/sécurité/sensibilité, l'intendance, la gouvernance, etc.
Cela peut aller au-delà de ce dont certains ont besoin pour documenter une base de données, mais ces choses sont importantes pour l'entreprise et les aident à gérer leurs données.
Les outils formels m'aident également dans la gestion des 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 la documentation du serveur SQL, je recommande fortement la publication récente:
Documentation SQL Server et Windows utilisant Windows PowerShell écrit par Kendal Van Dyke
Brève description du lien:
SQL Power Doc est une collection de scripts et de modules Windows PowerShell qui découvrent, documentent et diagnostiquent 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 des systèmes d'exploitation Windows grand public de Windows 2000 et Windows XP via Windows Server 2012 et Windows 8 . SQL Power Doc est également capable de documenter les bases de données SQL Azure Windows.
Créateur de dictionnaire DB
est un outil de documentation de base de données open source avec une interface graphique décente et des options d'exportation/importation. Il utilise des propriétés étendues pour stocker la documentation. Il génère également 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. Le fait que ces descriptions soient facilement disponibles en tant que partie des 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 qui fournissent "intellisense", par exemple l'excellent Assistant SQL de Softtree http: // www. softtreetech.com/isql.htm (la dernière fois que je l'ai vérifié) ou intégré dans Intellisense de SQL Sever Management Studio (depuis sql2008)
Je crois également qu'il devrait être facile pour les développeurs et les administrateurs de bases de données d'ajouter ces notes parce que, comme Tangurena et Nick Chammas l'ont correctement souligné - les développeurs sont très réticents à garder les documents à jour et détestent le travail en double - ce qui est assez juste, surtout pour une personne à qui on a enseigné optimiser les choses tout au long de leur vie professionnelle. Donc, à moins qu'il ne soit vraiment facile de mettre à jour les 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 à cela, alors j'ai écrit LiveDoco (non gratuit, désolé) pour essayer de le rendre facile. Plus d'informations 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 colonne (avec des relations de clé étrangère) fonctionne immédiatement. Pour obtenir 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 en cours" qui est plus ou moins terminée, il suffirait d'utiliser l'essai gratuit.
Nous utilisons Dataedo pour créer un dictionnaire de données, documenter des procédures et des fonctions stockées. Nous collons les ERD créés 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 l'exportons vers PDF pour le document imprimé).
Nous assignons chaque objet à un module et assignons chaque module à une personne. Dataedo est livré avec un rapport d'état de la documentation afin que nous puissions savoir s'il y a une nouvelle colonne ou un nouveau tableau qui doit être documenté.
Vous pouvez utiliser le --- commentaires préfixés dans le .sql fichier.
Les avantages incluent que la documentation est avec le code du schéma de base de données et que vous pouvez facilement la valider 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
);
Vous pourriez peut-être 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 ressemblant à 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 (diagrammes de base de données) ont toujours été les plus utiles pour mon équipe
Mais il existe une règle pour écrire " Decription " dans Propriétés de chaque table et la colonne que nous créons.
Ensuite, nous utilisons un nom de logiciel est Enterprise Architect pour documenter Tables avec tous Indexes, Foreign Keys Et Columns avec Type et Description .
