¿Cómo documenta la estructura de su base de datos?

Question

Muchos sistemas de bases de datos no permiten comentarios o descripciones de tablas y campos, entonces, ¿cómo se puede documentar el propósito de una tabla/campo aparte de lo obvio de tener buenas convenciones de nomenclatura?

(Supongamos por ahora que "excelentes" nombres de tabla y campo no son suficientes para documentar el pleno significado de cada mesa, el campo y las relaciones en la base de datos.)

Sé que muchas personas usan diagramas UML para visualizar la base de datos, pero rara vez tengo — si alguna vez — he visto un diagrama UML que incluye comentarios de campo. Sin embargo, tengo una buena experiencia con el uso de comentarios dentro de los archivos .sql. La desventaja de este enfoque es que requiere que los archivos .sql se mantengan actualizados manualmente a medida que la estructura de la base de datos cambia con el tiempo —, pero si lo hace, también puede tenerlo bajo control de versión.

Algunas otras técnicas que he visto son documentos separados que describen la estructura y las relaciones de la base de datos y los comentarios mantenidos manualmente dentro del código ORM u otro código de mapeo de bases de datos.

¿Cómo ha resuelto este problema en el pasado? ¿Qué métodos existen y cuáles son los diversos pros y contras asociados con ellos? ¿Cómo te gustaría que esto se resuelva en "un mundo perfecto"?

actualización

Como otros han señalado, la mayoría de los motores SQL populares sí permiten a los comentarios, que es grande. Por extraño que parezca, la gente no parece estar usando estas características mucho. Al menos no en los proyectos en los que he estado involucrado en el pasado.

Answer 1

MySQL allows comentarios sobre tablas y filas. PostgreSQL does también. De otras respuestas, Oracle y MSSQL también tienen comentarios.

Para mí, una combinación de diagrama UML para un repaso rápido sobre nombres de campo, tipos y restricciones, y un documento externo (TeX, pero podría ser cualquier formato) con descripción extendida de todo lo relacionado con bases de datos - valores especiales, comentarios de campo, notas de acceso, lo que sea - funciona mejor.

Answer 2

Como usamos Rational Software Architect, usamos sus funciones de descubrimiento de datos para documentar nuestras bases de datos y luego anotarlas desde allí.

Answer 3

SQL Server tiene propiedades extendidas que pueden encargarse de esto.

En este artículo se describe cómo hacer configurarlas en SQL Sever http://www.developer.com/db/article.php/3677766

MSDN Reference

Puede ser utilizado en conjunción con RedGate SQL Doc para crear un diccionario de datos agradable.

Answer 4

En un momento escribí un analizador SQL básico que analizaría las sentencias CREATE TABLE y eliminaría los comentarios formateados especialmente. Estos fueron luego procesados ​​en la fuente LaTeX y se procesaron en PDF. Esto fue inspirado por Javadoc y se utilizó para crear la documentación para This product. Posteriormente, se creó una función de diccionario de datos en el administrador de depósito y se utilizó una versión modificada del generador LaTeX para procesar el diccionario de datos del administrador de depósito.

En otro proyecto utilicé Visio: la versión que viene con Visual Studio Enterprise Architect reenviará la ingeniería de una base de datos. El SQL así generado tenía los comentarios de tabla y columna representados en cadenas de comentarios que eran bastante sencillos de analizar. La herramienta que escribí generó archivos MIF que se incluyeron en un documento de especificaciones creado con FrameMaker.

Si tiene una herramienta de depósito como Powerdesigner, puede mantener modelos de datos en ella y obtener informes de repositorio que incluyen la documentación que ha ingresado.Si necesita una integración más profunda de su diccionario de datos con especificaciones funcionales (bastante útil para los sistemas de almacenamiento de datos donde el ETL es complejo e implica un cálculo significativo de los valores derivados) puede extraer los metadatos y escribir una utilidad para generar algo que integre los datos diccionario en un documento de especificación. Esto también permite referencias cruzadas entre los elementos del diccionario de datos y otros documentos de especificación y la generación de índices que cubren las definiciones del diccionario de datos y la documentación relacionada, como una especificación de cómo algo se calcula con ejemplos.

Answer 5

Hemos escrito un documento de palabra que enumera las tablas, los campos y todo lo que hace. Esto está respaldado por un diagrama que muestra cómo todo se vincula/se relaciona entre sí. Es un documento bastante simple, solo una carga de tablas con Nombre de campo> Tipo de datos> Propósito

Answer 6

Estoy usando Firebird que tiene campo de descripción para todos los objetos del sistema (tablas, columnas, vistas, procedimientos y parámetros, activadores, etc.) Es agradable porque puedes compartirlo fácilmente con otros (los documentos van con la base de datos, no por separado) y nunca lo pierdes.

Most admin. las herramientas para Firebird le permiten editar estas descripciones y hay algunas herramientas especializadas (como IBDesc, por ejemplo) que crean buenos informes HTML o PDF que puede imprimir (para algunas o todas las tablas) fácilmente.

Answer 7

En Oracle puede comentar tablas y las almacena en el diccionario de datos.

Sin embargo, almaceno todos mis comentarios de tabla, columna, índice en una versión muy antigua de ERWin. Es la fuente principal de la verdad y genera el DDL para crear tablas, etc. A partir de ahí, puedo extraerlo en un documento de Word o PDF.

Answer 8

Es un enfoque realmente simplista, pero utilizo un par de páginas wiki: una con el mysqldump de la base de datos y otra escrita en un formato ligeramente más similar al inglés.

Para los proyectos en los que he trabajado, eso ha sido suficiente (a través del nivel de docenas de tablas). No sé qué tan bien podría escalar a proyectos más grandes (por ejemplo, en cientos de tablas), pero hasta ahora ha sido bueno.

Answer 9

Comenta mis bases de datos mientras comento mis programas. Al escribir buenos (espero) comentarios en el código fuente (el archivo SQL que contiene las instrucciones DDL).

Usar el COMENTARIO de SQL es otra posibilidad. Lo bueno de ellos es que siempre están con sus objetos, están respaldados con ellos, etc. Lo malo es que son más limitados (por ejemplo, en longitud).

Answer 10

Uso los comentarios adjuntos a tablas y columnas. SchemaSpy es una gran herramienta para generar archivos de documentación html fuera de su esquema, incluidos los comentarios.

Answer 11

Tarde una, pero espero sea de utilidad ... Aquí es un proceso que usamos en el desarrollo de la base de datos relativamente grande (alrededor de 100 mesas y alrededor de 350 objetos en total) se requieren

• los desarrolladores utilizar las propiedades extendidas para añadir detalles a todos los objetos
• Los administradores rechazaron cualquier DDL que no tuviera propiedades extendidas
• Se utilizó una herramienta de terceros para generar automáticamente documentación visual mediante la interfaz de línea de comandos todos los días. Usamos ApexSQL Doc y funcionó bien, pero también utilicé SQL Doc de Red Gate en otra compañía.

Este proceso aseguró que tenemos todos los objetos documentados y documentados al día.

Lo difícil, aunque estaba recibiendo a los desarrolladores escribir buenos comentarios consistentemente;)

Answer 12

me he vuelto recientemente a escribir documentación de reducción del precio, lo que incluye la vinculación de mesa individual .sql archivos (donde las mesas y los campos son de esperar intuitivamente nombre tenga muchos comentarios).

guardo la tabla individual del esquema de control de versiones, con el siguiente comando:

mysqldump --no-data --tab=./tables dbname

El esquema para una sola tabla le permite ver los comentarios, índices, claves únicas, etc por lo que es bastante auto explicativo (bueno, esa es la idea al menos).

La documentación del recorte maestro tiene hipervínculos como la tabla de usuario salpicada, por lo que el lector puede acceder fácilmente a las diferentes tablas.