it-swarm.asia

كيف توثق قواعد البيانات الخاصة بك؟

أجد أن معظم عملائي لا يوثقون قواعد بياناتهم على الإطلاق ، وأجد ذلك مخيفًا جدًا. لتقديم بعض الممارسات الأفضل ، أود أن أعرف ما هي الأدوات/العمليات التي يستخدمها الناس.

  • كيف توثق قاعدة البيانات الخاصة بك؟ (خادم قاعدة البيانات)
  • ما الأداة التي تستخدمها؟
  • تنسيق تخزين الوثائق لمخطط قاعدة البيانات/بيانات التعريف؟
    • مستندات Word
    • جداول البيانات إكسل
    • نص عادي
  • عملية التوثيق أو السياسات؟

أنا لا أتحدث عن الهندسة العكسية/توثيق قاعدة بيانات موجودة ، ولكن بشكل أساسي حول أفضل ممارسات التوثيق أثناء تطوير النظام/قاعدة البيانات.

234
user316

لقد استخدمت خصائص ممتدة لأنها مرنة للغاية. يمكن تشغيل معظم أدوات التوثيق القياسية MS_Description ، وبعد ذلك يمكنك استخدام أدواتك الخاصة مع أدوات مخصصة.

شاهد هذا العرض التقديمي: # 41-احصل على رافعة واختيار أي سلحفاة: الرفع باستخدام البيانات الوصفية

وهذا الكود: http://code.google.com/p/caderoux/wiki/LeversAndTurtles

80
Cade Roux

يمكن لـ Microsoft Visio Pro (حتى Visio 2010) إجراء هندسة عكسية لقاعدة بيانات مثل CA's ERwin . Visio هو الخيار الأرخص ، ولكن ERwin هو الخيار الأكثر تفصيلاً وأكثر اكتمالاً. الخصائص الممتدة جميلة ، إذا كان الناس يكلفون أنفسهم عناء النظر إليها. يمكنك أيضًا استخدام شيء مثل Red Gate's SQL Doc لإخراج الوثائق بتنسيق HTML.

أجد اصطلاحات التسمية وإعداد المفاتيح الخارجية بشكل صحيح يؤدي إلى قاعدة بيانات ذاتية التوثيق تقريبًا. لا يزال يجب أن يكون لديك بعض المستندات الخارجية لفهم الغرض بشكل أفضل.

59
Eric Humphrey - lotsahelp
27
Robert Durgin

بالنسبة لـ SQL Server ، أستخدم خصائص موسعة.

باستخدام برنامج PowerShell Script التالي ، يمكنني إنشاء نصوص إنشاء جدول لجدول واحد أو لجميع الجداول في مخطط dbo.

يحتوي البرنامج النصي على Create table الأمر ، المفاتيح والفهارس الأساسية. تتم إضافة المفاتيح الخارجية كتعليقات. تتم إضافة الخصائص الممتدة للجداول وأعمدة الجدول كتعليقات. نعم ، يتم دعم خصائص الخطوط المتعددة.

تم ضبط البرنامج النصي على نمط الترميز الشخصي الخاص بي.

  • لا يوجد ترتيب فردي للأعمدة الفردية.

  • يتطلب حاليًا مصادقة خادم Sql.

إليك الشفرة الكاملة لتحويل الخصائص الموسعة إلى نسخة جيدة قديمة ASCII (BTW من صالح 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'
26
bernd_k

ألق نظرة على SchemaCrawler - إنها أداة سطر الأوامر المجانية التي صممتها للقيام بما تبحث عنه. ينتج SchemaCrawler ملفًا نصيًا يحتوي على جميع كائنات مخطط قاعدة البيانات. تم تصميم إخراج النص هذا ليكون قابلاً للقراءة البشرية ، بالإضافة إلى إمكانية الاختلاف مقارنة بالإخراج المماثل من خادم آخر.

عمليًا ، ما وجدته هو أن إخراج ملف نصي من مخطط قاعدة البيانات مفيد ، عندما يتم ذلك كجزء من البناء. وبهذه الطريقة ، يمكنك التحقق من الملف النصي في نظام التحكم في التعليمات البرمجية المصدر ، والحصول على تاريخ إصدار لكيفية تطور مخططك بمرور الوقت. تم تصميم SchemaCrawler لأتمتة هذا أيضًا ، من سطر الأوامر.

21
Sualeh Fatehi

إذا تمت كتابتها في أي وقت ، تتكون الوثائق من مستند Word. سيتم تضمين زوجين من مخططات العلاقات. قوائم الجداول ووصف موجز لما يحمله كل جدول وكيف يرتبط بجداول أخرى. يتضمن فصل واحد من الوثائق إعدادات الأمان: ما هي الأذونات التي يحتاجها "المستخدم" التي يحتاجها التطبيق؟

بشكل عام ، في الشركات التي عملت فيها ، تتم كتابة وثائق قاعدة البيانات فقط عندما يكون العميل هو الذي يقوم بالتدقيق ، والذي يميل إلى قصر استخدامه على العملاء الماليين والحكوميين.

إخلاء المسؤولية: يتخذ عدد كبير جدًا من المطورين موقفًا الرمز هو التوثيق ، وقد أدينت بذلك أيضًا.

20
Tangurena

يمكنني استخدام الخصائص الممتدة ووثيقة Red Gates SQL. يعمل بشكل جيد للغاية!

16
jrara

مضحك ، كنت أتساءل كيف يفعل الآخرون ذلك أيضًا ..

أثناء تطوير أول مشروع كبير لقاعدة البيانات ، وجدت أن Microsoft SQL Server Management Studio 10.0.1600.22 يدعم الرسوم البيانية لقاعدة البيانات التي يمكنك تصديرها إلى مستند Word أو برنامج توثيق آخر حيث يمكنك إضافة أكبر قدر ممكن من تفاصيل الوثائق كما تريد. فقط قم بتوسيع قاعدة البيانات التي اتصلت بها على SQL Management Studio وانقر بزر الماوس الأيمن على "الرسوم البيانية لقاعدة البيانات" في مستكشف الكائنات وحدد "مخطط قاعدة بيانات جديد" لإنشاء رسم تخطيطي تفاعلي والذي سيظهر جميع العلاقات بين الجداول المختلفة. يمكنك حتى تحديد الجداول التي تريد تضمينها في المخططات ، بحيث لا تحصل الصورة بشكل غريب إذا كنت تحاول فقط توثيقها قطعة قطعة. قم بتصدير الصورة إلى أي برنامج تحرير آخر وقم بالتعليق بقدر ما تريد.

أوصي أيضًا بالكثير من/التعليقات/في البرنامج النصي الذي ينشئ قاعدة بياناتك.

بشكل عام ، هناك الكثير من العمل لتدوين الغرض من كل شيء ، ولكن فكرة جيدة على المدى الطويل ، مثل عندما تعود أنت أو بعض الروح الفقيرة الأخرى لتحديث إبداعك بعد بضع سنوات! :)

14
fa1c0n3r

قمت بتعيين خاصية MS_description الممتدة لجميع الكائنات ثم قمت بتوثيق قاعدة البيانات بأكملها باستخدام ApexSQL Doc . اعتدت على إنشاء مستندات HTML في وقت سابق ، لكني أفضل PDF مؤخرًا

13
Carol Baker West

أستخدم أدوات نمذجة البيانات لأنها تسمح لي بتوثيق معلومات مهمة حول قاعدة البيانات بخلاف ما "يناسب" في قاعدة البيانات. بيانات التعريف مثل مخاوف الخصوصية/الأمان/الحساسية ، الإدارة ، الحوكمة ، إلخ.

قد يتجاوز ذلك ما يحتاجه البعض في توثيق قاعدة البيانات ، ولكن هذه الأشياء مهمة للأعمال ومساعدتهم على إدارة بياناتهم.

تساعدني الأدوات الرسمية أيضًا في إدارة البيانات المخزنة في أكثر من قاعدة بيانات/مثيل/خادم. لم يكن هذا أكثر صحة من أي وقت مضى في عالم التطبيقات المعبأة لدينا.

12
Karen Lopez

بالنسبة لتوثيق خادم SQL ، أوصي بشدة بإصداره مؤخرًا:

خادم SQL ووثائق Windows باستخدام Windows PowerShell بقلم كيندال فان دايك

وصف موجز من الرابط:

SQL Power Doc عبارة عن مجموعة من البرامج النصية والوحدات النمطية لـ Windows PowerShell التي تكتشف وتوثق وتشخيص مثيلات SQL Server وتكوينات نظام التشغيل Windows & الجهاز الأساسية الخاصة بها. يعمل SQL Power Doc مع جميع إصدارات SQL Server من SQL Server 2000 حتى 2012 ، وجميع إصدارات Windows Server وأنظمة تشغيل Windows للمستهلكين من Windows 2000 و Windows XP من خلال Windows Server 2012 و Windows 8 إن SQL Power Doc قادر أيضًا على توثيق قواعد بيانات Windows Azure SQL.

10
Kin Shah

منشئ قاموس DB

هي أداة توثيق قاعدة بيانات مفتوحة المصدر مع واجهة مستخدم رسومية جيدة وخيارات تصدير/استيراد. يستخدم خصائص ممتدة لتخزين الوثائق. سيقوم أيضًا بإنشاء أوصاف تلقائية لأعمدة المفاتيح الأساسية وأعمدة المفاتيح الخارجية.

10
Sundeep Arun

وبالفعل ، فإن Extended Properties (MS_Description) هو السبيل للذهاب. إن إتاحة هذه الأوصاف بسهولة كجزء من البيانات الوصفية يمكن استخدامها ليس فقط من قبل مولدات المستندات ولكن أيضًا (كما نأمل في يوم واحد) من خلال الأدوات التي توفر "التحسس" على سبيل المثال مساعد Softtree الممتاز SQL http: // www. softtreetech.com/isql.htm (آخر مرة راجعت أنهم لم يفعلوا ذلك) أو بنيت في Intellisense في SQL Sever Management Studio (منذ sql2008)

أعتقد أيضًا أنه يجب أن يكون من السهل على devs و DBA إضافة هذه الملاحظات لأنه كما أشار Tangurena و Nick Chammas بشكل صحيح - ديفز متردد للغاية في الحفاظ على المستندات محدثة ويكرهون العمل المكرر - وهو أمر عادل بما يكفي بالنسبة لشخص تم تعليمه لتحسين الأشياء طوال حياتهم المهنية. لذلك ما لم يكن من السهل حقًا تحديث المستندات في مكان واحد قريب من شفرة المصدر - لن يعمل هذا. في مرحلة ما ، قمت بالبحث في الويب ولم أجد حلاً لهذا لذا كتبت LiveDoco (ليس مجانيًا ، آسف) في محاولة لتسهيل الأمر. مزيد من المعلومات هنا إذا كانت مهتمة: http://www.livedoco.com/why-livedoco

8
Zar Shardan

يمكنك أيضًا إلقاء نظرة على wsSqlSrvDoc . إنها أداة صغيرة لطيفة تعمل مع خصائص SQL Server الموسعة وتنشئ مستند MS Word.

طباعة جميع خصائص العمود (مع علاقات المفاتيح الخارجية) تعمل خارج الصندوق. لمزيد من الأوصاف في كل حقل ، يتعين عليك إعداد خصائص موسعة لتلك الأعمدة في SQL Server Management Studio.

إنه ليس مجانيًا ولكن بأسعار معقولة جدًا. إذا كنت بحاجة فقط إلى إنشاء وثائق لقاعدة بيانات "لا تعمل" ، فهذا يعني أنه قد انتهى إلى حد ما من استخدام الإصدار التجريبي المجاني.

موقع الأداة

7
Kurresh

نستخدم Dataedo لإنشاء قاموس البيانات ، وتوثيق الإجراءات والوظائف المخزنة. نقوم بلصق ERDs التي تم إنشاؤها في Visio. يتم تخزين جميع الوثائق في مستودع البيانات الوصفية Dataedo (نص منسق) ونقوم بتصديره إلى HTML للاستخدام الداخلي أو التصدير إلى PDF للمستند المطبوع.

نحن نعين كل كائن لوحدة ونعين كل وحدة لشخص. يأتي Dataedo مع الإبلاغ عن حالة الوثائق حتى نتمكن من معرفة ما إذا كان هناك عمود أو جدول جديد يجب توثيقه.

5
Ryszard Bocian

يمكنك استخدام -- عادي - تعليقات مسبوقة ببادئة في ملف .sql.

تشمل الفوائد أن الوثائق مع رمز مخطط قاعدة البيانات ويمكنك بسهولة الالتزام به إلى نظام التحكم في الإصدار مثل 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)
);
2
Fred

مخططات ERD (مخططات قاعدة البيانات) كانت دائمًا الأكثر فائدة لفريقي.

ولكن هناك قاعدة لكتابة " Decription " في خصائص لكل جدول والعمود الذي نقوم بإنشائه.

ثم نستخدم اسم البرنامج هو Enterprise Architect لتوثيق Tables مع كل Indexes، Foreign Keys و Columns مع Type و الوصف .

enter image description here

1
El.Hum