Database documentation - dbdesc - document your databases!

User guide

dbdesc: command line interface

dbdesc can be used from the command line. This way you can easily integrate dbdesc in other process like scheduled builds.

To open a console window, select Run from the Windows Start menu and type cmd.exe

dbdesc uses several switches to control its behavior. The first parameter must be always the database engine. Currently the available values are SqlServer, Firebird or Access. The rest of the parameters can appear in any order.

SQL Server

In this example we are going to suppose that you have a SQL Server (2000, 2005, 2005 Express or MSDE) instance installed on your system with windows authorization enabled. To get an html file with the info of the northwind database you must only type:

dbdesc SqlServer -d northwind

The file output.xml will be generated on your current directory.

If you are querying a database that is located on a remote server or a non-default named instance, simply add the parameter -S <server name>. Additional parameters are available to set the database user and password (-U <username> -P <password>) or to use windows authentication (-E). dbdesc will query system tables, so administrative privileges are required.

dbdesc SqlServer -S <remoteDbServerName> -d northwind -U <username>
                    -P <password>

Note that the parameters use the same syntax than the osql tool.

dbdesc can parse this xml file with a xslt template. In the following example dbdesc is instructed to use a template that will output

a html page:
dbdesc SqlServer -d northwind -i html.xslt -o northwind.htmlview output

a Rich Text Format (for Word 2000 or above) file:
dbdesc SqlServer -d northwind -i rtf.xslt -o northwind.rtfview output

a Word 2003 XML document (only for Word 2003 or above) file:
dbdesc SqlServer -d northwind -i xml_Word2003.xslt -o northwind.xmlview output

Documenting one schema

You can document just one schema using the switch -ds

dbdesc SqlServer -d northwind -ds Customer -i xml_Word2003.xslt -o northwind.xml

In this example only the Customer schema will be documented.

There are a couple of useful switches if you're using dbdesc in your scripts. The first one outputs a list of all the SQL Server instances visible from your computer:
dbdesc SqlServer -Ls

The second one allows you to list the databases stored in one server:
dbdesc SqlServer -S MyServer -Ld

MySQL

If you are targeting a MySQL server, the command line options are essentially the same as the SQL Server. The -Ls switch is not available though.

Firebird

Using Firebird engine is very similar to the MSDE engine. The only difference is the argument -E which, with Firebird, means to use the embedded engine to connect with the database. This way you can document a Firebird database even if the Firebird server is not installed in the system.

Also the -U argument is missing because the connection always uses the SYSDBA user.

Ms Access

Again the use is similar to the other engines. Password protected databases are supported using the switch -P. The arguments -U, -S and -E have no effect on this engine.

Using configuration files

dbdesc allows you to put all the parameters in a text file. You can add additional lines to this file and dbdesc will execute each line.

For example if we want to document the northwind database getting an html and a rtf documentation version we can create the file northwind.dbdesc and add the following lines:

SqlServer -d northwind -i html.xslt -o northwind.html

                                                                                                    SqlServer -d northwind -i rtf.xslt -o northwind.rtf

Now we can execute dbdesc: dbdesc -c northwind.dbdesc

Exclude database objects

By default, dbdesc will document every object in a database. In case you want to exclude some kind of object simply add one of the following switches:

-table
- -pk (primary keys)
- -ix (indices)
- -fk (foreign keys)
- -ck (check constraints)
- -trigger
-view
-sp (stored procedures)
-udf
-udt
-xml (XML schema collections)
-asm (assemblies)
-user

You can also exclude some sections:

-od (object definitions)
-op (object permissions)
-ex (extended properties)
-dep (object dependencies)

XSLT templates

You can use a XSLT template by using -i xslt_template switch. dbdesc will try to load your template from the current directory or from the dbdesc application directory.

When using a XSLT template to parse the output, you must use the -o switch to select an output file name. If this switch is missing, dbdesc will use the name 'output.' + the first part of the XSLT file name. For example if you have a XSLT template named 'rtf_myTemplate.xslt' and you use:

dbdesc SqlServer -d northwind -i rtf_myTemplate.xslt

dbdesc will create a file named 'output.rtf' with the results. This way, if you add a prefix ('ext_') to your XSLT template names, you can omit the -o switch.

dbdesc Wizard

dbdesc has a wizard-like interface. Take a look at the user guide.