Làm thế nào để bạn tài liệu cơ sở dữ liệu của bạn?


227

Tôi thấy rằng hầu hết các khách hàng của tôi hoàn toàn không ghi lại cơ sở dữ liệu của họ và tôi thấy điều đó khá đáng sợ. Để giới thiệu một số thực tiễn tốt hơn, tôi muốn biết những công cụ / quy trình mọi người đang sử dụng.

  • Làm thế nào để bạn tài liệu cơ sở dữ liệu của bạn? (Máy chủ SQL)
  • Bạn sử dụng công cụ gì?
  • Định dạng lưu trữ tài liệu cho lược đồ cơ sở dữ liệu / siêu dữ liệu?
    • Tài liệu Word
    • bảng tính Excel
    • Văn bản thô
  • Quy trình tài liệu hay chính sách?

Tôi không nói về kỹ thuật đảo ngược / tài liệu cơ sở dữ liệu hiện có, mà chủ yếu là về tài liệu thực hành tốt nhất trong khi bạn phát triển hệ thống / cơ sở dữ liệu của bạn.

Câu trả lời:


78

Tôi đã sử dụng các thuộc tính mở rộng vì chúng rất linh hoạt. Hầu hết các công cụ tài liệu tiêu chuẩn có thể được tắt MS_Description, và sau đó bạn có thể sử dụng công cụ của riêng bạn với các công cụ được tạo tùy chỉnh.

Xem bản trình bày này: # 41-Nhận đòn bẩy và chọn bất kỳ con rùa nào: Nâng bằng siêu dữ liệu

Và mã này: http://code.google.com.vn/p/caderoux/wiki/LeversAndTurtles


3
Bạn có thể thay đổi một cái gì đó và quên thay đổi các thuộc tính mở rộng của mình cho phù hợp, khiến chúng không chính xác. Bạn có thể tự động phát hiện sự khác biệt như vậy?
AK

2
Ít nhất, người ta có thể truy vấn lược đồ cơ sở dữ liệu (sys.tables / sys.columns) và tham gia vào các thuộc tính mở rộng của nó (sys.extends_properies) để xác định các trường không có tài liệu, sau đó biến tập lệnh đó thành một bài kiểm tra để chạy khi triển khai.
Mi-chê

59

Microsoft Visio Pro (lên đến Visio 2010) có thể thiết kế đối chiếu một cơ sở dữ liệu như thể CA của Erwin . Visio là tùy chọn rẻ hơn, nhưng ERwin là tùy chọn chi tiết hơn, đầy đủ hơn. Tài sản mở rộng là tốt đẹp, nếu mọi người bận tâm để xem xét chúng. Bạn cũng có thể sử dụng một cái gì đó như SQL Doc của Red Gate để xuất tài liệu ở định dạng HTML.

Tôi tìm thấy quy ước đặt tên và thiết lập đúng cách các phím nước ngoài dẫn đến hầu hết cơ sở dữ liệu tự ghi lại. Bạn vẫn nên có một số tài liệu bên ngoài để hiểu rõ hơn về mục đích.


Điều mà một lược đồ đơn giản thường bị thiếu (ngay cả trong cơ sở dữ liệu có tên và khóa ngoài) là các mô tả về các trường. Theo kinh nghiệm của tôi, có tất cả các trường đủ đơn giản để khớp với tên cột.
StockB


26

Đối với SQL Server, tôi đang sử dụng các thuộc tính mở rộng.

Với Tập lệnh PowerShell sau đây, tôi có thể tạo tập lệnh Tạo bảng cho một bảng hoặc cho tất cả các bảng trong lược đồ dbo.

Kịch bản chứa một Create tablelệnh, khóa chính và chỉ mục. Khóa ngoại được thêm vào dưới dạng bình luận. Các thuộc tính mở rộng của bảng và cột bảng được thêm vào dưới dạng nhận xét. Có nhiều thuộc tính được hỗ trợ.

Kịch bản được điều chỉnh theo phong cách mã hóa cá nhân của tôi.

  • không có đối chiếu riêng lẻ cho các cột đơn.

  • hiện tại nó yêu cầu Xác thực Máy chủ Sql.

Đây là mã hoàn chỉnh để biến các thuộc tính mở rộng thành một tài liệu ASCII cũ đơn giản (BTW là sql hợp lệ để tạo lại các bảng của bạn):

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

Bạn có thể tập lệnh hoàn thành lược đồ dbo của cơ sở dữ liệu đã cho

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

Hoặc lọc cho một bảng duy nhất

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

21

Hãy xem SchemaCrawler - đây là công cụ dòng lệnh miễn phí của tôi mà tôi đã thiết kế để làm những gì bạn đang tìm kiếm. SchemaCrawler tạo ra một tệp văn bản với tất cả các đối tượng lược đồ cơ sở dữ liệu. Đầu ra văn bản này được thiết kế để có thể đọc được cả con người, cũng như có thể chống lại đầu ra tương tự từ một máy chủ khác.

Trong thực tế, những gì tôi đã tìm thấy là việc xuất ra một tệp văn bản của lược đồ cơ sở dữ liệu là hữu ích, khi được thực hiện như một phần của bản dựng. Bằng cách này, bạn có thể kiểm tra tệp văn bản vào hệ thống kiểm soát mã nguồn của mình và có lịch sử phiên bản về cách lược đồ của bạn đã phát triển theo thời gian. SchemaCrawler được thiết kế để tự động hóa điều này, từ dòng lệnh.


20

Nếu nó được viết, tài liệu này bao gồm một tài liệu từ. Một vài sơ đồ mối quan hệ sẽ được bao gồm. Danh sách các bảng và mô tả ngắn gọn về những gì mỗi bảng giữ và cách nó liên quan đến các bảng khác. Một chương của tài liệu bao gồm các cài đặt bảo mật: "người dùng" mà ứng dụng cần có quyền gì?

Nói chung, trong các công ty tôi từng làm việc, tài liệu cơ sở dữ liệu chỉ được viết khi khách hàng là người thực hiện kiểm toán, có xu hướng giới hạn việc sử dụng nó cho khách hàng tài chính và chính phủ.

Tuyên bố miễn trừ trách nhiệm: quá nhiều nhà phát triển có thái độ rằng mã là tài liệu và tôi cũng đã phạm tội.


10
Một vấn đề lớn mà tôi tìm thấy với tài liệu không bị ràng buộc chặt chẽ với mã (ví dụ: một tài liệu Word riêng, trái ngược với sơ đồ lược đồ được tạo tự động + các đối tượng cơ sở dữ liệu được đặt tên tốt) là tài liệu này được đảm bảo không bị sai như Thơi gian trôi. Lý do rất đơn giản: một tài liệu riêng biệt sao chép thông tin một cách hiệu quả. Nếu không có cách tự động để giữ cho nó đồng bộ với nguồn, nó sẽ trở nên lỗi thời rất nhanh. So sánh điều này với một công cụ tạo sơ đồ lược đồ trực tiếp từ cơ sở dữ liệu và lấy các nhận xét thích hợp từ bên trong mã.
Nick Chammas

16

Tôi sử dụng các thuộc tính mở rộng và Red Gates SQL Doc. Hoạt động rất tốt!


14

Thật buồn cười, tôi đã tự hỏi làm thế nào những người khác cũng làm điều này ..

Khi phát triển dự án cơ sở dữ liệu lớn đầu tiên của mình, tôi thấy rằng Microsoft SQL Server Management Studio 10.0.1600.22 hỗ trợ các sơ đồ cơ sở dữ liệu mà bạn có thể xuất thành tài liệu từ hoặc phần mềm tài liệu khác nơi bạn có thể thêm chi tiết tài liệu như bạn muốn. Chỉ cần mở rộng cơ sở dữ liệu mà bạn đã kết nối trên SQL Management Studio và nhấp chuột phải vào "sơ đồ cơ sở dữ liệu" trong trình thám hiểm đối tượng và chọn "Sơ đồ cơ sở dữ liệu mới" để tạo sơ đồ tương tác sẽ hiển thị tất cả các mối quan hệ giữa các bảng khác nhau. Bạn thậm chí có thể chỉ định những bảng nào bạn muốn đưa vào sơ đồ, để hình ảnh không bị rối nếu bạn chỉ cố gắng ghi lại từng mảnh một. Xuất hình ảnh sang bất kỳ phần mềm chỉnh sửa nào khác và bình luận nhiều như bạn muốn.

Tôi cũng đề xuất nhiều / bình luận / trong tập lệnh tạo cơ sở dữ liệu của bạn.

Nói chung, có rất nhiều công việc viết ra tất cả những gì nó làm, nhưng một ý tưởng tốt về lâu dài, chẳng hạn như khi bạn hoặc một linh hồn đáng thương nào đó quay lại để cập nhật sáng tạo của bạn một vài năm sau đó! :)


3
Tôi không sử dụng các sơ đồ SQL Server, vì các ràng buộc khóa ngoài chỉ được kết nối ở đâu đó với các bảng, giống như được thực hiện trong các sơ đồ ER . Tôi thích có các kết nối kết nối các trường khóa chính và nước ngoài.
R. Schreurs

13

Tôi đặt thuộc tính mở rộng MS_description cho tất cả các đối tượng và sau đó ghi lại toàn bộ cơ sở dữ liệu bằng ApexQuery Doc . Tôi đã sử dụng để tạo tài liệu HTML trước đó, nhưng gần đây tôi thích PDF


12

Tôi sử dụng các công cụ mô hình hóa dữ liệu vì chúng cho phép tôi ghi lại thông tin quan trọng về cơ sở dữ liệu ngoài những gì "phù hợp" trong cơ sở dữ liệu. Dữ liệu meta như quyền riêng tư / bảo mật / độ nhạy cảm, quản lý, quản trị, v.v.

Điều đó có thể vượt xa những gì một số người cần trong việc ghi lại cơ sở dữ liệu, nhưng những điều đó rất quan trọng đối với doanh nghiệp và giúp họ quản lý dữ liệu của họ.

Các công cụ chính thức cũng giúp tôi quản lý dữ liệu được lưu trữ trong nhiều cơ sở dữ liệu / thể hiện / máy chủ. Điều này chưa bao giờ đúng hơn trong thế giới ứng dụng đóng gói của chúng tôi.


10

Đối với tài liệu máy chủ sql, tôi khuyên bạn nên phát hành gần đây:

Tài liệu SQL Server & Windows bằng Windows PowerShell được viết bởi Kendal Van Dyke

Mô tả ngắn gọn từ liên kết:

SQL Power Doc là một tập hợp các tập lệnh và mô-đun Windows PowerShell khám phá, lập tài liệu và chẩn đoán các phiên bản SQL Server cũng như các cấu hình máy và hệ điều hành Windows bên dưới của chúng. SQL Power Doc hoạt động với tất cả các phiên bản SQL Server từ SQL Server 2000 đến 2012 và tất cả các phiên bản Windows Server và hệ điều hành Windows tiêu dùng từ Windows 2000 và Windows XP thông qua Windows Server 2012 và Windows 8. SQL Power Doc cũng có khả năng ghi lại Cơ sở dữ liệu Windows Azure SQL.


10

Trình tạo từ điển DB

là một công cụ tài liệu cơ sở dữ liệu nguồn mở với GUI tùy chọn và xuất / nhập tốt. Nó sử dụng các thuộc tính mở rộng để lưu trữ tài liệu. Nó cũng sẽ tạo mô tả tự động cho các cột khóa chính và cột khóa ngoài.


1
yêu cầu .NET Framework 4.0 và chỉ hoạt động với SQL Server và SQL Express
kevinsky

8

Thật vậy, Thuộc tính mở rộng (MS_Des mô tả) là cách để đi. Có sẵn các mô tả này như một phần của siêu dữ liệu không chỉ được sử dụng bởi các trình tạo tài liệu mà còn (hy vọng một ngày nào đó) bởi các công cụ cung cấp "intellisense", ví dụ như Trợ lý SQL xuất sắc của Softtree http://www.softtreetech.com/ isql.htm (lần trước tôi đã kiểm tra họ đã không) hoặc được xây dựng trong SQL Sever Management Studio's Intellisense (kể từ sql2008)

Tôi cũng tin rằng các nhà phát triển và DBA nên dễ dàng thêm các ghi chú này vì như Tangurena và Nick Chammas đã chỉ ra một cách chính xác - các nhà phát triển rất miễn cưỡng giữ các tài liệu được cập nhật và ghét công việc trùng lặp - điều này đủ công bằng đặc biệt đối với một người được dạy để tối ưu hóa mọi thứ trong suốt cuộc đời chuyên nghiệp của họ. Vì vậy, trừ khi thật dễ dàng để cập nhật tài liệu ở một nơi gần với mã nguồn - điều này sẽ không hiệu quả. Tại một số thời điểm tôi đã tìm kiếm trên web và không tìm thấy giải pháp nào cho vấn đề này nên tôi đã viết LiveDoco (không miễn phí, xin lỗi) để cố gắng làm cho nó dễ dàng. Thêm thông tin ở đây nếu quan tâm: http://www.livingoco.com/why-livingoco


7

Bạn cũng có thể xem wsSqlSrvDoc . Đây là một công cụ nhỏ xinh hoạt động với các thuộc tính mở rộng của SQL Server và tạo tài liệu MS Word.

Bản in ra của tất cả các thuộc tính cột (có quan hệ khóa ngoài) hoạt động ngoài hộp. Để biết thêm mô tả về từng lĩnh vực, bạn phải thiết lập các thuộc tính mở rộng của các cột đó trong SQL Server Management Studio.

Nó không miễn phí nhưng khá phải chăng. Nếu bạn chỉ cần tạo một tài liệu cho một DB "không hoạt động", thì nó đã hoàn thành ít nhiều hơn là đủ để sử dụng bản dùng thử miễn phí.

Trang web công cụ


5

Chúng tôi sử dụng Dataedo để tạo từ điển dữ liệu, các thủ tục và chức năng lưu trữ tài liệu. Chúng tôi dán ERD được tạo trong Visio. Tất cả tài liệu được lưu trữ trong kho siêu dữ liệu của Dataedo (văn bản có định dạng) và chúng tôi xuất nó sang HTML để sử dụng nội bộ hoặc xuất sang PDF cho tài liệu in.

Chúng tôi gán từng đối tượng cho một mô-đun và gán từng mô-đun cho một người. Dataedo đi kèm với báo cáo trạng thái tài liệu để chúng tôi có thể biết nếu có một cột hoặc bảng mới cần được ghi lại.


1

Bạn có thể sử dụng các --bình luận được tổng hợp thường xuyên trong .sqltệp.

Lợi ích bao gồm tài liệu đi kèm với mã cho lược đồ cơ sở dữ liệu và bạn có thể dễ dàng cam kết nó với một hệ thống kiểm soát phiên bản như Git .

Thí dụ:

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

Có lẽ bạn cũng có thể sử dụng 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)
);

Bạn cũng có thể sử dụng một số cú pháp tương tự 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)
);

Hoặc bạn có thể sử dụng cú pháp 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)
);

1

Biểu đồ ERD (Sơ đồ cơ sở dữ liệu) luôn là những biểu đồ hữu ích nhất cho nhóm của tôi

Nhưng có quy tắc để viết " Decription " trong Thuộc tính của mỗi bảng và cột mà chúng ta tạo.

Sau đó, chúng tôi sử dụng một tên phần mềm là Enterprise Architect để ghi lại Tablestất cả Indexes, Foreign KeysColumnsvới TypeMô tả .

nhập mô tả hình ảnh ở đây


-1

Đối với MySQL nói riêng, chúng tôi luôn sử dụng MySQL Workbench . Chúng tôi tạo các thiết kế cơ sở dữ liệu của mình trong trình thiết kế, sau đó xuất nó dưới dạng tập lệnh SQL có thể chạy được. Áp dụng tất cả các thay đổi trong thiết kế và sau đó chạy tập lệnh được tạo sẽ đảm bảo rằng thiết kế và cơ sở dữ liệu thực tế hoàn toàn đồng bộ với nhau và tài liệu sẽ không bị lỗi thời một cách dễ dàng.

Khi sử dụng trang web của chúng tôi, bạn xác nhận rằng bạn đã đọc và hiểu Chính sách cookieChính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.