データベースをどのように文書化しますか。


202

私のクライアントの大部分は彼らのデータベースをまったく文書化していないことに気付きました。いくつかのより良い習慣を紹介するために、私は人々がどんなツール/プロセスを使用しているかを知りたいです。

  • データベースをどのように文書化しますか。(SQLサーバー)
  • どのようなツールを使っていますか?
  • データベーススキーマ/メタデータのドキュメント格納形式
    • Word文書
    • エクセルスプレッドシート
    • テキストで表示
  • 文書化プロセスまたはポリシー

私はリバースエンジニアリング/既存のデータベースの文書化について話しているのではなく、あなたがあなたのシステム/データベースを開発している間の文書のベストプラクティスについて主に話しています。

+3

@TML:データベースのドキュメントはどのように*見えるべきです*、Lex de HaanとToon Koppelaarsによる[データベース専門家のための応用数学](http://apress.com/book/view/1590597451)で読むことができます(ところで、a誤解を招くようなタイトルのとても素敵な本ですが、(m)どんな人でもこのようにしているのではないかと思います。 18 1月. 112011-01-18 15:32:06

64

非常に柔軟なので、私は拡張プロパティを使用しています。ほとんどの標準的なドキュメンテーションツールは追い払うことができますMS_Descriptionそして、あなたはカスタムメイドのツールであなた自身のものを使うことができます。

このプレゼンテーションを見てください。#41-Get a Lever and Pick Any Turtle: Lifting with Metadata

そしてこのコード:http://code.google.com/p/caderoux/wiki/LeversAndTurtles

+2

何かを変更し、それに応じて拡張プロパティを変更するのを忘れて、誤ったものにすることがあります。このような矛盾を自動的に検出できますか? 25 3月. 132013-03-25 00:43:35

+1

少なくとも、データベーススキーマ(sys.tables/sys.columns)を照会し、その拡張プロパティ(sys.extended_properties)に結合したまま文書化されていないフィールドを識別し、そのスクリプトをデプロイ時に実行するテストに変えることができます。 18 2月. 162016-02-18 21:11:31


17

それが書かれているならば、ドキュメンテーションは単語文書から成ります。いくつかの関係図が含まれます。テーブルのリストと、各テーブルの内容と他のテーブルとの関係についての簡単な説明。ドキュメントの1章にセキュリティ設定が含まれています。アプリケーションに必要な「ユーザー」にはどのような権限が必要ですか。

一般的に、私が働いていた会社では、データベースドキュメンテーションは顧客が監査を実行する人であるときにしか書かれません。

免責事項: コードがドキュメントであるという態度を採用している開発者はあまりにも多く、私もそれについて罪を犯しています。

+9

コードに密接には関係しないドキュメンテーション(例えば、自動生成されたスキーマダイアグラム+名前の付けられたデータベースオブジェクトとは対照的に、別のWordドキュメント)で私が見つけた大きな問題は、このドキュメンテーションは時を経て。その理由は簡単です。別の文書が事実上情報を複製するからです。ソースと同期するための*自動*の方法がないと、非常に早く時代遅れになるでしょう。これをデータベースからライブのスキーマ図を生成し、コード内から適切なコメントを引き出すツールと比較してください。 19 8月. 112011-08-19 20:24:40


50

MicrosoftのVisio Pro (Visio 2010まで)は、CAのERwin同様にデータベースをリバースエンジニアリングできます。Visioは安価なオプションですが、ERwinはより詳細で完全なオプションです。人々がそれらを見たくない場合は、拡張プロパティはいいです。Red GateのSQL Docようなものを使用して、ドキュメントをHTML形式で出力することもできます。

命名規則と外部キーを適切に設定することで、ほとんど自己文書化データベース目的をよりよく理解するためには、まだいくつかの外部文書が必要です。

  0

単純なスキーマに欠けていることがよくあるのは(たとえ名前がよく外部キー付きのデータベースでも)、フィールドの説明です。私の経験では、すべてのフィールドを列名に収まるほど単純にすることは珍しいことです。 17 5月. 162016-05-17 19:54:18


21

SchemaSpyをお試しください: http://schemaspy.sourceforge.net/


18

SchemaCrawler見てSchemaCrawler - それは私があなたが探しているものをするように設計した私の無料の、コマンドラインツールです。SchemaCrawlerは、すべてのデータベーススキーマオブジェクトを含むテキストファイルを作成します。このテキスト出力は、人間が判読できるように設計されているだけでなく、他のサーバーからの同様の出力と比較することもできます。

実際には、ビルドの一部としてデータベーススキーマのテキストファイルを出力すると便利です。このようにして、テキストファイルをあなたのソースコード管理システムにチェックインし、あなたのスキーマがどのように進化したかのバージョン履歴を持つことができます。SchemaCrawlerは、これもコマンドラインから自動化するように設計されています。


10

おかしい、私は他の人々が同様にこれをやっているかと思っていました..

私の最初の大きなデータベースプロジェクトを開発している間、Microsoft SQL Server Management Studio 10.0.1600.22はあなたが望む限りの詳細なドキュメントを追加できるワードドキュメントまたは他のドキュメントソフトウェアにエクスポートできるデータベースダイアグラムをサポートすることがわかりました。SQL Management Studioで接続したデータベースを展開し、オブジェクトエクスプローラで[データベースダイアグラム]を右クリックして[新しいデータベースダイアグラム]を選択すると、さまざまなテーブル間のすべての関係を示す対話型ダイアグラムが生成されます。どのテーブルをダイアグラムに含めるかを指定することもできます。そのため、分割して文書化しようとしただけでイメージが乱れないようになります。画像を他の編集ソフトウェアにエクスポートして、必要なだけコメントします。

私はあなたのデータベースを生成するスクリプトにたくさんの/comments /を推薦します。

一般的にそれは何のためにあるのかを書き留めている多くの仕事ですが、あなたや他の貧しい魂が数年後にあなたの創造を更新するために戻ってくる時のような長期のための良い考え!:)

+1

[ER-diagram](https://en.wikipedia.org/wiki/Entity%E2%80)で行われているように、外部キー制約はテーブルのどこかに接続されているだけなので、SQL Serverの図は使用しません。 %93relationship_model)。主キーフィールドと外部キーフィールドを接続するコネクタがあることを好みます。 15 7月. 162016-07-15 11:43:39


19

SQL Serverでは、拡張プロパティを使用しています。

次のPowerShellスクリプトを使用して、dboスキーマ内の単一のテーブルまたはすべてのテーブルに対してCreate Tableスクリプトを生成できます。

このスクリプトには、 Create tableコマンド、主キー、およびインデックスが含まれています。外部キーはコメントとして追加されます。テーブルとテーブル列の拡張プロパティはコメントとして追加されます。はい複数行プロパティはサポートされています。

スクリプトは私の個人的なコーディングスタイルに合わせています。

  • 単一列に対して個別の照合順序はありません。

  • 現在はSql ServerAuthenticationが必要です。

拡張プロパティを古き良きASCIIドキュメントに変換するための完全なコードは次のとおりです(ところで、テーブルを再作成するのは有効なSQLです)。

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"
    }
   }
} 
}

特定のデータベースの完全なdboスキーマをスクリプト化することができます。

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

または単一のテーブルをフィルタリングする

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

9

私は拡張プロパティとRed Gates SQL Docを使います。とてもうまくいきます。


7

DB Dictionary Creator

まともなGUIとエクスポート/インポートオプションを備えたオープンソースのデータベースドキュメント作成ツールです。ドキュメントを格納するためにExtendedプロパティを使用します。また、主キー列と外部キー列の自動説明も生成されます。

+1

.NET Framework 4.0が必要で、SQL ServerとSQL Expressでのみ動作します。 07 10月. 122012-10-07 15:55:26


9

データベースに「収まる」もの以外に、データベースに関する重要な情報を文書化できるため、データモデリングツールを使用します。プライバシー/セキュリティ/機密性の問題、スチュワードシップ、ガバナンスなどのメタデータ

それはデータベースを文書化するのに必要なものを超えるかもしれませんが、それらのことはビジネスにとって重要であり、彼らが彼らのデータを管理するのを助けます。

正式なツールは、複数のデータベース/インスタンス/サーバーに格納されているデータの管理にも役立ちます。これは私たちのパッケージ化されたアプリケーションの世界よりも真実ではありませんでした。


5

確かに、Extended Properties(MS_Description)がその方法です。これらの記述をメタデータの一部として容易に利用できるようにすることは、docsジェネレータだけでなく(おそらく1日)「インテリセンス」を提供するツールによっても利用されるhttp://www.softtreetech.com/isql.htmhttp://www.softtreetech.com/isql.htm ) )またはSQL Server Management StudioのIntellisenseに組み込まれています(sql2008以降)。

TangurenaとNick Chammasが正しく指摘しているように、開発者とDBAがこれらのメモを追加するのは簡単であるべきだと私は信じています。彼らの全職業生活の間に物事を最適化するため。ですから、ソースコードに近い場所でドキュメントを更新するのが本当に簡単でない限り、これはうまくいきません。ある時点で私はウェブを検索しましたが、これに対する解決策を見つけることができなかったので、私はそれを簡単にするためにLiveDoco(無料ではなく、ごめんなさい)を書きました。興味があるならば、ここでより多くの情報: http://www.livedoco.com/why-livedoco


10

私はすべてのオブジェクトのMS_description拡張プロパティを設定してから使用してデータベース全体文書ApexSQL Doc以前のHTML文書を作成するために使用される.Iを、しかし、最近私は、PDFを好みます


5

wsSqlSrvDocwsSqlSrvDoc 。これは、SQL Serverの拡張プロパティと連携してMS Word文書を作成するための優れた小さなツールです。

すべての列プロパティの印刷(外部キーリレーションを含む)は、そのまま使用できます。各フィールドの詳細については、SQL Server Management Studioでそれらの列の拡張プロパティを設定する必要があります。

無料ではありませんが、かなり手頃な価格です。「進行中ではない」データベースの文書を作成する必要があるだけであれば、無料試用版を使用するのに十分な程度の完成度で完成することになります。

Tool Website


8

SQL Serverを文書化するために、最近リリースされたばかりのものを強くお勧めします。

SQL Server & Windows Documentation Using Windows PowerShellKendal Van Dykeによって書かれた

リンクからの簡単な説明:

SQL Power Docは、SQL Serverインスタンスとその基盤となるWindows OSとマシン構成を検出、文書化、および診断するWindows PowerShellスクリプトとモジュールのコレクションです。 SQL Power Docは、SQL Server 2000から2012までのすべてのバージョンのSQL Server、およびWindows 2000からWindows XPまで、Windows Server 2012からWindows 8までのすべてのバージョンのWindows ServerおよびコンシューマWindowsオペレーティングシステムで動作します。 Windows Azure SQLデータベース。


2

データディクショナリの作成、ストアドプロシージャおよび関数のドキュメント化には、 Dataedoを使用します。Visioで作成したERDを貼り付けます。すべてのドキュメントはDataedoメタデータリポジトリ(フォーマットされたテキスト)に格納されており、内部使用のためにHTMLにエクスポートするか、印刷ドキュメントのためにPDFにエクスポートします。

各オブジェクトをモジュールに割り当て、各モジュールを人に割り当てます。Dataedoにはドキュメントステータスレポートが付属しているため、ドキュメント化する必要がある新しい列またはテーブルがあるかどうかを確認できます。