데이터베이스를 문서화하는 방법

데이터베이스를 문서화하는 방법

---

(참고 : 이것이 데이터베이스 구조 를 어떻게 문서화합니까?에 가깝다는 것을 알고 있지만 동일하다고 생각하지 않습니다.)

저는 말 그대로 수백 개의 테이블과 뷰가있는 데이터베이스에서 작업을 시작했습니다. 모두 모음이 거의없고 문서가없는 암호화 된 이름을 사용합니다. 그들은 또한 데이터베이스 스키마에 대한 무상 변경을 허용하지 않으며 내 컴퓨터에서 테스트를 제외한 데이터베이스 (정기적으로 날아가고 다시 생성됨)를 제외하고는 어떤 데이터베이스도 건드릴 수 없으므로 누구에게도 도움이 될 주석을 추가 할 수 없습니다.

저는 "Toad"를 사용하여 ER 다이어그램을 만들려고했지만 48 시간 동안 계속 실행 한 후에도 여전히 아무것도 보이지 않았기 때문에 컴퓨터를 다시 필요로했습니다. 저는 최근에 고용 된 다른 직원들과 이야기를 나누고 있었는데, 우리 모두는 특정 테이블이 무엇을 의미하는지 또는 일부 열이 무엇을 의미하는지 궁금 할 때마다 개발자 위키에서 업데이트해야한다고 제안했습니다.

그래서 이것을하는 좋은 방법은 무엇입니까? 표 /보기 및 해당 열을 나열하고 이동하면서 채우시겠습니까? 제가 손에 넣은 기본 도구는 Toad, Oracle의 "SQL Developer", MS Office 및 Visio입니다.

---

제 경험상 ER (또는 UML) 다이어그램은 가장 유용한 아티팩트가 아닙니다. 많은 수의 테이블에서 다이어그램 (특히 리버스 엔지니어링 된 다이어그램)은 종종 아무도 아무것도 배우지 못하는 커다란 혼란스러운 엉망입니다.

내 돈을 위해 좋은 사람이 읽을 수있는 문서 (아마도 시스템의 작은 부분에 대한 다이어그램으로 보완 됨)가 가장 많은 마일리지를 제공합니다. 여기에는 각 테이블에 대해 다음이 포함됩니다.

• 테이블의 의미 및 기능적으로 사용되는 방법에 대한 설명 (UI 등)
• 명확하지 않은 경우 각 속성의 의미에 대한 설명
• 이 테이블과 다른 테이블 간의 관계 (외래 키)에 대한 설명 및 그 반대의 경우
• 추가 제약 및 / 또는 트리거에 대한 설명
• 이미 잘 문서화되지 않은 경우 테이블을 다루는 주요 뷰 및 프로세스에 대한 추가 설명

위의 모든 내용을 문서화하기 위해 문서화하지 마십시오. 명백한 내용을 다시 설명하는 문서는 사람들에게 방해가됩니다. 대신 처음에는 혼란 스러웠던 부분에 집중하고 몇 분 동안 매우 명확하고 간결한 설명을 작성하십시오. 그것은 당신이 그것을 생각하는 데 도움이 될 것이며 처음으로 이러한 테이블을 실행하는 다른 개발자에게 큰 도움 이 될 것 입니다.

다른 사람들이 언급했듯이 Enterprise Architect , Red Gate SQL Doc 및 다양한 공급 업체의 기본 제공 도구와 같이이를 관리하는 데 도움이 되는 다양한 도구가 있습니다. 그러나 도구 지원은 도움이되지만 (더 큰 데이터베이스에서는 중요하기도하지만) 데이터베이스 의 개념적 모델을 이해 하고 설명 하기 위해 열심히 노력하는 것이 진정한 승리입니다. 이러한 관점에서 텍스트 파일로도 할 수 있습니다 (위키 형식으로 수행하면 여러 사람이 해당 문서에 점진적으로 추가하는 작업을 공동으로 수행 할 수 있습니다. 따라서 누군가가 무언가를 알아낼 때마다 성장하는 신체에 추가 할 수 있습니다. 즉시 문서화).

---

고려해야 할 한 가지는 DBMS에 내장 된 COMMENT 기능입니다. DBMS 자체의 모든 테이블과 모든 열에 주석을 달면 문서가 데이터베이스 시스템 내에 있습니다.

COMMENT 기능을 사용하면 스키마 자체가 변경되지 않고 USER_TAB_COMMENTS 카탈로그 테이블에만 데이터가 추가됩니다.

---

우리는 DB 정의에 Enterprise Architect 를 사용 합니다. UML에 정의 된 저장 프로 시저, 트리거 및 모든 테이블 정의가 포함됩니다. 프로그램의 세 가지 뛰어난 기능은 다음과 같습니다.

1. ODBC 연결에서 UML 다이어그램을 가져옵니다.
2. 한 번에 전체 DB에 대한 SQL 스크립트 (DDL) 생성
3. DB의 사용자 지정 템플릿 문서를 생성합니다.

UML 도구 내에서 클래스 / 테이블 정의를 편집하고 그림이 포함 된 문서로 완전한 설명을 생성 할 수 있습니다. 자동 생성 된 문서는 MSWord를 포함하여 여러 형식이 될 수 있습니다. 스키마에 100 개 미만의 테이블이 있으며 매우 관리하기 쉽습니다.

저는 개발자로서 10 년 이상을 보낸 동안 다른 도구에 더 깊은 인상을받은 적이 없습니다. EA는 Oracle, MySQL, SQL Server (여러 버전), PostGreSQL, Interbase, DB2 및 Access를 한 번에 지원합니다. 내가 문제가있을 때마다 그들의 포럼은 내 문제에 신속하게 대답했습니다. 추천!!

DB 변경이 들어 오면 EA에서 만들고 SQL을 생성 한 다음 버전 제어 (svn)로 확인합니다. 빌드를 위해 Hudson 을 사용 하고 체크인 된 SQL을 수정 한 것을 확인하면 스크립트에서 데이터베이스를 자동 빌드합니다.

( 대부분 내 다른 답변에서 도난당했습니다 )

---

우리 팀에서는 레거시 대규모 Oracle 및 SQL Server 데이터베이스를 문서화하는 데 유용한 접근 방식을 찾았습니다. 데이터베이스 스키마 요소 (데이터 사전)를 문서화하고 ERD 다이어그램을 생성 하기 위해 Dataedo 를 사용 합니다. Dataedo는 문서 저장소와 함께 제공되므로 모든 팀이 온라인으로 최신 문서를 문서화하고 읽을 수 있습니다. 그리고 데이터베이스 (Oracle 주석 또는 SQL Server MS_Description)를 방해 할 필요가 없습니다.

먼저 스키마 (모든 테이블, 뷰, 저장 프로 시저 및 함수-트리거, 외래 키 등)를 가져옵니다. 그런 다음 논리 도메인 / 모듈을 정의하고 모든 개체를 여기에 그룹화 (드래그 앤 드롭)하여 더 작은 데이터베이스 청크를 분석하고 작업 할 수 있습니다. 각 모듈에 대해 ERD 다이어그램을 만들고 최상위 설명을 작성합니다. 그런 다음 테이블과 뷰의 의미를 발견하면 각각에 대한 간단한 설명을 작성합니다. 각 열에 대해 동일하게 수행하십시오. Dataedo를 사용하면 각 개체와 열에 의미있는 제목을 추가 할 수 있습니다. 개체 이름이 모호하거나 잘못된 경우 유용합니다. Pro 버전을 사용하면 외래 키, 고유 키 / 제약 조건 및 트리거를 설명 할 수 있습니다. 이는 유용하지만 데이터베이스를 이해하는 데 필수적인 것은 아닙니다.

UI를 통해 문서에 액세스하거나 PDF 또는 대화 형 HTML로 내보낼 수 있습니다 (후자는 Pro 버전에서만 사용 가능).

여기에 설명 된 것은 일회성 작업이 아니라 연속적인 프로세스입니다. 데이터베이스가 변경되면 (예 : 새 열,보기) 문서를 정기적으로 동기화해야합니다 (Dataedo로 몇 번의 클릭).

샘플 문서 참조 : http://dataedo.com/download/Dataedo%20repository.pdf

문서화 프로세스에 대한 몇 가지 지침 :

다이어그램 :

• 다이어그램을 작고 읽기 쉽게 유지하십시오. 중요한 테이블, 관계 및 열만 포함하십시오. 중요한 테이블, 관계 및 열만 포함하십시오. 주요 / 비즈니스 키, 중요한 속성 및 관계,
• 다이어그램의 키 테이블에 다른 색상을 사용합니다.
• 모듈 당 하나 이상의 다이어그램을 가질 수 있습니다.
• 가장 중요한 테이블 / 대부분의 관계에 대한 설명에 다이어그램을 추가 할 수 있습니다.

설명 :

• 명백한 것을 문서화하지 마십시오. document.date 열에 "문서 날짜"에 대한 설명을 작성하지 마십시오. 추가 할 의미가 없으면 비워 두세요.
• 테이블에 저장된 객체에 유형이나 상태가있는 경우 테이블의 일반적인 설명에 나열하는 것이 좋습니다.
• 예상되는 형식을 정의하십시오. 텍스트 필드에 저장된 날짜의 경우 "mm / dd / yy",
• 모든 알려진 / 중요한 값을 나열합니다. 예를 들어 상태 열의 경우 다음과 같을 수 있습니다. "문서 상태 : A – 활성, C – 취소됨, D – 삭제됨",
• 테이블에 대한 API가있는 경우-데이터를 읽는 데 사용해야하는 뷰와 데이터 삽입 / 업데이트를위한 기능 / 절차-테이블 설명에 나열합니다.
• 행 / 열의 값이 어디에서 오는지 설명 (프로 시저, 양식, 인터페이스 등),
• Use “[deprecated]” mark (or similar) for columns that should not be used (title column is useful for this, explain which field should be used instead in description field).

---

Here is a good post on how to approach the database documentation: http://www.simple-talk.com/sql/database-administration/database-documentation---lands-of-trolls-why-and-how/

---

A wiki solution supports hyperlinks and collaborative editing, but a wiki is only as good as the people who keep it organized and up to date. You need someone to take ownership of the document project, regardless of what tool you use. That person may involve other knowledgeable people to fill in the details, but one person should be responsible for organizing the information.

If you can't use a tool to generate an ERD by reverse engineering, you'll have to design one by hand using TOAD or VISIO.

Any ERD with hundreds of objects is probably useless as a guide for developers, because it'll be unreadable with so many boxes and lines. In a database with so many objects, it's likely that there are "sub-systems" of a few dozen tables and views each. So you should make custom diagrams of these sub-systems, instead of expecting a tool to do it for you.

You can also design a pseudo-ERD, where groups of tables are represented by a single object in one diagram, and that group is expanded in another diagram.

A single ERD or set of ERD's are not sufficient to document a system of this complexity, any more than a class diagram would be adequate to document an OO system. You'll have to write a document, using the ERD's as illustrations. You need text descriptions of the meaning and use of each table, each column, and the relationships between tables (especially where such relationships are implicit instead of represented by referential integrity constraints).

All of this is a lot of work, but it will be worth it. If there's a clear and up-to-date place where the schema is documented, the whole team will benefit from it.

---

This answer extends Kieveli's above, which I upvoted. If your version of EA supports Object Role Modeling (conceptual design, vs. logical design = ERD), reverse engineer to that and then fill out the model with the expressive richness it gives you.

The cheap and lighter-weight option is to download Visiomodeler for free from MS, and do the same with that.

The ORM (call it ORMDB) is the only tool I've ever found that supports and encourages database design conversations with non-IS stakeholders about BL objects and relationships.

Reality check - on the way to generating your DDL, it passes through a full-stop ERD phase where you can satisfy your questions about whether it does anything screwy. It doesn't. It will probably show you weaknesses in the ERD you designed yourself.

ORMDB is a classic case of the principle that the more conceptual the tool, the smaller the market. Girls just want to have fun, and programmers just want to code.

---

Since you have the luxury of working with fellow developers that are in the same boat, I would suggest asking them what they feel would convey the needed information, most easily. My company has over 100 tables, and my boss gave me an ERD for a specific set tables that all connect. So also, you might want to try breaking 1 massive ERD into a bunch of smaller, manageable, ERDs.

---

If describing your databases to your end users is your primary goal Ooluk Data Dictionary Manager can prove useful. It is a web-based multi-user software that allows you to attach descriptions to tables and columns and allows full text searches on those descriptions. It also allows you to logically group tables using labels and browse tables using those labels. Tables as well as columns can be tagged to find similar data items across your database/databases.

The software allows you to import metadata information such as table name, column name, column data type, foreign keys into its internal repository using an API. Support for JDBC data sources comes built-in and can be extended further as the API source is distributed under ASL 2.0. It is coded to read the COMMENTS/REMARKS from many RDBMSs.You can always manually override the imported information. The information you can store about tables and columns can be extended using custom fields.

The Data Dictionary Manager uses the "data object" and "attribute" terminology instead of table and column because it isn't designed specifically for relational databases.

Notes

• If describing technical aspects of your database such as triggers, indexes, statistics is important this software isn't the best option. It is however possible to combine a technical solution with this software using hyperlink custom fields.
• The software doesn't produce an ERD

Disclosure: I work at the company that develops this product.

---

Well, a picture tells a thousand words so I would recommend creating ER diagrams where you can view the relationship between tables at a glance, something that is hard to do with a text-only description.

You don't have to do the whole database in one diagram, break it up into sections. We use Visual Paradigm at work but EA is a good alternative as is ERWIN, and no doubt there are lots of others that are just as good.

If you have the patience, then using html to document the tables and columns makes your documentation easier to access.

ReferenceURL : https://stackoverflow.com/questions/369266/how-to-document-a-database