Cómo automatizar la documentación de una base de datos SQL

¿No sería un gran truco si usted pudiera documentar una base de datos con un doble clic? Con este artículo, mostraremos algunos pasos simples para permitirle crear un archivo de script que correrá un proceso que genera documentación para su base de datos. Después de eso usted puede simplemente ejecutarlo para repetir el proceso con sólo dos clics o incluso configurar un trabajo para correrlo automáticamente cada noche. En este artículo usted aprenderá cómo crear este proceso automatizado de documentación de bases de datos usando ApexSQL Doc.

ApexSQL Doc es una herramienta de documentación de bases de datos SQL que documenta bases de datos SQL Server, paquetes SSIS y cubos SSAS.

ApexSQL Doc genera documentación en formatos CHM, HTML, Word y PDF y usted puede personalizar completamente con diferentes estilos, texto personalizado y gráficos.

En este ejemplo crearemos documentación de una base de datos primero usando la aplicación a través de la Interfaz Gráfica y luego crearemos una solución automatizada vía la Interfaz de Línea de Comandos.

Descripción

1. Para configurar el proceso de documentación de la base de datos SQL, haga clic en el botón New Project y conéctese a SQL Server:

   

   Haga clic en la opción seleccionada arriba y el diálogo Add SQL Server aparecerá. Elija el servidor y haga clic en Connect.

2. Cuando usted haya establecido una conexión con SQL Server verá una lista de servidores SQl Server en la sección SQL Servers, y todas las bases de datos que están conectadas al servidor seleccionado serán visibles en la sección Databases en la derecha.

   

   Nota:
   
   Usted debe seleccionar al menos una base de datos si desea continuar con el proceso de configuración de la documentación. En este ejemplo generaremos la documentación para la base de datos Test. Esta base de datos será documentada en un archivo de ayuda HTML por defectos, pero eso puede cambiarse a HTML, Word y PDF.

3. Configure su base de datos con las opciones deseadas. Los objetos pueden ser filtrados usando la opción Object filter Usted puede establecer configuraciones de documentación adicionales haciendo clic en la pestaña Database options En la pestaña Database objects usted puede incluir/excluir objetos para la documentación. Usted también puede incluir la documentación acerca de SQL Server.

   

   Configure la localización de los resultados, donde usted desea que se genere la documentación. Esto puede ser hecho haciendo clic en el botón Options en la pestaña Home.

   

   

   Ingrese la localización donde usted desea generar la documentación o use el botón Browse. Cuando esto se complete, haga clic en el botón OK

   Para configurar el formato de la documentación haga clic en el botón Defaults

   

   En el menú Project defaults haga clic en la pestaña File format seleccione el formato deseado de salida y haga clic en OK.

   

   Si desea añadir una fecha a su documentación, puede hacerlo fácilmente seleccionando la pestaña Naming en el Project Defaults y haciendo clic en el botón Naming en el Project Defaults y haciendo clic en el botón Date en la sección Filename. Usted puede también añadir un Nombre de Fuente y un Nombre de Base de datos a su nombre de archivo.

   

4. Cuando haya establecido todas las opciones es tiempo de grabar el proyecto. Haga clic en el botón Save as debajo del botón Save.

   

5. Después de configurar la selección y opciones de las bases de datos, el proceso de documentación puede ser iniciado haciendo clic en el botón Generate desde la pestaña Home tab.

   

   Cuando el proceso está completo usted obtendrá la documentación de la base de datos en el formato deseado.

Usando la interfaz de línea de comandos

El siguiente paso es automatizar el proceso. Esto puede ser hecho creando un archivo .BAT usando un script de Windows Shell contra la interfaz de línea de comando de ApexSQL Doc.

Si usted no está seguro de cómo crear un archivo ejecutable que automatizará su proceso de documentación, siga el ejemplo a continuación.

1. Primero, cree un nuevo Documento de Texto e incluya estas líneas en su archivo:

   @echo off
   «ApexSQLDoc.com»
   /pr:Project.axdp	#loading a project file
   /od:ApexSQLDoc	#specifies the output directory
   /of:html	#specifies the output type
   /f	# force switch, overwrites existing files
   /v	#verbose console output
   echo «error code: » %errorlevel%
   pause

   Definición:
   Primero ingrese la ruta del archivo ApexSQLDoc.com, después de eso defina la ruta del archivo del proyecto grabado con la opción /pr.

   Con la opción /od usted debe definir el directorio de salida.

   La opción /of especifica el formato del archivo de salida. Si usted no especifica la opción /of, la documentación será generada en formato HTML Compilado (.chm) por defecto.

   La opción /force (o /f) sobrescribe archivos existentes con el mismo nombre. Si la opción /forcé no es provista, cualquier intento de sobrescribir un archivo ya existente causará que se muestre un aviso.

   La opción /vervose (o /v) muestra mensajes, avisos, etc., relevantes durante el proceso. Con esta opción especificada, la aplicación imprime la información completa de operaciones en la consola.

2. Cuando esto esté hecho, grabe el archivo añadiendo la extensión .bat después del nombre del archivo y ejecute el archivo creado. Después de ejecutar el archivo .BAT previamente creado, usted obtendrá un resultado como este:
   
   Creating the table of contents…
   Creating the index file …
   Creating the documentation file…
   The documentation has been written to C:\User\Documents\ApexSQL\ApexSQLDoc\(local).TestDB_03_25_2016.chm
   «error code: » 0
   Press any key to continue…
   

Si todo está bien, usted debería obtener un código de error 0. Ahora que usted tiene un archivo que crea documentación cuando usted simplemente lo ejecuta y obtiene una documentación completa.

Si usted obtiene un error y no puede documentar su archivo, revise estos códigos de error para ver dónde ocurrió el problema.

Error General

Código de error 1 – General error

Not valid/accessible Database(s) are specified for Server (local).
«error code: » 1
Press any key to continue…

Código de error 2 – Combinación no válida de opciones. Usted obtendrá este error si:

La opción requerida no se encuentra, las opciones han sido duplicadas u opciones incompatibles han sido usadas (por ejemplo, una opción no existente es escrita).

Switch ‘prx’ is not recognized.
«error code: » 2
Press any key to continue…

Código de error 3 – Formato no válido de salida. Este código es mostrado si un formato de salida no válido fue provisto.

Incorrect format of /of ( /output_format ) switch.
Requested value ‘htmm’ was not found.
«error code: » 3
Press any key to continue…

Código de error 4 – Error IO. Usted obtendrá este error si usted ya tiene un archivo con el mismo nombre. En este caso usted debe usar una opción /f para sobrescribir el archivo existente.

The project file not found Project.axdp
«error code: » 4
Press any key to continue…

Ó,

The directory (local).Test already exists. Specify the /force switch to overwrite it
«error code: » 4
Press any key to continue…

Código de error 5 – Permisos insuficientes. Este código es mostrado si el usuario no tiene los permisos que son requeridos para esta acción.

Traductor: Daniel Calbimonte