21

Quando escrevo códigos em R, a maneira correta de documentar é no próprio código, em forma de comentários iniciados com uma marcação especial #'.

#' Add together two numbers.
#' 
#' @param x A number.
#' @param y A number.
#' @return The sum of \code{x} and \code{y}.
#' @examples
#' add(1, 1)
#' add(10, 1)
add <- function(x, y) {
  x + y
}

Depois existe uma ferramenta chamada roxygen que transforma esses comentários do código em um arquivo de documentação.

inserir a descrição da imagem aqui

Esse formato, mantém a documentação próxima do código, deixando muito mais fáceis as suas atualizações. Além disso, é possível produzir documentos padronizados de documentação.

Minha pergunta é: Como fazer algo parecido com isso para o SQL (especificamente para SQL Server)?

2
  • Realmente essa é uma questão interessante. Eu não conheço nenhuma ferramenta parecida com a que você usa. Fiz algumas pesquisas há muito tempo sobre isso e não encontrei. Pensei em uma solução paliativa que seria usar markdown dentro do SQL. E salvar um código como .md e outro no formato que você precisa. Lhe atende? ------ Commented 22/12/2016 às 10:58
  • 1
    Já deve ter cruzado com este link mas aqui vai red-gate.com/products/sql-development/sql-doc
    – lazyFox
    Commented 22/12/2016 às 12:19

1 Resposta 1

10
+100

Essa pergunta "How do you document your databases?" do dba.stackexchange tem algumas respostas interessantes.

Algumas das respostas aconselham usar as ferramentas:

  • SchemaSpy: baseada em Java (requer Java 5 ou superior) que analisa os metadados de um esquema em um banco de dados e gera uma representação visual do que em um formato de navegador-exibível.
  • SchemaCrawler: produz um arquivo de texto com todos os objetos esquema de banco de dados.
  • ApexSQL: documenta os bancos de dados SQL Servers, cubos SSAS, relatórios SSRS e pacotes SSIS. Ele cria a documentação do banco de dados em uma variedade de formatos, incluindo a ajuda compilada (.CHM), HTML, PDF e MS Word. Além disso, o processo de documentação pode ser agendada e executar autônoma. Se escolher esse aconselho a ver essa parte da documentação.
  • SQL Power Doc: 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 do sistema operacional Windows.
  • Data Dictionary Creator: aplicativo que ajuda a documentar bancos de dados SQL Server. Ele armazena todas as informações em Propriedades estendidas, por isso é mais fácil manter a documentação em sincronia com o banco de dados como ele muda.

Essa resposta também parece uma boa solução, para o SQL Server ele usa as propriedade estendidas e um script do PowerShell, assim gera scripts de criação de tabela para uma única tabela ou para todas as tabelas no esquema dbo. Nesse script contém um Create table de comando, chaves primárias e índices. Chaves estrangeiras são adicionadas como comentários. As propriedades estendidas de tabelas e colunas de tabela são adicionadas como comentários. O script dele está ajustado ao estilo de codificação pessoal, sem colações individuais para colunas individuais e atualmente requer Sql Server Authentication.

Na resposta ele mostra o código completo para transformar as propriedades estendidas em um bom documento antigo ASCII (BTW é válido 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ê também pode fazer um script completo de um dado banco de dados:

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

Ou um filtro para uma única tabela:

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

Além dessas respostas da pergunta "How do you document your databases?" tem também o DB>doc, que é uma ferramenta para documentação gerando para banco de dados Microsoft SQL Server. Ela é uma aplicação de console, usado na linha de comando e controlado por vários switches. Para gerar documentação HTML do banco de dados com uma string de conexão dada:

Sqldbdoc "SERVER =. \ SqlExpress; TRUSTED_CONNECTION = yes; DATABASE = AdventureWorks" aw-doc.htm

Eu particularmente nunca usei nenhuma dessas ferramentas, quando precisei de uma documentação sobre o banco de dados usei Engenharia Reversa. Com o Power Designer, ele transforma as tabelas do banco de dados em um diagrama.


Essas são ferramentas para documentar o banco de dados, para documentar views, store procedures e funções, você pode definir um comentário com a tag Descripcion:

-- Descripcion: Deleta por nome de Cliente
CREATE PROCEDURE [dbo].[DeleteByName]
@Name nvarchar(255)
AS
BEGIN
SET NOCOUNT ON;
DELETE FROM CLIENT WHERE NAME = @Name
END
GO

Obs.: Nas views os comentários devem ter o CREATE/ALTER antes do GO.

CREATE VIEW [dbo].[VW_SELLER]
AS
SELECT  *
FROM CLIENT
INNER JOIN SELLER ON CLIENT.ID = SELLER.ID
-- Descripcion: Retorna a informação expandidas dos vendedores
GO

O script abaixo obtém a informação da documentação inserida no código. Ele percorre os objetos da base de dados (views, stores procedures, funções) e para cada objeto obtém o código fonte com sp_helptext. Com a documentação, mostra o nome do objeto e sua descrição.

-- ************************************************************************
-- * Obtém a descrição das tabelas, procedures, views e funções *
-- ************************************************************************
SET NOCOUNT ON

DECLARE @DESCRIPCION VARCHAR(4000)
CREATE TABLE #helptext
(
[Text] VARCHAR(4000) NULL
);

DECLARE ShowComentsAll CURSOR
FOR
SELECT sysusers.[name] + '.' + sysobjects.[name] AS FullName
FROM sysobjects
INNER JOIN sysusers ON sysobjects.uid = sysusers.uid
WHERE xtype in ('P', 'V', 'FN')
ORDER BY xtype, FullName

OPEN ShowComentsAll
DECLARE @name VARCHAR(250)

FETCH NEXT FROM ShowComentsAll INTO @name
WHILE @@fetch_status = 0
BEGIN

DELETE #helptext
SET @DESCRIPCION = NULL

INSERT INTO #helptext
exec sp_helptext @name

SELECT @DESCRIPCION = [text]
FROM #helptext
WHERE [text] LIKE '-- Descripcion:%'
IF (@DESCRIPCION IS NOT NULL)
BEGIN
PRINT @NAME
PRINT @DESCRIPCION
END

FETCH NEXT FROM ShowComentsAll INTO @name
END
CLOSE ShowComentsAll
DEALLOCATE ShowComentsAll
DROP TABLE #helptext

Resultado:

dbo.DeleteByName
-- Descripcion: Deleta por nome de Cliente
dbo.VW_SELLER
-- Descripcion: Retorna a informação expandidas dos vendedores
3
  • Nãos ei se estou correto, mas aparentemente documentar código SQL é diferente de documentar bancos de dados. Essas ferramentas que você citou parecem ser melhores para o segundo. Commented 26/12/2016 às 11:41
  • @DanielFalbel, você está correto, editei a resposta. Commented 26/12/2016 às 16:03
  • 1
    Essa ferramenta e muito boa para documentar bancos de dados, criei uma imagem docker para documentar todos os bancos de um servidor github.com/krismorte/database-diagrams
    – Krismorte
    Commented 16/07/2019 às 23:55

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .