Veritabanlarınızı nasıl belgeliyorsunuz?


227

Müşterilerimin çoğunun veritabanlarını belgelemediğini ve bunun oldukça korkutucu olduğunu biliyorum. Bazı daha iyi uygulamaları tanıtmak için insanların hangi araçları / süreçleri kullandığını bilmek isterim.

  • Veritabanınızı nasıl belgeliyorsunuz? (SQL Server)
  • Hangi aracı kullanıyorsunuz?
  • Veritabanı şeması / meta-veri için Dokümantasyon Depolama Formatı?
    • Word belgeleri
    • Excel elektronik tablo
    • Düz Metin
  • Belgelendirme süreci veya politikaları?

Tersine mühendislik / mevcut bir veritabanını belgelemekten bahsetmiyorum, ancak sisteminizi / veritabanınızı geliştirirken temel olarak en iyi dokümantasyon belgelerinden bahsediyorum.

Yanıtlar:


78

Çok esnek olduklarından genişletilmiş özellikler kullanıyorum. Çoğu standart dokümantasyon aracı çıkartılabilir MS_Descriptionve sonra kendinize özel araçlar kullanarak kendiniz kullanabilirsiniz.

Bu sunuma bakın: # 41-Bir Kol Alın ve Herhangi Bir Kaplumbağayı Seçin: Meta Veri İle Kaldırma

Ve bu kod: http://code.google.com/p/caderoux/wiki/LeversAndTurtles


3
Bir şeyleri değiştirebilir ve genişletilmiş özelliklerinizi buna göre değiştirmeyi unutup yanlış yapabilirsiniz. Bu gibi farklılıkları otomatik olarak tespit edebiliyor musunuz?
AK

2
En azından bir kişi, veritabanı şemasını (sys.tables / sys.columns) sorgulayabilir ve belgelenmemiş alanları tanımlamak için genişletilmiş özelliklerine (sys.extended_properties) bırakılabilir ve ardından dağıtırken çalıştırılacak sınamaya dönüştürülebilir.
Micah, 21

59

Microsoft'un Visio Pro'su (Visio 2010'a kadar) CA'nın ERwin'sindeki gibi bir veritabanını tersine çevirebilir . Visio daha ucuz seçenektir, ancak ERwin daha detaylı, daha eksiksiz bir seçenektir. Uzatılmış özellikler, insanlar bunlara bakmaktan rahatsız olursa iyidir. Belgeleri HTML biçiminde almak için Red Gate'in SQL Belgesi gibi bir şey de kullanabilirsiniz .

Adlandırma kurallarını buluyorum ve yabancı anahtarların uygun şekilde ayarlanmasının neredeyse kendi kendini belgeleyen bir veritabanına götürdüğünü biliyorum . Amacın daha iyi anlaşılması için hala bazı harici dokümanlara sahip olmalısınız.


Ne kadar basit bir şemanın eksik olduğu (iyi bilinen ve yabancı anahtarlı bir veritabanında bile) alanların tanımlarıdır. Deneyimime göre, tüm alanların sütun adına sığacak kadar basit olması olağandışı.
StockB


26

SQL Server için genişletilmiş özellikler kullanıyorum.

Aşağıdaki PowerShell Komut Dosyası ile, tek tablo için veya dbo şemasındaki tüm tablolar için Tablo Oluştur komut dosyaları oluşturabilirim.

Komut dosyası bir Create tablekomut, birincil anahtarlar ve dizinler içeriyor . Yabancı anahtarlar yorum olarak eklenir. Tabloların ve tablo sütunlarının genişletilmiş özellikleri yorum olarak eklenir. Evet çok satırlı özellikler desteklenir.

Senaryo benim kişisel kodlama stilime göre ayarlandı.

  • tek sütunlar için bireysel harmanlama yok.

  • şu anda Sql Sunucu Kimlik Doğrulaması gerektirir.

Genişletilmiş özellikleri iyi bir düz eski ASCII belgesine dönüştürmek için kullanılan kodun tamamı (BTW tablolarınızı yeniden oluşturmak için geçerli sql'dir):

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

Belirli bir veritabanının complete dbo şemasını komut dosyası olarak kullanabilirsiniz.

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

Veya tek bir masa için filtre

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

21

SchemaCrawler'a bir göz atın - aradığınızı yapmak için tasarladığım ücretsiz, komut satırı aracımdır . SchemaCrawler, tüm veritabanı şema nesnelerini içeren bir metin dosyası oluşturur. Bu metin çıktısı, hem insan tarafından okunabilir hem de başka bir sunucudan gelen benzer çıktılara karşı farklılaşabilecek şekilde tasarlanmıştır.

Uygulamada, bulduğum şey, veritabanı şemasının bir metin dosyasının çıktısının, derlemenin bir parçası olarak yapılması yararlı olduğu yönünde. Bu şekilde, metin dosyasını kaynak kod kontrol sisteminize göre kontrol edebilir ve şemanızın zaman içinde nasıl geliştiğine dair bir sürüm geçmişi olabilir. SchemaCrawler, bunu komut satırından da otomatikleştirmek için tasarlanmıştır.


20

Daha önce yazılmışsa, belgeler bir kelime belgesinden oluşur. Birkaç ilişki diyagramı dahil edilecektir. Tabloların listesi ve her bir tablonun ne tuttuğunun ve diğer tablolarla nasıl ilişkili olduğuna dair kısa bir açıklama Belgelerin bir bölümü güvenlik ayarlarını içerir: uygulamanın ihtiyaç duyduğu "kullanıcı" hangi izinleri içeriyor?

Genel olarak çalıştığım firmalarda veri tabanı dokümantasyonu sadece müşteri denetimleri yapan ve finansal ve devlet müşterileri ile olan kullanımını sınırlama eğiliminde olduğu zaman yazılır.

Feragatname: Çok fazla sayıda geliştirici , kodun dokümantasyon olduğu yönünde davranıyor ve ben de suçlu bulundum.


10
Kodla yakından bağlı olmayan belgelerle (örneğin, otomatik olarak oluşturulan bir şema şeması + iyi adlandırılmış veritabanı nesnelerinin aksine ayrı bir Word belgesi gibi) belgeyle ilgili bulduğum büyük bir sorun, bu belgelerin yanlış anlaşılmasının garanti edilmesidir. zaman geçer. Sebep basit: ayrı bir belge bilgileri etkili bir şekilde çoğaltıyor. Kaynakla senkronize tutmanın otomatik bir yolu olmadan , çok hızlı bir şekilde eski hale gelecektir. Bunu veritabanından canlı bir şema diyagramı oluşturan ve kod içindeki uygun yorumları çeken bir araçla karşılaştırın.
Nick Chammas

16

Genişletilmiş özellikler ve Red Gates SQL Doc kullanıyorum. Çok iyi çalışıyor!


14

Komik, başkalarının da bunu nasıl yaptığını merak ediyordum.

İlk büyük veritabanı projemi geliştirirken, Microsoft SQL Server Management Studio 10.0.1600.22'nin bir kelime belgesine veya istediğiniz kadar belge detayı ekleyebileceğiniz başka bir belge yazılımına verebileceğiniz veritabanı diyagramlarını desteklediğini gördüm. Sadece SQL Management Studio'ya bağlandığınız veritabanını genişletin ve nesne gezgininde "veritabanı diyagramlarına" sağ tıklayın ve farklı tablolar arasındaki tüm ilişkileri gösterecek etkileşimli bir diyagram oluşturmak için "Yeni Veritabanı Şeması" nı seçin. Diyagramlara hangi tabloları dahil etmek istediğinizi bile belirleyebilirsiniz, böylece yalnızca parça parça belgelemeye çalışıyorsanız, görüntü kötüleşmeyebilir. Resmi başka bir düzenleme yazılımına dışa aktarın ve istediğiniz kadar yorum yapın.

Ayrıca , veritabanınızı oluşturan komut dosyasında bol miktarda / yorum / tavsiye ederim .

Genelde her şeyin ne olduğunu yazdığınız bir çok çalışma, ancak uzun vadede, örneğin siz veya başka bir fakir ruhun, yaratıcılığınızı birkaç yıl sonra güncellemek için geri geldiği zamanlar için iyi bir fikir! :)


3
Yabancı anahtar kısıtlamaları ER-diyagramlarında olduğu gibi tablolara bir yere bağlı olduğundan, SQL Server diyagramlarını kullanmıyorum . Birincil ve yabancı anahtar alanları birbirine bağlayan konektörlerin olmasını tercih ederim.
R. Schreurs,

13

Tüm nesneler için MS_description genişletilmiş özelliğini ayarlarım ve ardından tüm veritabanını ApexSQL Doc kullanarak belgelerim . Daha önce HTML belgeleri oluşturdum, ancak son zamanlarda PDF'yi tercih ediyorum


12

Veri modelleme araçlarını kullanıyorum çünkü veri tabanındaki veritabanına "uygun" olanlardan başka önemli bilgileri belgelememe izin veriyorlar. Gizlilik / güvenlik / hassasiyet endişeleri, idare, yönetişim, vs. gibi meta veriler

Bu, bir veritabanını belgelemek için ihtiyaç duyulanın ötesine geçebilir, ancak bu şeyler iş için önemlidir ve onların verilerini yönetmelerine yardımcı olur.

Resmi araçlar ayrıca birden fazla veritabanında / örnek / sunucuda depolanan verileri yönetmeme yardımcı olur. Bu bizim paketlenmiş uygulama dünyamızdan daha doğru olmamıştı.


10

Sql sunucusunu belgelemek için, son zamanlarda yayınlamanızı şiddetle tavsiye ederim:

SQL Server ve Windows Belgeleri Kendal Van Dyke tarafından yazılmış Windows PowerShell Kullanımı

Bağlantıdan kısa açıklama:

SQL Power Doc, SQL Server örneklerini ve bunların altında yatan Windows işletim sistemi ve makine yapılandırmalarını keşfeden, belgeleyen ve tanılayan bir Windows PowerShell scriptleri ve modülleri koleksiyonudur. SQL Power Doc, SQL Server 2000'den 2012'ye kadar tüm SQL Server sürümleriyle ve Windows 2000'den Windows Server'a ve Windows 2000'den Windows XP'ye ve Windows XP'den Tüketici Windows İşletim Sistemlerine tüm sürümleriyle birlikte çalışır. Windows Azure SQL Veritabanları.


10

DB Sözlük Oluşturan

iyi GUI ve ihracat / ithalat seçenekleri ile açık kaynak kodlu bir veritabanı dokümantasyon aracıdır. Belgeleri depolamak için Genişletilmiş özellikleri kullanır. Ayrıca, birincil anahtar sütunlar ve yabancı anahtar sütunlar için otomatik açıklamalar oluşturur.


1
.NET Framework 4.0 gerektirir ve yalnızca SQL Server ve SQL Express ile çalışır
kevinsky

8

Nitekim, Genişletilmiş Özellikler (MS_Description) gitmenin yoludur. Bu tanımların meta verilerin bir parçası olarak kolayca erişilebilir olması, sadece dokümanlar üreticileri tarafından değil, aynı zamanda (umarım bir gün) örneğin mükemmel Softtree'nin SQL Yardımcısı http://www.softtreetech.com/ adresinde "intellisense" sağlayan araçlar tarafından da kullanılabilir. isql.htm (son kontrol etmedilerse kontrol ettim) ya da SQL Sever Management Studio'nun Zekası (sql2008’den beri)

Ayrıca, devs ve DBA'ların bu notları eklemelerinin kolay olması gerektiğine inanıyorum, çünkü Tangurena ve Nick Chammas'ın doğru bir şekilde belirttiği gibi - devs, dokümanlar güncel tutmak ve yinelenen işlerden nefret etmek konusunda isteksiz - ki bu, özellikle öğretilen bir kişi için yeterince adil. Mesleki yaşamları boyunca işleri optimize etmek. Bu nedenle, dokümanları kaynak koduna yakın bir yerde güncellemek gerçekten kolay değilse, bu işe yaramayacak. Bir noktada web'i araştırdım ve bunun için bir çözüm bulamadım, bu yüzden LiveDoco'yu (ücretsiz değil, üzgünüm) yazmayı kolaylaştırmak için yazdım. İlgileniyorsanız daha fazla bilgi burada: http://www.livedoco.com/why-livedoco


7

Ayrıca wsSqlSrvDoc dosyasına da bakabilirsiniz . SQL Server genişletilmiş özellikleri ile çalışan ve bir MS Word belgesi oluşturan hoş küçük bir araçtır.

Tüm sütun özelliklerinin (yabancı anahtar ilişkileri olan) çıktısı kutudan çıkar. Her alandaki diğer açıklamalar için, bu sütunların genişletilmiş özelliklerini SQL Server Management Studio'da ayarlamanız gerekir.

Ücretsiz değil ama oldukça uygun. Yalnızca "devam etmeyen çalışma" DB için bir belge oluşturmanız gerekiyorsa, ücretsiz denemeyi kullanmak için yeterli olacağından daha az veya daha az bitmiştir.

Araç Web Sitesi


5

Veri sözlüğü oluşturmak, saklı yordamları ve işlevleri belgelemek için Dataedo'yu kullanırız . Visio'da oluşturulan ERD'leri yapıştırıyoruz. Tüm belgeler Dataedo meta veri deposunda (biçimlendirilmiş metin) saklanır ve dahili kullanım için HTML'ye veya basılı belge için PDF'ye dışa aktarırız.

Her nesneyi bir modüle atar ve her modülü bir kişiye atarız. Dataedo, dokümantasyon durum raporlaması ile birlikte gelir, böylece belgelenmesi gereken yeni bir sütun veya tablo olup olmadığını anlayabiliriz.


1

Düzenli olarak --önceden belirlenmiş yorumları .sqldosyada kullanabilirsiniz.

Yararları arasında, belgelerin veritabanı şeması koduyla birlikte olduğu ve onu Git gibi bir sürüm kontrol sistemine kolayca bağlayabileceğiniz bir yer vardır .

Örnek:

-- 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
);

Belki de XML kullanabilirsiniz.

-- <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)
);

Ayrıca bir benzerlik bazı sözdizimi kullanabilirsiniz 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 <jsmith@example.com>
-- @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)
);

Veya MarkDown sözdizimini kullanabilirsiniz.

-- # 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)
);

1

ERD Diyagramları (Veritabanı Diyagramları) ekibim için her zaman en faydalı olanlardı.

Ancak oluşturduğumuz her tablonun ve sütununun özelliklerine " Decription " yazmanın kuralı vardır .

Sonra bir yazılım adıdır kullanmak Enterprise Architect belgelemek için Tablestüm Indexes, Foreign KeysVe Columnsile Typeve Tanımı .

görüntü tanımını buraya girin


-1

Özellikle MySQL için, her zaman MySQL Workbench kullanıyoruz . Tasarımcılarımızda veritabanı tasarımlarımızı yarattıktan sonra çalıştırılabilir bir SQL betiği olarak ihraç ediyoruz. Tasarımdaki tüm değişiklikleri uygulamak ve ardından oluşturulan komut dosyasını çalıştırmak, tasarımın ve asıl veritabanının birbiriyle mükemmel bir şekilde senkronize olmasını ve belgelerin bu kadar kolay eskimez hale gelmesini sağlar.

Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.