Derby Database Corruption Issues

Derby is a very stable database.

However, just like with any DBMS, it is still possible to corrupt a database.

This document explores some of the issues related to database corruption, including things that might cause corruption, and techniques for dealing with a corrupted database.

Categories of Corruption

There are two types of corruption

Possible Causes of Database Corruption

The Derby Developers community is always attempting to ensure database corruption is as unlikely as is possible. However, there are some issues that have shown in the past to lead to database corruption:


Matching the list of possible causes above, one can do the following to prepare and prevent database corruption:


If the database has become corrupt, and you do not have a usable backup, there are still a couple of approaches for salvaging as much as possible from the damaged databases. This is not a guaranteed mechanism of restoring a database - depending on the corruption, the tools may not be able to access the database, and even if they do, in the end, there may still be data missing, and it's impossible to say what. Having a proper backup plan, and restoring from backup is still a better option.

Optional Tools for working with corrupt databases

There are some optional tools that have been written to facilitate crawling a database in the face of corruption. These are not part of the product distributions, and at time of writing this (December 2013), they are not even checked-in into the source code. To use them (currently), you will have to download the various tools from their JIRAs and compile with access to the derby.jars. These tools are (partly) based on some documentation on the Apache Derby web site:

The optional tools are found in these JIRAs:

Note: currently, to compile in trunk, you need to adjust the permissions of the method from private to public.


First it is helpful to understand the connection between tablenames and the .dat filenames. See this page: ListFileNamesOfTables. A quick way to go from container/conglomerate number is to convert the container number from dec to hex. Then add 'c' to the front and '.dat' as extension. If the hex number ends in 0 it is a base table, and if it ends in 1, it is a btree (index).


The first of these tools is DataFileVTI and of DERBY-6136. The JIRA issue provided a .sql file which can be used to access a database. You have to change the path in the .sql.

Note, that you *do* need to know the passwords of the various users to access their schemas. Otherwise, the tool will give an error like this:  The exception 'java.lang.Exception: APP is not the owner of the database 

Note also, that if you've built the tools using trunk, and the database was created with an older Derby version, you need the special alpha-version upgrade flag, e.g.:  java -Dderby.database.allowPreReleaseUpgrade=true dataFileVTI-1.sql 

Which for instance for the syschemas showed this:

ij> select * from sysschemas;

A second mechanism to access the database is by registering a custom tool. You need to have a database physically upgraded to at least 10.10 or the syscs_register_tool procedure will not be available:

 call syscs_util.syscs_register_tool('customTool',<register_or_un>,'<name of the class>,'<controlschemaname>',<tableprefix>, '<database_location>','<bootpwd>','<dbo_username>','<dbo_password'>); 

For example:

 call syscs_util.syscs_register_tool('customTool',true,'RawDBReader','CONTROL','RAW_', 'c:/10tst/opttools/corruptdb/TST',null,'APP',null); 

At this point, you can select contents from the corrupted database. Tor instance, if there's a table 'sched' in the schema 'TSTSCHEMA', like so:  select * from RAW_TSTSCHEMA.SCHED; 

I found, that a good way to effectively see all schemas and their tables was to run this query in ij (after issuing maximumdisplaywidth 20;)

ij> SELECT SCHEMANAME, TABLENAME FROM sys.sysschemas s, sys.systables t WHERE s.schemaid = t.schemaid


and you unregister the tool like so;  call syscs_util.syscs_register_tool ('customTool',false,'RawDBReader','CONTROL','RAW_'); 

The schemas starting with 'RAW_' will be removed again when you unregister the tool.

See DERBY-6136: for more examples when the database is encrypted, or using other authentication mechanisms. and

This is from DERBY-5201. The intention is to read the seg0.


This tool prints out the signature of a table, which is needed for the DataFileReader. This tool did not work with just compiled classes for me, it gave a 'java.sql.Exception: No suitable driver". But it worked with jars (derbyrun.jar) in the classpath.

Usage:  java TableSignatureReader connectionURL schemaName tableName 


   connectionURL e.g. "jdbc:derby:db1"
   schemaName case-sensitive schema name, e.g. APP
   tableName case-sensitive table name, e.g. T1

Here's an example use...  java TableSignatureReader "jdbc:derby:db1" SYS SYSALIASES 

...which prints out the following result:

( "ALIASID" char( 36 ), "ALIAS" varchar( 128 ), "SCHEMAID" char( 36 ), "JAVACLASSNAME" long varchar, "ALIASTYPE" char( 1 ), "NAMESPACE" char( 1 ), "SYSTEMALIAS" boolean, "ALIASINFO" serializable, "SPECIFICNAME" varchar( 128 ) )


Usage:  java DataFileReader $dataFileName [ -v ] [ -d $D ] [ -p $P ] [ -n $N ] [ -e $encryptionAttributes $serviceProperties ] 


   -v Verbose. Print out records and slot tables. Field data appears as byte arrays. If you do not set this flag, the tool just decodes the page headers.
   -d Data signature. This makes a verbose printout turn the field data into objects. $D is a row signature, e.g., "( a int, b varchar( 30 ) )"
   -p Starting page. $P is a number which must be at least 1, the first page to read after the header. Page 0 (the header) is always read.
   -n Number of pages to read. $N is a positive number. Defaults to all subsequent pages.
   -e If the database is encrypted, you must supply the encryption attributes and the location of

For example, the following command deserializes all of the records in the SYSCONGLOMERATES file:  java DataFileReader db/seg0/c20.dat -v -d "( a char(36), b char(36), c bigint, d varchar( 128), e boolean, f serializable, g boolean, h char( 36 ) )" 

The following command decodes the entire SYSCOLUMNS conglomerate:  java DataFileReader db/seg0/c90.dat -v -d "( a char(36), b char(128), c int, d serializable, e serializable, f char( 36 ), g bigint, h bigint, i bigint )" 

Note the special 'serializable' type in the preceding example. Use 'serializable' for user-defined types and for the system columns which are objects.

The following example decrypts and deserializes an entire SYSCONGLOMERATES file, dumping the result into an xml file for inspection:

 java DataFileReader wombat/seg0/c20.dat -v -d "( a char(36), b char(36), c bigint, d varchar( 128), e boolean, f serializable, g boolean, h char( 36 ) )" -e Wednesday wombat/ > z.xml 

Note the special 'serializable' type in the preceding example. Use 'serializable' for user-defined types and for the system columns which are objects.

Here are examples of using this tool on encrypted databases:

 java DataFileReader encryptedDB/seg0/c490.dat -v -d "( a varchar( 50 ), b char( 11 ) )" -e "encryptionKey=abcd1234efab5678" encryptedDB/ > ~/junk/z.xml 

 java DataFileReader bootpasswordDB/seg0/c490.dat -v -d "( a varchar( 50 ), b char( 11 ) )" -e "bootPassword=mysecretpassword" bootpasswordDB/ > ~/junk/zz.xml 

Other examples of usage:

1) Decode an entire data file, putting the resulting xml in the file z.xml. You can then view that file using a browser like Firefox, which lets you collapse and expand the elements.  java DataFileReader db/seg0/c20.dat -v -d "( a char(36), b char(36), c bigint, d varchar( 128), e boolean, f serializable, g boolean, h char( 36 ) )" > z.xml 

2) Pretty-print the file header:

java DataFileReader db/seg0/c20.dat -n 1
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <allocPage number="0">
        <status hexvalue="1">
        <containerStatus hexvalue="0">
        <extentStatus hexvalue="30000010">
        <freePages totalLength="8" bitsThatAreSet="0"/>
        <unFilledPages totalLength="8" bitsThatAreSet="1"/>

3) Count the number of pages in a data file:

 java DataFileReader db/seg0/c20.dat | grep pageCount <pageCount>9</pageCount> 

4) Decode 3 pages, starting at page 2. This one is a little tricky because the header page is always decoded. So you need to ask for 4 pages (3 data pages plus 1 header page):

 java DataFileReader db/seg0/c20.dat -v -p 4 -n 3 

LogFileReader and ControlFileReader

These are from DERBY-5195: Create tools for browsing the files in the database log directory.


Usage:  java LogFileReader $logFileName [ -v ] [ -p $P ] [ -n $N ] [ -e $bootPassword $serviceProperties ]  where

   -v Verbose. Deserialize the logged operations. If you do not set this flag, the tool just decodes the wrapper headers.
   -p Starting position. $P is a positive number, the offset of the first log entry to read. This causes the tool to skip reading the file header as well.
   -n Number of records to read. $N is a non-negative number. If you do not specify this flag, the tool prints all subsequent log entries.
   -e If the database is encrypted, you must supply the boot password and the location of

The following example decrypts and deserializes an entire log file, dumping the result into an xml file for inspection:

 java LogFileReader wombat/log/log1.dat -v -e Wednesday wombat/ > z.xml 

More examples:

1) Decode an entire log file, putting the resulting xml in the file z.xml. You can then view that file using a browser like Firefox, which lets you collapse and expand the elements. Because the -v switch is specified, the contents of the logged operations are deserialized and <details> elements are populated with the toString() results:

 java LogFileReader db/log/log2.dat -v > z.xml 

2) Pretty-print a log file header:

java LogFileReader db/log/log2.dat -n 0
<?xml version="1.0" encoding="UTF-8" standalone="no"?>

3) Count the number of entries in a log file:

java LogFileReader db/log/log2.dat | grep recordCount

4) Decode 3 log entries, starting at a given record offset:

java LogFileReader db/log/log2.dat -v -p 29363 -n 3
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
        <groups hexvalue="180">
        <transactionID value="192"/>
        <operation type="">
          <details>Page Operation: Page(2,Container(0, 81)) pageVersion 75 : Purge : 36 slots starting at 37 (recordId=43) (recordId=44) (recordId=45) (recordId=46) (recordId=47) (recordId=48) (recordId=49) (recordId=50) (recordId=51) (recordId=52) (recordId=53) (recordId=54) (recordId=55) (recordId=56) (recordId=57) (recordId=58) (recordId=59) (recordId=60) (recordId=61) (recordId=62) (recordId=63) (recordId=64) (recordId=65) (recordId=66) (recordId=67) (recordId=68) (recordId=69) (recordId=70) (recordId=71) (recordId=72) (recordId=73) (recordId=74) (recordId=75) (recordId=76) (recordId=77) (recordId=78)</details>
        <groups hexvalue="180">
        <transactionID value="192"/>
        <operation type="">
          <details>Page Operation: Page(1,Container(0, 81)) pageVersion 147 : Insert : Slot=1 recordId=79</details>
        <groups hexvalue="112">
        <transactionID value="192"/>
        <operation type="">
          <details>EndXact null Committed : transactionStatus = Committed</details>


This tool reads the control file in the log directory and pretty-prints it as an xml file.


java ControlFileReader db/log/log.ctrl
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
  <flags flags="1">

java ControlFileReader generated/toursdb/toursdb/log/log.ctrl
<?xml version="1.0" encoding="UTF-8"?><controlFile>
    <flags flags="0"/>

DatabaseCorruption (last edited 2014-12-13 16:32:01 by 50)