MBTiles Validation

The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code.

mbtiles validate src_file.mbtiles

SQLite Integrity check

The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick.

Schema check

The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes.

Per-tile validation

If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). The hash is computed with the file's hash algorithm.

A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin's mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout.

Per-tile validation is not available for the flat schema and will be skipped. For the dedup-id normalized schema variant, foreign key integrity is validated instead - every tile_data_id in tiles_shallow must have a matching entry in tiles_data.

Aggregate Content Validation

Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash.

The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate, or the matching function of the file's hash algorithm:

md5_concat_hex(
    CAST(zoom_level  AS TEXT),
    CAST(tile_column AS TEXT),
    CAST(tile_row    AS TEXT),
    tile_data)

In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail.

The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist.

Hash algorithm

Every hash in a file, the per-tile tile_hash or tile_id and the agg_tiles_hash, is computed with one algorithm. The file records it in the hash_algorithm metadata value, and a file without that value is md5. The mbtiles tool writes the value into every file it creates.

A file from a tool that records no algorithm but does not use MD5, such as one made by tippecanoe, fails per-tile validation until the value is set.

mbtiles meta-set tippecanoe.mbtiles hash_algorithm fnv1a-decimal
mbtiles validate tippecanoe.mbtiles

mbtiles copy gives the destination the source's algorithm, and --hash-algorithm picks another one.