Como você documenta seus bancos de dados?

Acho que a maioria dos meus clientes não está documentando seus bancos de dados e acho isso bastante assustador. Para introduzir melhores práticas, gostaria de saber quais ferramentas / processos as pessoas estão usando.

• Como você documenta seu banco de dados? (Servidor SQL)
• Qual ferramenta você usa?
• Documentação Formato de armazenamento para esquema de banco de dados / metadados?
  • Documentos do Word
  • planilha do Excel
  • Texto simples
• Processo ou políticas de documentação?

Não estou falando sobre engenharia reversa / documentar um banco de dados existente, mas principalmente sobre as práticas recomendadas da documentação enquanto você desenvolve seu sistema / banco de dados.

Uso propriedades estendidas, pois são muito flexíveis. A maioria das ferramentas de documentação padrão pode ser desativada MS_Descriptione, em seguida, você pode usar as suas com ferramentas personalizadas.

Veja esta apresentação: # 41-Pegue uma alavanca e escolha qualquer tartaruga: levantando com metadados

E este código: http://code.google.com/p/caderoux/wiki/LeversAndTurtles

Do Microsoft Visio Pro (até Visio 2010) pode fazer engenharia reversa de um banco de dados como pode do CA ERwin . O Visio é a opção mais barata, mas o ERwin é a opção mais detalhada e completa. Propriedades ampliadas são boas, se as pessoas se preocupam em examiná-las. Você também pode usar algo como o SQL Doc do Red Gate para gerar documentação em formato HTML.

Acho que as convenções de nomenclatura e a configuração adequada de chaves estrangeiras levam a um banco de dados quase auto-documentado. Você ainda deve ter alguns documentos externos para entender melhor o objetivo.

Experimente o SchemaSpy: http://schemaspy.sourceforge.net/

Para o SQL Server, estou usando propriedades estendidas.

Com o seguinte script do PowerShell, posso gerar os scripts Criar tabela para uma única tabela ou para todas as tabelas no esquema dbo.

O script contém um Create tablecomando, chaves primárias e índices. Chaves estrangeiras são adicionadas como comentários. As propriedades estendidas das tabelas e colunas da tabela são adicionadas como comentários. Sim, as propriedades de várias linhas são suportadas.

O script está ajustado no meu estilo de codificação pessoal.

• sem agrupamentos individuais para colunas únicas.

• atualmente, requer autenticação do servidor sql.

Aqui está o código completo para transformar as propriedades estendidas em um bom documento ASCII antigo (BTW, é válido o sql para recriar suas tabelas):

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

Você pode criar um script do esquema dbo completo de um determinado banco de dados

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

Ou filtre para uma única tabela

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

Dê uma olhada no SchemaCrawler - é minha ferramenta gratuita de linha de comando que eu projetei para fazer o que você está procurando. SchemaCrawler produz um arquivo de texto com todos os objetos de esquema do banco de dados. Essa saída de texto foi projetada para ser legível por humanos, além de ser diferente da saída semelhante de outro servidor.

Na prática, o que descobri é que a saída de um arquivo de texto do esquema do banco de dados é útil, quando realizada como parte da compilação. Dessa forma, você pode verificar o arquivo de texto no seu sistema de controle de código-fonte e ter um histórico de versão de como seu esquema evoluiu ao longo do tempo. O SchemaCrawler foi projetado para automatizar isso também, na linha de comando.

Se alguma vez for escrita, a documentação consiste em um documento do Word. Alguns diagramas de relacionamento serão incluídos. Lista as tabelas e uma breve descrição do que cada tabela contém e como ela se relaciona com outras tabelas. Um capítulo da documentação inclui as configurações de segurança: de que permissões o "usuário" que o aplicativo precisa?

Geralmente, nas empresas em que trabalhei, a documentação do banco de dados só é escrita quando o cliente é quem realiza auditorias, o que tende a limitar seu uso a clientes financeiros e governamentais.

Isenção de responsabilidade: muitos desenvolvedores adotam a atitude de que o código é a documentação , e eu também sou culpado.

Eu uso propriedades estendidas e Red Gates SQL Doc. Funciona muito bem!

Engraçado, eu queria saber como outras pessoas estão fazendo isso também ..

Ao desenvolver meu primeiro grande projeto de banco de dados, descobri que o Microsoft SQL Server Management Studio 10.0.1600.22 suporta diagramas de banco de dados que você pode exportar para um documento do Word ou outro software de documentação, onde você pode adicionar os detalhes da documentação que desejar. Apenas expanda o banco de dados ao qual você se conectou no SQL Management Studio e clique com o botão direito do mouse em "diagramas de banco de dados" no explorador de objetos e selecione "Novo diagrama de banco de dados" para gerar um diagrama interativo que mostrará todos os relacionamentos entre as diferentes tabelas. Você pode até especificar quais tabelas deseja incluir nos diagramas, para que a imagem não fique desorganizada se você estiver apenas tentando documentá-la peça por peça. Exporte a imagem para qualquer outro software de edição e comente o quanto quiser.

Eu também recomendo muitos / comentários / no script que gera seu banco de dados.

Geralmente, é muito trabalho escrever para que serve, mas é uma boa idéia a longo prazo, como quando você ou alguma outra alma pobre volta para atualizar sua criação alguns anos depois! :)

Defino a propriedade estendida MS_description para todos os objetos e depois documento o banco de dados inteiro usando o ApexSQL Doc . Eu costumava criar documentos HTML anteriormente, mas ultimamente prefiro PDF

Eu uso ferramentas de modelagem de dados porque elas me permitem documentar informações importantes sobre o banco de dados, além daquilo que "cabe" em um banco de dados. Meta dados, como preocupações com privacidade / segurança / sensibilidade, administração, governança etc.

Isso pode ir além do que alguns precisam para documentar um banco de dados, mas essas coisas são importantes para os negócios e para ajudá-los a gerenciar seus dados.

As ferramentas formais também me ajudam no gerenciamento de dados armazenados em mais de um banco de dados / instância / servidor. Isso nunca foi tão verdadeiro quanto em nosso mundo de aplicativos empacotados.

Para documentar o servidor sql, recomendo o lançamento recente:

Documentação do SQL Server e Windows usando o Windows PowerShell escrito por Kendal Van Dyke

Breve descrição no link:

O SQL Power Doc é uma coleção de scripts e módulos do Windows PowerShell que descobrem, documentam e diagnosticam instâncias do SQL Server e suas configurações subjacentes de SO e máquina do Windows. O SQL Power Doc funciona com todas as versões do SQL Server do SQL Server 2000 a 2012 e todas as versões do Windows Server e Windows Operating Systems do Windows 2000 e Windows XP ao Windows Server 2012 e Windows 8. O SQL Power Doc também é capaz de documentar Bancos de dados SQL do Windows Azure.

Criador de dicionário de banco de dados

é uma ferramenta de documentação de banco de dados de código aberto com GUI decente e opções de exportação / importação. Ele usa propriedades estendidas para armazenar a documentação. Também gera descrições automáticas para colunas de chave primária e colunas de chave estrangeira.

Na verdade, Propriedades Estendidas (MS_Description) é o caminho a percorrer. Ter essas descrições prontamente disponíveis como parte dos metadados pode ser utilizado não apenas pelos geradores de documentos, mas também (espero um dia) por ferramentas que fornecem "intellisense", por exemplo, o excelente Assistente SQL da Softtree http://www.softtreetech.com/ isql.htm (da última vez que verifiquei que não) ou construído no Intellisense do SQL Sever Management Studio (desde sql2008)

Também acredito que deve ser fácil para os desenvolvedores e DBAs adicionarem essas notas, porque, como Tangurena e Nick Chammas apontaram corretamente - os desenvolvedores relutam em manter os documentos atualizados e odeiam trabalhos duplicados - o que é justo o suficiente, especialmente para quem foi ensinado otimizar as coisas durante toda a sua vida profissional. Portanto, a menos que seja realmente fácil atualizar documentos em um local próximo ao código-fonte - isso não vai funcionar. Em algum momento, pesquisei na web e não encontrei uma solução para isso, então escrevi o LiveDoco (não livre, desculpe) na tentativa de facilitar. Mais informações aqui, se estiver interessado: http://www.livedoco.com/why-livedoco

Você também pode dar uma olhada no wsSqlSrvDoc . É uma ferramenta pequena e agradável que funciona com propriedades estendidas do SQL Server e cria um documento do MS Word.

A impressão de todas as propriedades da coluna (com relações de chave estrangeira) funciona imediatamente. Para obter mais descrições sobre cada campo, você deve configurar propriedades estendidas dessas colunas no SQL Server Management Studio.

Não é gratuito, mas é bastante acessível. Se você apenas precisar criar uma documentação para um banco de dados "sem trabalho em andamento" que esteja mais ou menos concluído do que seria suficiente para usar a avaliação gratuita.

Site da Ferramenta

Usamos o Dataedo para criar dicionário de dados, documentar procedimentos e funções armazenados. Colamos ERDs criados no Visio. Toda a documentação é armazenada no repositório de metadados Dataedo (texto formatado) e a exportamos para HTML para uso interno ou para PDF para documentos impressos.

Atribuímos cada objeto a um módulo e atribuímos cada módulo a uma pessoa. O Dataedo vem com o relatório de status da documentação, para que possamos saber se há uma nova coluna ou tabela que precisa ser documentada.

Você pode usar --comentários com prefixos regulares no .sqlarquivo.

Os benefícios incluem que a documentação está com o código do esquema do banco de dados e você pode facilmente confirmá-la em um sistema de controle de versão como o Git .

Exemplo:

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

Talvez você possa usar XML também.

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

Você também pode usar alguma sintaxe com semelhança com 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)
);

Ou você pode usar a sintaxe do 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)
);

Os diagramas de ERD (diagramas de banco de dados) sempre foram os mais úteis para minha equipe

Mas existe uma regra para escrever " Decription " nas propriedades de cada tabela e coluna que criamos.

Em seguida, usamos um nome de software é Enterprise Architect para documentar Tablescom todos Indexes, Foreign KeysE Columnscom Typee Descrição .

Para o MySQL em particular, sempre usamos o MySQL Workbench . Criamos nossos designs de banco de dados no designer e depois exportamos como um script SQL executável. A aplicação de todas as alterações no design e a execução do script gerado garantem que o design e o banco de dados real estejam perfeitamente sincronizados entre si e que a documentação não fique desatualizada com tanta facilidade.