Cómo documentar una base de datos

Question

(Nota:. Soy consciente de que está cerca de How do you document your database structure?, pero no creo que sea idéntico)

He empezado a trabajar en un lugar con una base de datos con literalmente cientos de mesas y vistas, todas con nombres crípticos con muy pocas vocales y sin documentación. Tampoco permiten cambios gratuitos al esquema de la base de datos, ni puedo tocar ninguna base de datos excepto la de prueba en mi propia máquina (que se destruye y se recrea de forma regular), por lo que no puedo agregar comentarios que puedan ayudar a nadie.

Intenté usar "Toad" para crear un diagrama ER, pero después de dejarlo funcionando durante 48 horas seguidas, todavía no había producido nada visible y necesitaba mi computadora de nuevo. Estuve hablando con otras contrataciones recientes y todos sugerimos que cada vez que averigüemos qué tabla en particular o qué significan algunas de sus columnas, deberíamos actualizarla en la wiki de desarrolladores.

Entonces, ¿cuál es una buena manera de hacer esto? ¿Solo enumera las tablas/vistas y sus columnas y las completa a medida que avanzamos? Las herramientas básicas que tengo a mi alcance son Toad, "SQL Developer" de Oracle, MS Office y Visio.

Answer 1

En mi experiencia, los diagramas ER (o UML) no son el artefacto más útil: con un gran número de tablas, los diagramas (especialmente los de ingeniería inversa) son a menudo un gran lío enrevesado del que nadie aprende nada.

Por mi dinero, una buena documentación de lectura humana (quizás complementada con diagramas de porciones más pequeñas del sistema) le dará el mayor rendimiento. Esto incluirá, para cada tabla:

• Descripciones de lo que significa la tabla y cómo se usa funcionalmente (en la interfaz de usuario, etc.)
• descripciones de lo que cada atributo significa que, si no es obvio
• Las explicaciones de las relaciones (claves foráneas) de esta tabla a otros, y viceversa
• Explicaciones de restricciones adicionales y/o desencadenantes
• explicación adicional de las principales vistas & procsos que tocan la mesa, si no están bien documentadas ya

Con todo lo anterior, no documentan por el bien de la documentación - documentación que reafirma la obvia solo se pone en el camino de la gente. En cambio, concéntrese en las cosas que lo confundieron al principio, y dedique unos minutos a escribir explicaciones realmente claras y concisas. Eso te ayudará a pensarlo bien, y va a masivamente ayudar a otros desarrolladores que se encuentran con estas tablas por primera vez.

Como han mencionado otros, hay una amplia variedad de herramientas para ayudarlo a manejar esto, como Enterprise Architect, Red Gate SQL Doc, y las herramientas incorporadas de varios proveedores. Pero mientras que el soporte de herramientas es útil (e incluso crítico, en bases de datos más grandes), haciendo el arduo trabajo de entendiendo y explicando el modelo conceptual de la base de datos es la verdadera victoria. Desde esa perspectiva, incluso puedes hacerlo en un archivo de texto (aunque hacerlo en formato wiki permitiría que varias personas colaboren para agregar esa documentación de forma incremental, de modo que cada vez que alguien descubra algo, lo pueda agregar al cuerpo en crecimiento). de la documentación al instante).

Answer 2

Dado que tiene el lujo de trabajar con otros desarrolladores que están en el mismo barco, sugiero que les pregunte qué sienten para transmitir la información necesaria, más fácilmente. Mi compañía tiene más de 100 tablas, y mi jefe me dio un ERD para una serie de tablas específicas que se conectan. Por lo tanto, también puede intentar dividir 1 ERD masivo en un grupo de ERD más pequeños y manejables.

Answer 3

Una cosa a considerar es la facilidad COMMENT incorporada en el DBMS. Si coloca comentarios en todas las tablas y todas las columnas en el DBMS mismo, entonces su documentación estará dentro del sistema de base de datos.

Al utilizar el recurso COMMENT no se realizan cambios en el esquema en sí, solo agrega datos a la tabla de catálogo USER_TAB_COMMENTS.

Answer 4

Utilizamos Enterprise Architect para nuestras definiciones de base de datos. Incluimos procedimientos almacenados, desencadenadores y todas las definiciones de tablas definidas en UML. Las tres características brillantes del programa son:

1. Importación de diagramas UML de una conexión ODBC.
2. Generar secuencias de comandos SQL (DDL) para toda la base de datos a la vez
3. Generar documentación personalizada con plantilla de su base de datos.

Puede editar sus definiciones de clase/tabla dentro de la herramienta UML y generar un documento completamente descriptivo con imágenes incluidas. El documento autogenerado puede estar en múltiples formatos, incluido MSWord. Tenemos menos de 100 tablas en nuestro esquema, y ​​es bastante manejable.

Nunca he estado más impresionado con ninguna otra herramienta en mis más de 10 años como desarrollador. EA admite Oracle, MySQL, SQL Server (múltiples versiones), PostGreSQL, Interbase, DB2 y Access de una sola vez. Cada vez que he tenido problemas, sus foros han respondido a mis problemas de inmediato. ¡¡Muy recomendable!!

Cuando entran los cambios de DB, hacemos en EA, generamos el SQL y lo comprobamos en nuestro control de versiones (svn). Usamos Hudson para construir, y construye automáticamente la base de datos a partir de scripts cuando ve que ha modificado el sql registrado.

(Mostly stolen from another answer of mine)

Answer 5

Una solución wiki es compatible con hipervínculos y la edición colaborativa, pero un wiki es sólo tan buena como las personas que lo mantienen organizados y actualizados. Necesita que alguien se haga cargo del proyecto del documento, independientemente de la herramienta que use. Esa persona puede involucrar a otras personas conocedoras para completar los detalles, pero una persona debe ser responsable de organizar la información.

Si no puede utilizar una herramienta para generar un ERD mediante ingeniería inversa, tendrá que diseñar uno manualmente con TOAD o VISIO.

Cualquier ERD con cientos de objetos probablemente sea inútil como guía para los desarrolladores, ya que será ilegible con tantas casillas y líneas. En una base de datos con tantos objetos, es probable que haya "subsistemas" de unas pocas docenas de tablas y vistas cada una. Entonces debería hacer diagramas personalizados de estos subsistemas, en lugar de esperar que una herramienta lo haga por usted.

También puede diseñar un pseudo-ERD, donde los grupos de tablas están representados por un solo objeto en un diagrama, y ​​ese grupo se expande en otro diagrama.

Un único ERD o un conjunto de ERD no es suficiente para documentar un sistema de esta complejidad, de la misma manera que un diagrama de clase sería adecuado para documentar un sistema OO. Tendrá que escribir un documento, utilizando los ERD como ilustraciones. Necesita descripciones de texto del significado y uso de cada tabla, cada columna y las relaciones entre las tablas (especialmente cuando tales relaciones son implícitas en lugar de estar representadas por restricciones de integridad referencial).

Todo esto es mucho trabajo, pero valdrá la pena. Si hay un lugar claro y actualizado donde se documenta el esquema, todo el equipo se beneficiará de él.

Answer 6

Esta respuesta se extiende a Kieveli anterior, que he votado a favor. Si su versión de EA es compatible con el Modelo de roles de objetos (diseño conceptual, frente a diseño lógico = ERD), aplique ingeniería inversa a eso y luego complete el modelo con la riqueza expresiva que le brinda.

La opción más barata y ligera es descargar Visiomodeler gratis de MS, y hacer lo mismo con eso.

El ORM (llámalo ORMDB) es la única herramienta que he encontrado que admite y fomenta las conversaciones de diseño de bases de datos con partes interesadas ajenas a IS sobre objetos BL y relaciones.

Comprobación de la realidad: en el camino hacia la generación de su DDL, pasa a través de una fase de ERD de parada completa donde puede satisfacer sus preguntas sobre si hace algo extraño. No es así Probablemente le muestre debilidades en el ERD que diseñó usted mismo.

ORMDB es un caso clásico del principio de que cuanto más conceptual es la herramienta, más pequeño es el mercado. Las chicas solo quieren divertirse, y los programadores solo quieren codificar.

Answer 7

Bueno, una imagen vale más que mil palabras, por lo que recomendaría crear diagramas ER donde pueda ver la relación entre tablas de un vistazo, algo que es difícil de hacer con una descripción de solo texto.

No tiene que hacer toda la base de datos en un diagrama, divídalo en secciones. Usamos Visual Paradigm en el trabajo, pero EA es una buena alternativa como ERWIN, y sin duda hay muchos otros que son igual de buenos.

Si tiene paciencia, entonces usar html para documentar las tablas y columnas facilita el acceso a su documentación.

Answer 8

Aquí es un buen puesto en la forma de abordar la documentación de la base de datos: http://www.simple-talk.com/sql/database-administration/database-documentation---lands-of-trolls-why-and-how/

Answer 9

En nuestro equipo hemos llegado a enfoque útil para documentar grandes bases de datos heredadas de Oracle y SQL Server. Usamos Dataedo para documentar los elementos del esquema de la base de datos (diccionario de datos) y crear diagramas ERD. Dataedo viene con un repositorio de documentación para que todo su equipo pueda trabajar en la documentación y lectura de documentación reciente en línea. Y no necesita interferir con la base de datos (comentarios de Oracle o MS_Description de SQL Server).

Primero importa el esquema (todas las tablas, vistas, procedimientos almacenados y funciones, con activadores, claves externas, etc.). A continuación, define dominios/módulos lógicos y agrupa todos los objetos (arrastre & drop) en ellos para poder analizar y trabajar en trozos más pequeños de la base de datos. Para cada módulo crea un diagrama ERD y escribe una descripción de nivel superior. Luego, cuando descubra el significado de tablas y vistas, escriba una breve descripción para cada una. Haz lo mismo para cada columna. Dataedo le permite agregar un título significativo para cada objeto y columna; es útil si los nombres de los objetos son vagos o no válidos. La versión Pro le permite describir claves externas, claves/restricciones y activadores únicos, lo cual es útil pero no esencial para comprender una base de datos.

Se puede acceder a la documentación a través de la interfaz de usuario o se puede exportar a PDF o HTML interactiva (esto último está disponible sólo en versión Pro).

descrito aquí es un proceso continuo en lugar de un trabajo a tiempo. Si su base de datos cambia (por ejemplo, nuevas columnas, vistas), debe sincronizar su documentación de forma periódica (clics en pareja con Dataedo).

Véase la documentación de la muestra: http://dataedo.com/download/Dataedo%20repository.pdf

algunas pautas sobre el proceso de documentación:

Diagramas:

• Mantenga sus diagramas pequeña y de fácil lectura - sólo incluyen mesas importantes, las relaciones y las columnas - sólo el uno que tenga algún significado para comprender el panorama general: claves primarias/comerciales, atributos y relaciones importantes,
• Uso de color diferente para las tablas de claves en un diagrama,
• Usted puede tener más de un diagrama por módulo,
• Puede agregar a la descripción del diagrama de las tablas más importantes/con la mayoría de las relaciones.

Descripciones:

• no documentan lo obvio - no escriben Descripción “Fecha del documento” para la columna document.date. Si no tiene sentido agregar nada, déjelo en blanco,
• Si los objetos almacenados en tablas tienen tipos o estados, es bueno enumerarlos en la descripción general de una tabla,
• Definir el formato que se espera, p. Ej. “Dd/mm/aa” para una fecha que se almacena en el campo de texto,
• Lista de todos los valores importantes conocidos/una su significado, por ejemplo, para la columna de estado podría ser algo como esto: “Estado del documento: A - Activo, C - Cancelado, D - Suprimido”,
• Si hay alguna API para una mesa - una vista que se debe utilizar para leer datos y funciones/procedimientos para insertar/actualizar datos - listela en la descripción de la tabla,
• Describa de dónde vienen los valores de filas/columnas (procedimiento, forma, interfaz, etc.),
• Use la marca "[deprecated]" (o similar)) para columnas que no deberían usarse (la columna de título es útil para esto, explique qué campo se debe usar en su lugar en el campo de descripción).

Answer 10

Si describir sus bases de datos a sus usuarios finales es su objetivo principal Ooluk Data Dictionary Manager puede resultar útil. Es un software multiusuario basado en web que le permite adjuntar descripciones a tablas y columnas y permite búsquedas de texto completo en esas descripciones. También le permite agrupar lógicamente tablas usando etiquetas y explorar tablas usando esas etiquetas. Tanto las tablas como las columnas se pueden etiquetar para encontrar elementos de datos similares en su base de datos/bases de datos.

El software le permite importar información de metadatos, tales como nombre de tabla, nombre de la columna, la columna tipo de datos, claves externas en su repositorio interno utilizando una API. La compatibilidad con las fuentes de datos JDBC viene incorporada y puede extenderse aún más a medida que la fuente API se distribuye bajo ASL 2.0. Está codificado para leer los COMENTARIOS/OBSERVACIONES de muchos RDBMS. Siempre puede anular manualmente la información importada. La información que puede almacenar sobre tablas y columnas se puede ampliar utilizando campos personalizados.

El Administrador de diccionario de datos utiliza la terminología "objeto de datos" y "atributo" en lugar de tabla y columna porque no está diseñado específicamente para bases de datos relacionales.

Notas

• Si la descripción de los aspectos técnicos de su base de datos, tales como disparadores, índices, estadísticas, es importante que este software no es la mejor opción. Sin embargo, es posible combinar una solución técnica con este software utilizando los campos personalizados del hipervínculo.
• El software no produce un ERD

Revelación: Yo trabajo en la compañía que desarrolla este producto.