dbdoc

dbdoc is a tool for documenting database schemas. It generates a visual display of all schema information in which you are able to see all tables and their relation to each other.
You can set an Ant script to configure the order and display of your tables.

To execute dbdoc you need to install Graphviz.

1. Structure of a dbdoc script

1.1. Including of dbdoc tasks

First you have to include the dbdoc tasks and Orcas default tasks.

<import file="${orcas_dir}/orcas_default_tasks.xml"/>
<import file="${orcas_dbdoc_dir}/orcas_dbdoc_tasks.xml"/>

1.2. Accessing the database

The database will be read out in the task <orcas_dbdoc>.

<orcas_dbdoc jdbcurl="${jdbc_url}" user="${demo_user}" password="${demo_password}" outfolder="${output}" tmpfolder="${tmpdir}/">

1.3. Configuration of the process

All table groups, the style, the diagrams and their structure will be defined in <config>.

1.3.1. Configuration of table groups

All table groups will be defines in <tablerregistry>.

The task <tablegroup> will be created for every table group.

Both tasks <include> and <exclude> will be used in <tablegroup> for including and excluding tables.

Working with regular expressions is also possible, so you can create filters to select multiple tables.

Examples:

<tableregistry tablesrcfolder="tables">

  <tablegroup name="TIERDISPATCH">
    <include name=".*DISPATCH.*"/>
    <include name="TIEROWNER"/>
  </tablegroup>

  <tablegroup name="SLAUGHTER">
    <include name="SLAUGHT.*"/>
    <include name="TYPE_GRADE"/>
    <include name="TYP_TIERCATEGORY"/>
</tablegroup>

1.3.2. Style configuration

The output format of the tables and diagrams are defined in <styles>.

1.3.2.1. Configuration of table presentation

You can adjust the table presentation for every single table group in <tables>.
You only have to keep in mind not to assign a table to multiple table groups (the same applies to multiple selections by regular expressions!)

You’ll find many additional attributes in the Graphviz documentation.

<tables>
  <style name="fillcolor" value="#FFE500" tablegroup="TIER"/>
  <style name="fontsize"  value="18"      tablegroup="TIER"/>
  <style name="color"     value="green"   tablegroup="TIER"/>
  <style name="fillcolor" value="#FFE500" tablegroup="TIERNUMBERS"/>
  <style name="fillcolor" value="#FF6600" tablegroup="BUSINESSESTABLISHMENT"/>
  <style name="fillcolor" value="#FF9900" tablegroup="ADRESSE"/>
</tables>

1.3.2.2. Configuration of table presentation

All style groups are defined in <diagrams> and can be selected in the next step (diagram generation) in <diagram>.
The task <stylegroup> will be created for every style group.

There are six different style groups:

dot	fdp	sfdp
circo	neato	twopi

Every style group can be adjusted with <style>.
Possible parameters:

You’ll find many additional attributes in the Graphviz documentation . Not all attributes are supported by all style groups.

<diagrams>
  <stylegroup name="style1" dotexecutable="dot">
    <style name="nodesep" value="1"/>
    <style name="ranksep" value="1"/>
    <style name="splines" value="polyline"/>
  </stylegroup>
</diagrams>

1.3.3. Configuration of diagram structure

You can define the names and hierarchy of diagrams in <diagram>.

All three presentation formats of a diagram differ in size of the presented contents.

diagrams_only	-------------------------------------------------------------------------------------------------------------------------------------------------------- Hierarchically subordinated diagrams with their table groups and linking between them will be displayed here. Single tables will not be displayed. (Mainly interesting for the main diagram)
diagrams_with_tables	Hierarchically subordinated diagrams with their table groups and linking between them will be displayed here. (Error-prone presentation)
tables	All hierarchically subordinated tables with linking between them will be displayed here. Subordinated diagram structures will not be considered. (Chaotic with many tables)

The hierarchical structure of the a diagram will be achieved by nesting <diagram> tasks.
The presentation form “diagrams_only” should be chosen for the main diagram (which includes all further diagrams) to achieve a clear presentation.
To select all table groups, you have to set “tablegroup” to “.*”.

<diagram label="Milk production" stylegroup="style1" subinclude="diagrams_only" tablegroup=".*"/>

If you are going to execute this, all table groups with all associated tables will be loaded and displayed because there are no hierarchically subordinated diagrams.
With a big amount of included tables, this can get complex very fast.
Because of this, there is the possibility to summarize table groups in separate diagrams, which are displayed hierarchically below the main diagram.

If you take the world as an example, there will be a diagram called “world”. For this diagram you have a subordinate diagram for each continent. For a continent diagram you will have subordinate state diagrams and so on.

<diagram label="The world" subinnclude="diagrams_only" tablegroup=".*">

  <diagram label="Europe" subinnclude="diagrams_with_tables">
    <diagram label="Germany" subinnclude="tables">
      <diagram label="Baden_Wuerttemberg" tablegroup="Baden_Wuerttemberg"/>
      <diagram label="Bavaria" tablegroup="Bavaria"/>
    </diagram>
    <diagram label="Spain" tablegroup="Spain"/>
  </diagram>

  <diagram label="South America" subinnclude="tables">
    <diagram label="Brasil" tablegroup="Brasil"/>
    <diagram label="Chile" tablegroup="Chile"/>
    <diagram label="Columbia" tablegroup="Columbia"/>
  </diagram>

</diagram>

If you execute this code, there will be a diagram for “Europe” with subordinate diagrams “Spain” and “Germany” (“Germany” has two more subordinate diagrams for the federa states Bavaria and Baden-Württemberg).

Example project dbdoc_demo

You will find an example project at examples\dbdoc_demo\build.xml. You can execute it and use it as a template for your own projects.
The example is a data model für milk production.
Here you will find the main diagram (the gray rectangles are hierarchically subordinate diagrams):

This link offers a presentation of the table group on an extra page.

Single tables can also be selected and will display associated SQL queries of included table directories.