Summary

Making on-disk format changes is difficult and requires careful planning around upgrade and downgrade. Given upcoming use cases for format changes, e.g., PM-2947, we should consider making our various on-disk formats more easily extensible by leveraging one or more industry-standard solutions:

1) Tags

This is arguably the most flexible and the easiest to use mechanism for improving on-disk format extensibility. It is quite widely used, e.g., in MP3, TIFF, and WAV.

After a required fixed metadata header, the rest of the metadata section (or depending on the file format, data section) consists of tags, each of which has the following fields:

• Type (typically 1 or 2 bytes)
• Length (can be fixed length or a packed int)
• Payload

The type field indicates the content of the tag. For example, we could extend the cell format change in PM-2947 to have a tag type for BTREE_INFO and a tag type ADDR.

On upgrade, WiredTiger would notice that a tag that it expects is missing, so it would have to fill in the missing information according to the program-specific logic. On downgrade, WiredTiger can simply skip processing the tag by using the length field.

2) Variable-length metadata

The second industry-standard trick is to explicitly include the metadata length in the header. This is, for example, used in BMP and WAV. This approach can be used in combination with the first approach to make tags extensible.

On upgrade, we would add new fields to the end of the metadata. WiredTiger would find the length smaller than what it expects, so it would know that the new fields are missing. On downgrade, WiredTiger would see that it has extra fields that it does not know about, and it would use the length field to skip over the unknown field.

3) Including compatibility version number in the header

The final trick is to store two version numbers in the header:

• Version: The version of the file format.
• Compatibility version (I can't think of the correct term right now): The lowest compatible file format version.

This is best explained using an example. Let's say that we have a page with format version 5 and compatibility version 3. When the WiredTiger that understands on-disk formats up until version 4 sees the page, it knows it can safely use it, as long as it skips any unsupported tags or metadata fields using the aforementioned approaches.

But if an older version of WiredTiger sees its page that understands page formats up until version 2, it would know that it is unsafe to use the page, so it would return an error.