DB Sanity FAQ

1. Does DB Sanity support database xyz?

DB Sanity is supposed to work with any database for which a JDBC driver is available.

2. How to connect to database xyz?

Download a JDBC driver for database xyz, put it into the lib folder of your -db Sanity installation and create an environment file for the database instance you want to access, e.g. 'my-xyz.env.properties'. Finally start DB Sanity and provide the environment name, e.g.

dbsanity my-xyz

3. Why don't I see the 'Overall Summary' pie chart?

The pie chart feature is borrowed from Google's chart API. It can only be viewed when online. For getting an offline view of the overall statistics use the offline mode invoking DB Sanity with the option

-s offline.

4. How can I speed up DB Sanity runs?

DB Sanity is programmed to incur as little overhead to the database access as possible. Thus, long execution times mainly result from database execution times and serialization of defective data from the database to DB Sanity.

If there is a single check with an extraordinary number of defects, you might want to restrict the query's result row count. The number of columns a defect query returns, also influences the amount of data to be serialized and consequentially the time needed to transfer it. Thus, instead of issuing a select *, query for the primary key and one or two columns that characterize the data set or the defect. Do not include CLOB or BLOB columns in the query's select clause.

If you connect to a very large database, DBSanity might need several minutes for importing the database's structural data. You can specify a regular expression for tables to be ignored (see the file format documentation). Otherwise or additionally you can DB Sanity cause to buffer the structural data in a local file calling it with the command line argument -b. In the first invocation with -b, DB Sanity will need the same amount of time for execution, since it has to query the database structure once before it can be buffered. But on subsequent calls, the time overhead for structural data parsing is almost zero. A recent observation is that the time that an Oracle database needs for providing structural information about an index relates to the number of rows stored in the index. Thus, the import of an index with several million rows can take serveral minutes.

If the checks have aggregated to a very large number and you have a fast database connection, screen output might slow down DB Sanity execution. Then you can save a bit of time using the quiet mode (-q) or piping the console output to a file.

Check the Execution Times Report for the checks that take extraordinaly long time. In the long run they are worth investigation and optimization. Possibly you are lucky and detect redundant checks, e.g. a combination of a trimming and an uppercase check for a column which may only have one of a small list of values. In this case you save one check and replace the othe one with a efficient IN check. Also check them for the issues mentioned above.

5. A defect report file get so big that my browser cannot open it. What can I do?

Eather use the fast method described above (4) to cancel defect reporting after a given number of defects (accepting incorrect reports), or use the command line option -m (or --maxrows). It still counts all defects, but only writes a limited number of defect rows to the HTML report file.

6. How to reduce the disk space required to store the reports?

Use the method described in (5) an/or use the -z (--zip) option to compress the report to a ZIP file. It has the name of the report root directory with the zip suffix appended. After creating the ZIP file, DB Sanity deletes the original report folder, except if the option -B is used for opening the report in a browser immediately after execution. 

7. I've defined 500 checks. How to locate the only 5 defective checks quickly?

The 'Defects per Check' report module shows all the checks for which defects were found, but leaves out the faulty checks.

You can invoke DB Sanity with the command line option -C or --condensed to restrict the check list in the report to faulty or violated checks.

8. Why do I get an OutOfMemoryError?

The simplest measure for an OutOfMemoryError is to provide more memory to DB Sanity, setting the environment variable DBSANITY_OPTS to -Xmx1024m.

Do not return the content of CLOB or BLOB columns in the defect message. 

9. I get a strange exception message - what can I do to analyze?

DB Sanity works with many different databases through a common interface. Unfortunately, different database vendors have different understandings of the interfaces which cause errors. For getting detailed information about what is going in DB Sanity you can edit the file 'log4j.xml' in DBSANITY_HOME/bin and set the priorities of different loggers from 'info' to 'debug':

When running DB Sanity with these modified settings you get additional output to the console as well as to the log file dbsanity.log in your current working directory.