it-swarm.asia

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.

234
user316

Saya telah menggunakan properti yang diperluas karena sangat fleksibel. Sebagian besar alat dokumentasi standar dapat dihilangkan MS_Description, lalu Anda dapat menggunakan milik Anda 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

80
Cade Roux

Microsoft Visio Pro (hingga Visio 2010) dapat merekayasa balik basis data seperti halnya CA ERwin . Visio adalah opsi yang lebih murah, tetapi ERwin adalah opsi yang lebih rinci, lebih lengkap. Properti yang diperluas bagus, jika orang repot-repot melihatnya. Anda juga dapat menggunakan sesuatu seperti Red Gate SQL Doc untuk menghasilkan dokumentasi dalam format HTML.

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

27
Robert Durgin

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.

Skrip berisi Create table perintah, 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 biasa ASCII dokumen yang baik (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'
26
bernd_k

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 database 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.

21
Sualeh Fatehi

Jika pernah ditulis, dokumentasi terdiri dari dokumen Word. 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 yang kodenya adalah dokumentasi, dan saya juga bersalah karenanya.

20
Tangurena

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

16
jrara

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 Word atau perangkat lunak dokumentasi lain di mana Anda dapat menambahkan sebanyak mungkin detail dokumentasi yang Anda inginkan. Cukup rentangkan basis data yang Anda sambungkan ke 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! :)

14
fa1c0n3r

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

13
Carol Baker West

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 dibutuhkan beberapa orang 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.

12
Karen Lopez

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

SQL Server & Dokumentasi Windows Menggunakan Windows PowerShell 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 dan 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 konsumen Sistem Operasi Windows dari Windows 2000 dan Windows XP melalui Windows Server 2012 dan Windows 8 SQL Power Doc juga mampu mendokumentasikan Windows Azure SQL Databases.

10
Kin Shah

DB Dictionary Creator

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.

10
Sundeep Arun

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 (semoga 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 untuk orang yang diajar untuk mengoptimalkan berbagai hal selama seluruh kehidupan profesional mereka. Jadi kecuali sangat mudah untuk memperbarui dokumen di satu tempat 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

8
Zar Shardan

Anda juga dapat 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 yang diperluas dari kolom tersebut 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

7
Kurresh

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.

5
Ryszard Bocian

Anda dapat menggunakan -- Reguler - komentar yang diawali dalam file .sql.

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 dapat 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)
);
2
Fred

ERD Diagram (Database Diagram) selalu yang paling berguna untuk tim saya

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

Kemudian kami menggunakan nama perangkat lunaknya adalah Arsitek Perusahaan untuk mendokumentasikan Tables dengan semua Indexes, Foreign Keys Dan Columns dengan Type dan Keterangan .

enter image description here

1
El.Hum