sql - query - modelo documentacion de una base de datos

Cómo documentar una base de datos (10)

(Nota: me doy cuenta de que esto está cerca de ¿Cómo se documenta la estructura de su base de datos?, Pero no creo que sea idéntica).

Empecé a trabajar en un lugar con una base de datos con literalmente cientos de tablas 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.

Aquí hay una buena publicación sobre cómo 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/

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, dividirlo 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, usar html para documentar las tablas y columnas facilita el acceso a su documentación.

Como puede darse 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 con mayor facilidad. 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.

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) a menudo son un gran lío enrevesado del que nadie aprende nada.

Por mi dinero, una buena documentación legible por humanos (quizás complementada con diagramas de partes 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 significa cada atributo, si no es obvio
Explicaciones de las relaciones (claves externas) de esta tabla a otras, y viceversa
Explicaciones de restricciones y / o factores desencadenantes adicionales
Explicación adicional de las principales vistas y procesos que tocan la tabla, si aún no están bien documentados

Con todo lo anterior, no documente con el fin de documentar: documentación que repite lo obvio que se interpone en el camino de las personas. 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 mejor, y ayudará masivamente a otros desarrolladores que se encuentren con estas tablas por primera vez.

Como han mencionado otros, hay una amplia variedad de herramientas para ayudarlo a administrar esto, como Enterprise Architect , Red Gate SQL Doc y las herramientas incorporadas de varios proveedores. Pero si bien el soporte de herramientas es útil (e incluso crítico, en bases de datos más grandes), hacer el trabajo arduo de comprender y explicar 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).

En nuestro equipo llegamos a un enfoque útil para documentar las 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 los dominios / módulos lógicos y agrupa todos los objetos (arrastrar y soltar) 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.

Puede acceder a la documentación a través de la IU o puede exportarla a PDF o HTML interactivo (este último solo está disponible en la versión Pro).

Aquí se describe un proceso continuo en lugar de un trabajo de una sola vez. 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).

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

Algunas pautas sobre el proceso de documentación:

Diagramas:

Mantenga sus diagramas pequeños y legibles, solo incluya tablas, relaciones y columnas importantes, solo el que tenga algún significado para comprender el panorama general, claves primarias / comerciales, atributos y relaciones importantes,
Use un color diferente para las tablas clave en un diagrama,
Puedes tener más de un diagrama por módulo
Puede agregar un diagrama a la descripción de las tablas más importantes / con la mayoría de las relaciones.

Descripciones:

No documente lo obvio: no escriba la 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, ej. "Mm / dd / aa" para una fecha que se almacena en el campo de texto,
Enumere todos los valores conocidos / importantes y su significado, por ejemplo, para la columna de estado podría ser algo como esto: "Estado del documento: A - Activa, C - Cancelada, D - Eliminada",
Si hay una API en una tabla, una vista que debe usarse para leer datos y funciones / procedimientos para insertar / actualizar datos, enumerarla en la descripción de la tabla,
Describa de dónde provienen los valores de filas / columnas (procedimiento, forma, interfaz, etc.),
Utilice la marca "[obsoleta]" (o similar) para las columnas que no se deben usar (la columna de título es útil para esto, explique qué campo se debe usar en su lugar en el campo de descripción).

Esta respuesta se extiende a Kieveli arriba, que subí. 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 respalda y alienta las conversaciones de diseño de bases de datos con partes interesadas ajenas a IS sobre objetos BL y relaciones.

Verificación de la realidad: en el camino hacia la generación de su DDL, pasa por 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.

Si su principal objetivo es describir sus bases de datos a sus usuarios finales, Ooluk Data Dictionary Manager puede resultarle ú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 como nombre de tabla, nombre de columna, tipo de datos de columna, claves foráneas 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 de "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, como desencadenantes, índices, estadísticas es importante, 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

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

Una cosa a considerar es la instalación de COMENTARIOS 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.

Una solución wiki admite hipervínculos y edición colaborativa, pero una wiki es tan buena como las personas que la mantienen organizada y actualizada. 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 usar 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 tantos cuadros 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 conjunto de ERD no es suficiente para documentar un sistema de esta complejidad, de la misma manera que un diagrama de clases no 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.

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:

Importar diagramas UML desde una conexión ODBC.
Genere SQL Scripts (DDL) para todo el DB a la vez
Genere 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 cambios DB, hacemos entonces en EA, generamos el SQL y lo chequeamos 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.

( Mayormente robado de otra respuesta mía )