データベースをどのように文書化しますか？
私のクライアントのほとんどがデータベースをまったく文書化していないことがわかりました。いくつかのより良い実践を紹介するために、私は人々が使用しているツール/プロセスを知りたいです。
- データベースをどのように文書化しますか？ （SQLサーバー）
- どのツールを使用していますか？
- データベーススキーマ/メタデータのドキュメントストレージフォーマット？
- Word文書
- エクセルスプレッドシート
- 平文
- 文書化プロセスまたはポリシー？
私は既存のデータベースをリバースエンジニアリング/ドキュメント化することについて話しているのではなく、主にシステム/データベースを開発する際のドキュメントのベストプラクティスについて話します。
拡張プロパティは非常に柔軟であるため、私は拡張プロパティを使用しています。ほとんどの標準的なドキュメンテーションツールは無効にすることができますMS_Description、そして独自に作成したツールで独自のツールを使用できます。
このプレゼンテーションを参照してください： ＃41-Get a Lever and Pick Any Turtle：Lifting with Metadata
そしてこのコード： http://code.google.com/p/caderoux/wiki/LeversAndTurtles
SchemaSpyを試してください： http://schemaspy.sourceforge.net/
SQL Serverでは、拡張プロパティを使用しています。
次のPowerShellスクリプトを使用すると、dboスキーマ内の単一のテーブルまたはすべてのテーブルのCreate Tableスクリプトを生成できます。
スクリプトにはCreate tableコマンド、主キーおよびインデックス。外部キーはコメントとして追加されます。テーブルとテーブル列の拡張プロパティがコメントとして追加されます。はい、複数行のプロパティがサポートされています。
スクリプトは私の個人的なコーディングスタイルに合わせて調整されています。
単一の列の個別の照合順序はありません。
現在、SQLサーバー認証が必要です。
以下は、拡張プロパティを適切な古い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'
SchemaCrawler をご覧ください。これは、私が設計した無料のコマンドラインツールであり、あなたが探しているものを実行するために設計されています。 SchemaCrawlerは、すべてのデータベーススキーマオブジェクトを含むテキストファイルを生成します。このテキスト出力は、人間が読めるだけでなく、別のサーバーからの同様の出力と比較できるように設計されています。
実際、私が発見したのは、データベーススキーマのテキストファイルを出力することは、ビルドの一部として実行すると便利であることです。このようにして、テキストファイルをソースコード管理システムにチェックインし、スキーマが時間とともにどのように進化したかについてのバージョン履歴を取得できます。 SchemaCrawlerは、これもコマンドラインから自動化するように設計されています。
これまでに書かれた場合、ドキュメントはWord文書で構成されます。いくつかの関係図が含まれます。テーブルのリストと、各テーブルの内容と他のテーブルとの関係の簡単な説明。ドキュメントの1つの章にはセキュリティ設定が含まれています。アプリケーションに必要な「ユーザー」にはどのようなアクセス許可がありますか？
一般に、私が働いた会社では、データベースのドキュメントは、顧客が監査を実行する人である場合にのみ作成され、その使用は金融および政府の顧客に限定される傾向があります。
免責事項：コードはドキュメントですという態度をとる開発者が多すぎます。私もそれを犯しています。
拡張プロパティとRed Gates SQL Docを使用しています。とてもうまくいきます！
おかしい、私は他の人たちもこれをやっているのだろうかと思っていました。
私の最初の大きなデータベースプロジェクトの開発中に、Microsoft SQL Server Management Studio 10.0.1600.22がサポートするデータベースダイアグラムがWord文書または他のドキュメントソフトウェアにエクスポートできるので、必要なだけドキュメントの詳細を追加できることがわかりました。 SQL Management Studioで接続したデータベースを展開し、オブジェクトエクスプローラーで[データベースダイアグラム]を右クリックして[新しいデータベースダイアグラム]を選択するだけで、さまざまなテーブル間のすべての関係を示すインタラクティブなダイアグラムが生成されます。ダイアグラムに含めるテーブルを指定することもできます。これにより、イメージを1つずつドキュメント化しようとした場合に、イメージが不自然にならないようにすることができます。画像を他の編集ソフトウェアにエクスポートし、好きなだけコメントを付けます。
また、データベースを生成するスクリプトには、たくさんの/ comments /をお勧めします。
一般的にそれはすべての目的を書き留めるのに多くの仕事ですが、あなたや他の貧しい魂が数年後にあなたの作品を更新するために戻ってきたときなど、長期的には良い考えです！ :)
すべてのオブジェクトにMS_description拡張プロパティを設定し、 ApexSQL Doc を使用してデータベース全体をドキュメント化します。以前はHTMLドキュメントを作成していましたが、最近はPDFを好みます
データモデリングツールを使用しているのは、データベースに「適合」するもの以外のデータベースに関する重要な情報を文書化できるためです。プライバシー/セキュリティ/機密性の懸念、スチュワードシップ、ガバナンスなどのメタデータ.
これは、データベースの文書化に必要なものを超える可能性がありますが、それらはビジネスにとって重要であり、データの管理に役立ちます。
正式なツールは、複数のデータベース/インスタンス/サーバーに保存されているデータの管理にも役立ちます。これは、パッケージ化されたアプリケーションの世界ほど真実ではありません。
SQLサーバーのドキュメント化については、最近リリースされたばかりを強くお勧めします。
Windows PowerShellを使用したSQL ServerとWindowsのドキュメントKendal Van Dyke作成
リンクからの簡単な説明：
SQL Power Docは、SQL Serverインスタンスとその基盤となるWindows OSおよびマシン構成を検出、文書化、および診断するWindows PowerShellスクリプトおよびモジュールのコレクションです。 SQL Power Docは、SQL Server 2000から2012までのすべてのバージョンのSQL Server、およびWindows Serverのすべてのバージョンと、Windows 2000およびWindowsからのコンシューマWindowsオペレーティングシステムで動作しますXP Windows Server 2012およびWindows 8までSQL Power Docは、Windows Azure SQLデータベースを文書化することもできます。
DB辞書作成者
まともなGUIとエクスポート/インポートオプションを備えたオープンソースのデータベースドキュメントツールです。拡張プロパティを使用してドキュメントを保存します。また、主キー列と外部キー列の自動説明も生成します。
確かに、拡張プロパティ（MS_Description）はそのための方法です。これらの説明をメタデータの一部としてすぐに利用できるようにすると、ドキュメントジェネレーターだけでなく、（おそらく1日）優れたSofttreeのSQLアシスタントなどの「インテリセンス」を提供するツールでも利用できます http：// www。 softtreetech.com/isql.htm （前回確認しなかった場合）またはSQL Sever Management StudioのIntellisenseに組み込まれています（sql2008以降）
TangurenaとNick Chammasが正しく指摘したように、開発者やDBAがこれらのメモを追加するのは簡単だと私は信じています。人生全体で物事を最適化するために。したがって、ソースコードに近い1か所でドキュメントを更新するのが本当に簡単でない限り、これは機能しません。ある時点でWebを検索しても解決策が見つからなかったため、簡単にするためにLiveDoco（無料ではありません）を作成しました。興味のある方はこちらの詳細情報： http://www.livedoco.com/why-livedoco
wsSqlSrvDoc もご覧ください。これは、SQL Serverの拡張プロパティで機能し、MS Word文書を作成する素晴らしいツールです。
すべての列プロパティ（外部キー関係を含む）の印刷は、そのまま使用できます。各フィールドの詳細については、SQL Server Management Studioでそれらの列の拡張プロパティを設定する必要があります。
無料ではありませんが、かなり手頃な価格です。 「進行中の作業ではない」DBのドキュメントを作成する必要があるだけの場合は、無料試用版を使用するのに十分だとは言えません。
Dataedo を使用して、データディクショナリを作成し、ストアドプロシージャと関数をドキュメント化します。 Visioで作成したERDを貼り付けます。すべてのドキュメントはDataedoメタデータリポジトリ（フォーマットされたテキスト）に保存され、内部で使用するためにHTMLにエクスポートするか、印刷ドキュメントの場合はPDF）にエクスポートします。
各オブジェクトをモジュールに割り当て、各モジュールを人に割り当てます。 Dataedoにはドキュメントステータスレポートが付属しているため、ドキュメント化する必要がある新しい列またはテーブルがあるかどうかを確認できます。
通常の--で始まる接頭辞.sqlファイル。
ドキュメントにはデータベーススキーマのコードが含まれており、 Git などのバージョン管理システムに簡単にコミットできるという利点があります。
例：
-- 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
);
多分あなたも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)
);
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)
);
または、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)
);
ERD図（データベース図）は常に私のチームにとって最も有用な図でした
ただし、各テーブルのPropertiesに「Decription」と書くルールがありますと私たちが作成する列。
次に、Enterprise Architectというソフトウェア名を使用して、TablesとすべてのIndexes、Foreign KeysおよびColumns with TypeおよびDescription。
