¿Cómo documentas tus bases de datos?

Me parece que la mayoría de mis clientes no están documentando sus bases de datos y eso me da bastante miedo. Para presentar una mejor práctica, me gustaría saber qué herramientas / procesos están utilizando las personas.

• ¿Cómo documentas tu base de datos? (Servidor SQL)
• ¿Qué herramienta usas?
• ¿Formato de almacenamiento de documentación para esquema de base de datos / metadatos?
  • Documentos de Word
  • hoja de cálculo de Excel
  • Texto sin formato
• Proceso de documentación o políticas?

No estoy hablando de ingeniería inversa / documentar una base de datos existente, sino principalmente de las mejores prácticas de documentación mientras desarrolla su sistema / base de datos.

He estado usando propiedades extendidas ya que son muy flexibles. La mayoría de las herramientas de documentación estándar se pueden eliminar MS_Description, y luego puede usar las suyas con herramientas personalizadas.

Vea esta presentación: # 41-Obtenga una palanca y elija cualquier tortuga: levantando con metadatos

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

De Microsoft Visio Pro (hasta Visio 2010) se puede aplicar ingeniería inversa a una base de datos al igual que de CA ERwin . Visio es la opción más barata, pero ERwin es la opción más detallada y completa. Las propiedades extendidas son agradables, si las personas se molestan en mirarlas. También podría usar algo como el SQL Doc de Red Gate para generar documentación en formato HTML.

Encuentro que las convenciones de nomenclatura y la configuración adecuada de claves externas conducen a una base de datos casi autodocumentada. Aún debe tener algunos documentos externos para una mejor comprensión del propósito.

Pruebe SchemaSpy: http://schemaspy.sourceforge.net/

Para SQL Server estoy usando propiedades extendidas.

Con la siguiente secuencia de comandos de PowerShell puedo generar una secuencia de comandos Crear tabla para una sola tabla o para todas las tablas en el esquema dbo.

El script contiene un Create tablecomando, claves primarias e índices. Las claves externas se agregan como comentarios. Las propiedades extendidas de las tablas y las columnas de la tabla se agregan como comentarios. Sí, se admiten propiedades de varias líneas.

El guión está ajustado a mi estilo de codificación personal.

• No hay colaciones individuales para columnas individuales.

• actualmente requiere autenticación de servidor SQL.

Aquí está el código completo para convertir las propiedades extendidas en un buen documento ASCII antiguo (por cierto, es válido sql para recrear sus tablas):

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

Puede escribir el esquema de dbo completo de una base de datos determinada

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

O filtrar por una sola mesa

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

Eche un vistazo a SchemaCrawler : es mi herramienta gratuita de línea de comandos que diseñé para hacer lo que está buscando. SchemaCrawler produce un archivo de texto con todos los objetos de esquema de la base de datos. Esta salida de texto está diseñada para ser legible por humanos, así como diferible frente a una salida similar de otro servidor.

En la práctica, lo que he encontrado es que generar un archivo de texto del esquema de la base de datos es útil cuando se hace como parte de la compilación. De esta manera, puede verificar el archivo de texto en su sistema de control de código fuente y tener un historial de versiones de cómo ha evolucionado su esquema con el tiempo. SchemaCrawler está diseñado para automatizar esto también, desde la línea de comandos.

Si alguna vez se escribe, la documentación consta de un documento de Word. Se incluirán un par de diagramas de relación. Listas de las tablas y una breve descripción de lo que contiene cada tabla y cómo se relaciona con otras tablas. Un capítulo de la documentación incluye la configuración de seguridad: ¿qué permisos necesita el "usuario" que necesita la aplicación?

En general, en las empresas para las que he trabajado, la documentación de la base de datos solo se escribe cuando el cliente es el que realiza las auditorías, lo que tiende a limitar su uso a clientes financieros y gubernamentales.

Descargo de responsabilidad: demasiados desarrolladores toman la actitud de que el código es la documentación , y yo también he sido culpable.

Utilizo propiedades extendidas y Red Gates SQL Doc. Funciona muy bien!

Es curioso, me preguntaba cómo otras personas están haciendo esto también ...

Mientras desarrollaba mi primer gran proyecto de base de datos, descubrí que Microsoft SQL Server Management Studio 10.0.1600.22 admite diagramas de base de datos que puede exportar a un documento de Word u otro software de documentación donde puede agregar tantos detalles de documentación como desee. Simplemente expanda la base de datos a la que se conectó en SQL Management Studio y haga clic derecho en "diagramas de base de datos" en el explorador de objetos y seleccione "Nuevo diagrama de base de datos" para generar un diagrama interactivo que mostrará todas las relaciones entre las diferentes tablas. Incluso puede especificar qué tablas desea incluir en los diagramas, de modo que la imagen no se vea de manera desordenada si solo está tratando de documentarla pieza por pieza. Exporte la imagen a cualquier otro software de edición y comente todo lo que quiera.

También recomiendo muchos / comentarios / en el script que genera su base de datos.

En general, es mucho trabajo escribir para qué sirve, pero es una buena idea a largo plazo, como cuando tú o alguna otra pobre alma regresa para actualizar tu creación un par de años después. :)

Configuré la propiedad extendida MS_description para todos los objetos y luego documenté toda la base de datos usando ApexSQL Doc . Solía ​​crear documentos HTML antes, pero últimamente prefiero PDF

Utilizo herramientas de modelado de datos porque me permiten documentar información importante sobre la base de datos además de lo que "cabe" en una base de datos. Metadatos como preocupaciones de privacidad / seguridad / sensibilidad, administración, gobernanza, etc.

Eso puede ir más allá de lo que algunos necesitan para documentar una base de datos, pero esas cosas son importantes para el negocio y ayudarlos a administrar sus datos.

Las herramientas formales también me ayudan a administrar los datos almacenados en más de una base de datos / instancia / servidor. Esto nunca ha sido más cierto que en nuestro mundo de aplicaciones empaquetadas.

Para documentar el servidor sql, recomiendo lanzar recientemente:

Documentación de SQL Server y Windows con Windows PowerShell escrita por Kendal Van Dyke

Breve descripción del enlace:

SQL Power Doc es una colección de scripts y módulos de Windows PowerShell que descubren, documentan y diagnostican instancias de SQL Server y sus configuraciones subyacentes del sistema operativo Windows y de la máquina. SQL Power Doc funciona con todas las versiones de SQL Server desde SQL Server 2000 hasta 2012, y todas las versiones de Windows Server y sistemas operativos Windows de consumo desde Windows 2000 y Windows XP hasta Windows Server 2012 y Windows 8. SQL Power Doc también es capaz de documentar Bases de datos SQL de Windows Azure.

DB Dictionary Creator

es una herramienta de documentación de base de datos de código abierto con GUI decente y opciones de exportación / importación. Utiliza propiedades extendidas para almacenar la documentación. También generará descripciones automáticas para columnas de clave principal y columnas de clave externa.

De hecho, Extended Properties (MS_Description) es el camino a seguir. Tener estas descripciones fácilmente disponibles como parte de los metadatos podría ser utilizado no solo por los generadores de documentos, sino también (con suerte algún día) por herramientas que proporcionan "inteligencia", por ejemplo, el excelente Asistente SQL de Softtree http://www.softtreetech.com/ isql.htm (la última vez que verifiqué que no lo hicieron) o integrado en Intellisense de SQL Sever Management Studio (desde sql2008)

También creo que debería ser fácil para los desarrolladores y DBA agregar estas notas porque, como Tangurena y Nick Chammas señalaron correctamente, los desarrolladores son muy reacios a mantener actualizados los documentos y odian el trabajo duplicado, lo cual es bastante justo, especialmente para una persona a la que se le enseñó para optimizar las cosas durante toda su vida profesional. Entonces, a menos que sea realmente fácil actualizar documentos en un lugar cercano al código fuente, esto no funcionará. En algún momento busqué en la web y no encontré una solución para esto, así que escribí LiveDoco (no gratis, lo siento) en un intento de facilitarlo. Más información aquí si está interesado: http://www.livedoco.com/why-livedoco

También puede echar un vistazo a wsSqlSrvDoc . Es una pequeña herramienta que funciona con las propiedades extendidas de SQL Server y crea un documento de MS Word.

La impresión de todas las propiedades de la columna (con relaciones de clave externa) funciona de forma inmediata. Para obtener más descripciones sobre cada campo, debe configurar las propiedades extendidas de esas columnas en SQL Server Management Studio.

No es gratis pero es bastante asequible. Si solo necesita crear una documentación para una base de datos "no en progreso" que está más o menos terminada de lo que sería suficiente para usar la versión de prueba gratuita.

Sitio web de herramientas

Usamos Dataedo para crear un diccionario de datos, documentar procedimientos almacenados y funciones. Pegamos los ERD creados en Visio. Toda la documentación se almacena en el repositorio de metadatos Dataedo (texto formateado) y la exportamos a HTML para uso interno o exportamos a PDF para documentos impresos.

Asignamos cada objeto a un módulo y asignamos cada módulo a una persona. Dataedo viene con informes de estado de la documentación para que podamos saber si hay una nueva columna o tabla que deba documentarse.

Puede usar --comentarios con prefijos regulares en el .sqlarchivo.

Los beneficios incluyen que la documentación es con el código para el esquema de la base de datos y puede enviarla fácilmente a un sistema de control de versiones como Git .

Ejemplo:

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

Quizás también podrías usar 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)
);

También podría usar una sintaxis similar a 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)
);

O podría usar la sintaxis de 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)
);

Los diagramas ERD (Diagramas de base de datos) siempre fueron los más útiles para mi equipo

Pero hay una regla para escribir " Descripción " en las Propiedades de cada tabla y columna que creamos.

Luego usamos un nombre de software es Enterprise Architect para documentar Tablescon todo Indexes, Foreign KeysY Columnscon Typey Descripción .

Para MySQL en particular, siempre usamos MySQL Workbench . Creamos nuestros diseños de bases de datos en el diseñador, luego los exportamos como un script SQL ejecutable. La aplicación de todos los cambios en el diseño y luego la ejecución del script generado garantiza que el diseño y la base de datos real estén perfectamente sincronizados entre sí, y que la documentación no quedará desactualizada tan fácilmente.