私のクライアントのほとんどは、データベースをまったく文書化しておらず、とても恐ろしいことだと感じています。より良い習慣を導入するために、どのようなツールやプロセスを使っているのか知りたいのです。
既存のデータベースをリバースエンジニアリング/ドキュメント化するのではなく、主にシステム/データベースを開発する際のドキュメントのベストプラクティスについて話しているのです。
拡張プロパティは非常に柔軟性が高いので、私はこれまで使ってきました。 ほとんどの標準的なドキュメント作成ツールは MS_Description
から駆動することができますし、カスタムビルドツールで独自のものを使用することもできます。
このプレゼンテーションをご覧ください。41-レバーを握ってどんな亀でも拾え: メタデータで持ち上げる。
そして、このコード: http://code.google.com/p/caderoux/wiki/LeversAndTurtles
マイクロソフトの「Visio Pro」(Visio 2010まで)とCAの「ERwin」(2)は、データベースのリバースエンジニアリングが可能です。Visioは安価なオプションですが、ERwinはより詳細で、より完全なオプションです。拡張プロパティは、人々がそれを見ようとするのであれば、良いものです。また、Red GateのSQL Docのようなものを使って、HTML形式のドキュメントを出力することも可能です。
命名規則や外部キーを適切に設定することで、ほぼ**セルフ・ドキュメンテーションのデータベースになると思います。それでも、目的をよりよく理解するために、外部のドキュメントを用意したほうがいいでしょう。
SQL Serverの場合、拡張プロパティを使用しています。
次のPowerShellスクリプトを使用すると、単一のテーブルまたはdboスキーマ内のすべてのテーブルのテーブル作成スクリプトを生成できます。
スクリプトには、「テーブルの作成」コマンド、主キー、インデックスが含まれています。 外部キーがコメントとして追加されます。 テーブルとテーブルの列の拡張プロパティがコメントとして追加されます。 はい、複数行のプロパティがサポートされています。
スクリプトは私の個人的なコーディングスタイルに合わせて調整されています。
-単一の列の個別の照合はありません。
-現在、Sql Serverが必要です。 認証。
以下は、拡張プロパティを古き良き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は、コマンドラインからこれも自動化するように設計されています。
もし書かれることがあっても、ドキュメントはワード文書で構成されています。関係図が数枚含まれる。テーブルのリストと、各テーブルが何を保持しているか、他のテーブルとどのように関連しているかの簡単な説明。ドキュメントの1つの章には、セキュリティ設定が含まれます:アプリケーションが必要とする"user"はどんなパーミッションなのか?
一般的に、私が勤めた会社では、データベースのドキュメントは、顧客が監査を行う側である場合にのみ作成され、その用途は金融や政府の顧客に限定される傾向があるようです。
免責事項:あまりにも多くの開発者が、コードはドキュメントであるという態度をとっており、私もその罪を犯してきました。
おかしい、他の人もこれをどうやっているのだろうと思っていました。.
最初の大きなデータベースプロジェクトの開発中に、Microsoft SQL Server Management Studio 10.0.1600.22がデータベース図をサポートしていることがわかりました。データベース図は、ワードドキュメントまたは他のドキュメントソフトウェアにエクスポートでき、必要なだけドキュメントの詳細を追加できます。 SQL Management Studioで接続したデータベースを拡張し、オブジェクトエクスプローラーの「データベース図」を右クリックして、「新しいデータベース図」を選択して、異なるテーブル間のすべての関係を示すインタラクティブ図を生成します。 図に含めるテーブルを指定することもできます。これにより、画像を少しずつ文書化しようとしても画像がおかしくならないようにします。 画像を他の編集ソフトウェアにエクスポートし、好きなだけコメントします。
また、データベースを生成するスクリプトには、たくさんの/ コメント /をお勧めします。
一般的にそれはそれが何であるかを書き留める多くの仕事ですが、あなたや他の貧しい魂が数年後にあなたの創造物を更新するために戻ってきたときなど、長期的には良い考えです。! :)。
すべてのオブジェクトにMS_description拡張プロパティを設定し、ApexSQL Docを使用してデータベース全体を文書化します。 以前はHTMLドキュメントを作成していましたが、最近はPDFを好みます。
データベースに「適合」するもの以外のデータベースに関する重要な情報を文書化できるため、データモデリングツールを使用しています。 プライバシー/セキュリティ/感度の懸念、スチュワードシップ、ガバナンスなどのメタデータ.
これは、データベースを文書化するために必要なものを超える可能性がありますが、それらはビジネスにとって重要であり、データの管理に役立ちます。
正式なツールは、複数のデータベース/インスタンス/サーバーに保存されているデータの管理にも役立ちます。 これは、パッケージ化されたアプリケーションの世界ほど真実ではありませんでした。
DB Dictionary Creator。 ---------------------。
まともなGUIとエクスポート/インポートオプションを備えたオープンソースデータベースドキュメントツールです。 拡張プロパティを使用してドキュメントを保存します。 また、主キー列と外部キー列の自動説明も生成されます。
sqlサーバーを文書化するには、最近リリースされたばかりを強くお勧めします。
SQL Server& Windows PowerShellを使用したWindowsドキュメント Kendal Van Dykeによって作成されました。
リンクからの簡単な説明:
確かに、拡張プロパティ(MS_Description)は進むべき道です。 これらの説明をメタデータの一部としてすぐに利用できるようにすることは、ドキュメントジェネレーターだけでなく、 (うまくいけばある日。) "を提供するツールによる。;intellisense"。; たとえば、優れたSofttree'。;s SQLアシスタントhttp://www.softtreetech.com/isql.htm。 (前回チェックしたところ、彼らはそうした'。;t。) またはSQL Sever Management Studio'で構築されています。;s Intellisense。 (sql2008以降。)
また、開発者やDBA'にとっても簡単なはずです。;TangurenaとNick Chammasが正しく指摘したように、これらのメモを追加する-開発者はドキュメントを更新し続けることに非常に消極的であり、重複した作業を嫌います-これは、職業生活全体で物事を最適化するように教えられた人にとって特に公平です。 したがって、ソースコードに近い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
ファイルで通常の --
-prefixedコメントを使用できます。
利点には、ドキュメントがデータベーススキーマのコードにあり、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)
);
特にMySQLでは、常にMySQL Workbenchを使用しています。 データベース設計をデザイナーで作成し、実行可能なSQLスクリプトとしてエクスポートします。 設計のすべての変更を適用してから生成されたスクリプトを実行すると、設計と実際のデータベースが完全に同期し、ドキュメントが簡単に古くなることはありません。