Bagaimana Anda mendokumentasikan basis data Anda?

Saya menemukan bahwa sebagian besar klien saya tidak mendokumentasikan database mereka sama sekali dan saya menemukan itu cukup menakutkan. Untuk memperkenalkan beberapa praktik yang lebih baik, saya ingin tahu alat / proses apa yang digunakan orang.

• Bagaimana Anda mendokumentasikan basis data Anda? (SQL-Server)
• Alat apa yang Anda gunakan?
• Format Penyimpanan Dokumentasi untuk skema basis data / meta-data?
  • Dokumen Word
  • Lembar kerja Excel
  • Teks Biasa
• Proses atau kebijakan dokumentasi?

Saya tidak berbicara tentang rekayasa balik / mendokumentasikan database yang ada, tetapi terutama pada praktik terbaik dokumentasi saat Anda mengembangkan sistem / database Anda.

Saya telah menggunakan properti yang diperluas karena sangat fleksibel. Sebagian besar alat dokumentasi standar dapat dimatikan MS_Description, dan kemudian Anda dapat menggunakannya sendiri dengan alat yang dibuat khusus.

Lihat presentasi ini: # 41-Dapatkan Tuas dan Pilih Any Turtle: Mengangkat dengan Metadata

Dan kode ini: http://code.google.com/p/caderoux/wiki/LeversAndTurtles

Microsoft Visio Pro (sampai dengan Visio 2010) dapat balik database seperti dapat CA Erwin . Visio adalah opsi yang lebih murah, tetapi ERwin adalah opsi yang lebih rinci, lebih lengkap. Properti yang diperluas bagus, jika orang-orang repot-repot melihatnya. Anda juga bisa menggunakan sesuatu seperti Red Docr Gate SQL untuk menghasilkan dokumentasi dalam format HTML.

Saya menemukan konvensi penamaan dan mengatur kunci asing dengan benar mengarah ke database yang hampir bisa didokumentasikan sendiri. Anda masih harus memiliki beberapa dokumen eksternal untuk memahami tujuan dengan lebih baik.

Coba SchemaSpy: http://schemaspy.sourceforge.net/

Untuk SQL Server saya menggunakan properti yang diperluas.

Dengan Skrip PowerShell berikut ini, saya dapat membuat skrip Buat Tabel untuk tabel tunggal atau untuk semua tabel dalam skema dbo.

Script berisi Create tableperintah, kunci utama dan indeks. Kunci asing ditambahkan sebagai komentar. Properti diperluas dari tabel dan kolom tabel ditambahkan sebagai komentar. Ya, properti multi-baris didukung.

Script disetel ke gaya pengkodean pribadi saya.

• tidak ada koleksi individu untuk satu kolom.

• saat ini memerlukan Sql Server Authentication.

Berikut ini adalah kode lengkap untuk mengubah properti yang diperluas menjadi dokumen ASCII tua yang bagus (BTW valid sql untuk membuat ulang tabel Anda):

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

Anda dapat skrip skema dbo lengkap dari database yang diberikan

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

Atau filter untuk satu tabel

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

Lihatlah SchemaCrawler - ini adalah alat baris perintah gratis yang saya rancang untuk melakukan apa yang Anda cari. SchemaCrawler menghasilkan file teks dengan semua objek skema database. Output teks ini dirancang agar dapat dibaca oleh manusia, serta mampu melawan keluaran serupa dari server lain.

Dalam praktiknya, apa yang saya temukan adalah bahwa menghasilkan file teks dari skema basis data berguna, ketika dilakukan sebagai bagian dari build. Dengan cara ini, Anda dapat memeriksa file teks ke dalam sistem kontrol kode sumber Anda, dan memiliki riwayat versi tentang bagaimana skema Anda telah berkembang dari waktu ke waktu. SchemaCrawler dirancang untuk mengotomatisasi ini juga, dari baris perintah.

Jika pernah ditulis, dokumentasi terdiri dari dokumen kata. Beberapa diagram hubungan akan disertakan. Daftar tabel dan deskripsi singkat tentang apa yang masing-masing tabel pegang dan bagaimana hubungannya dengan tabel lainnya. Satu bab dokumentasi termasuk pengaturan keamanan: izin apa yang dibutuhkan oleh "pengguna" yang dibutuhkan aplikasi?

Secara umum, di perusahaan tempat saya bekerja, dokumentasi basis data hanya ditulis ketika pelanggan adalah orang yang melakukan audit, yang cenderung membatasi penggunaannya untuk pelanggan keuangan dan pemerintah.

Penafian: terlalu banyak pengembang mengambil sikap bahwa kode itu adalah dokumentasi , dan saya juga bersalah karenanya.

Saya menggunakan properti diperluas dan Red Gates SQL Doc. Bekerja dengan sangat baik!

Lucu, saya bertanya-tanya bagaimana orang lain melakukan ini juga ..

Saat mengembangkan proyek basis data besar pertama saya, saya menemukan bahwa Microsoft SQL Server Management Studio 10.0.1600.22 mendukung diagram basis data yang dapat Anda ekspor ke dokumen kata atau perangkat lunak dokumentasi lain di mana Anda dapat menambahkan sebanyak mungkin detail dokumentasi yang Anda inginkan. Cukup rentangkan basis data yang Anda sambungkan pada SQL Management Studio dan klik kanan pada "database diagram" di objek explorer dan pilih "New Database Diagram" untuk menghasilkan diagram interaktif yang akan menunjukkan semua hubungan antara tabel yang berbeda. Anda bahkan dapat menentukan tabel mana yang ingin Anda sertakan dalam diagram, sehingga gambar tidak menjadi tidak adil jika Anda hanya mencoba mendokumentasikannya sepotong demi sepotong. Ekspor gambar ke perangkat lunak pengedit lainnya dan komentar sebanyak yang Anda inginkan.

Saya juga merekomendasikan banyak / komentar / dalam skrip yang menghasilkan basis data Anda.

Secara umum banyak pekerjaan menuliskan untuk apa semua ini, tetapi ide yang bagus untuk jangka panjang, seperti ketika Anda atau beberapa jiwa miskin lainnya kembali untuk memperbarui kreasi Anda beberapa tahun kemudian! :)

Saya mengatur properti diperluas MS_description untuk semua objek dan kemudian mendokumentasikan seluruh database menggunakan ApexSQL Doc . Saya dulu membuat dokumen HTML sebelumnya, tetapi belakangan ini saya lebih suka PDF

Saya menggunakan alat pemodelan data karena memungkinkan saya untuk mendokumentasikan informasi penting tentang database selain apa yang "cocok" dalam database. Data meta seperti masalah privasi / keamanan / sensitivitas, pengelolaan, tata kelola, dll.

Itu mungkin melampaui apa yang beberapa orang butuhkan dalam mendokumentasikan database, tetapi hal-hal itu penting bagi bisnis dan membantu mereka mengelola data mereka.

Alat formal juga membantu saya dalam mengelola data yang disimpan di lebih dari satu database / instance / server. Ini tidak pernah lebih benar daripada di dunia aplikasi terpaket kami.

Untuk Mendokumentasikan sql server, saya sangat merekomendasikan yang baru dirilis:

Dokumentasi SQL Server & Windows Menggunakan Windows PowerShell yang ditulis oleh Kendal Van Dyke

Deskripsi singkat dari tautan:

SQL Power Doc adalah kumpulan skrip dan modul Windows PowerShell yang menemukan, mendokumentasikan, dan mendiagnosis instance SQL Server serta konfigurasi OS & mesin Windows yang mendasarinya. SQL Power Doc bekerja dengan semua versi SQL Server dari SQL Server 2000 hingga 2012, dan semua versi Windows Server dan sistem operasi Windows konsumen dari Windows 2000 dan Windows XP melalui Windows Server 2012 dan Windows 8. SQL Power Doc juga mampu mendokumentasikan Windows Azure SQL Database.

Pembuat Kamus DB

adalah alat dokumentasi basis data sumber terbuka dengan GUI dan opsi ekspor / impor yang layak. Ini menggunakan properti Extended untuk menyimpan dokumentasi. Itu juga akan menghasilkan deskripsi otomatis untuk kolom kunci utama dan kolom kunci asing.

Memang, Properties Extended (MS_Description) adalah cara untuk pergi. Memiliki deskripsi ini tersedia sebagai bagian dari metadata dapat digunakan tidak hanya oleh generator docs tetapi juga (mudah-mudahan suatu hari) oleh alat yang menyediakan "intellisense" misalnya Asisten SQL Softtree yang sangat baik http://www.softtreetech.com/ isql.htm (terakhir kali saya memeriksa mereka tidak) atau dibangun di Intellisense SQL Sever Management Studio (sejak sql2008)

Saya juga percaya seharusnya mudah bagi para devs dan DBA untuk menambahkan catatan ini karena sebagaimana ditunjukkan oleh Tangurena dan Nick Chammas dengan benar - devs sangat enggan untuk menjaga dokumen diperbarui dan membenci pekerjaan duplikat - yang cukup adil terutama bagi orang yang diajar untuk mengoptimalkan berbagai hal selama seluruh kehidupan profesional mereka. Jadi kecuali sangat mudah untuk memperbarui dokumen di satu tempat yang dekat dengan kode sumber - ini tidak akan berhasil. Pada titik tertentu saya mencari di web dan tidak menemukan solusi untuk ini jadi saya menulis LiveDoco (tidak gratis, maaf) untuk membuatnya mudah. Info lebih lanjut di sini jika tertarik: http://www.livedoco.com/why-livedoco

Anda juga bisa melihat wsSqlSrvDoc . Ini adalah alat kecil yang bagus yang bekerja dengan properti SQL Server yang diperluas dan membuat dokumen MS Word.

Print-out semua properti kolom (dengan hubungan kunci asing) berfungsi di luar kotak. Untuk keterangan lebih lanjut tentang setiap bidang Anda harus mengatur properti diperluas kolom-kolom di SQL Server Management Studio.

Ini tidak gratis tetapi cukup terjangkau. Jika Anda hanya perlu membuat dokumentasi untuk "tidak bekerja dalam proses" DB yang lebih atau kurang selesai daripada itu akan cukup untuk menggunakan uji coba gratis.

Situs Alat

Kami menggunakan Dataedo untuk membuat kamus data, mendokumentasikan prosedur dan fungsi yang tersimpan. Kami menempel ERD yang dibuat di Visio. Semua dokumentasi disimpan dalam repositori metadata Dataedo (teks berformat) dan kami mengekspornya ke HTML untuk penggunaan internal atau ekspor ke PDF untuk dokumen cetak.

Kami menetapkan setiap objek ke modul dan menetapkan setiap modul untuk seseorang. Dataedo dilengkapi dengan pelaporan status dokumentasi sehingga kami dapat mengetahui apakah ada kolom atau tabel baru yang perlu didokumentasikan.

Anda dapat menggunakan --komentar reguler yang sudah ada dalam .sqlfile.

Manfaatnya termasuk bahwa dokumentasi tersebut berisi kode untuk skema basis data dan Anda dapat dengan mudah memasukkannya ke sistem kontrol versi seperti Git .

Contoh:

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

Mungkin Anda bisa menggunakan XML juga.

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

Anda juga bisa menggunakan beberapa sintaks dengan kemiripan 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)
);

Atau Anda bisa menggunakan sintaks 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 Diagram (Database Diagram) selalu menjadi yang paling berguna untuk tim saya

Tetapi ada aturan untuk menulis " Decription " di Properties dari setiap tabel dan kolom yang kita buat.

Kemudian kami menggunakan nama perangkat lunak Enterprise Arsitek untuk mendokumentasikan Tablesdengan semua Indexes, Foreign KeysDan Columnsdengan Typedan Deskripsi .

Khusus untuk MySQL, kami selalu menggunakan MySQL Workbench . Kami membuat desain basis data kami di perancang, lalu mengekspornya sebagai skrip SQL yang dapat dijalankan. Menerapkan semua perubahan dalam desain dan kemudian menjalankan skrip yang dihasilkan memastikan bahwa desain dan database aktual benar-benar sinkron satu sama lain, dan bahwa dokumentasi tidak akan menjadi usang dengan mudah.