4.10 Database

All of these commands require that the database is specified, either via --db or the current workspace.

mtn db changesetify [--db=dbfile]

Converts the database to the changeset format.

This is only needed when upgrading very old monotone databases, created with monotone versions less than 0.15.

mtn db check [--db=dbfile]

Monotone always works hard to verify the data it creates and accesses. For instance, if you have hard drive problems that corrupt data in monotone’s database, and you attempt to retrieve this data, then monotone will notice the problem and stop, instead of silently giving you garbage data.

However, it’s also nice to notice such problems early, and in rarely used parts of history, while you still have backups. That’s what this command is for. It systematically checks the database dbfile to ensure that it is complete and consistent. The following problems are detected:

• missing files that are referenced by their SHA1 hash from some manifest but do not exist in the database. This is a serious problem; it means that your history is not fully reconstructible. You can fix it by finding the file with the given hash, and loading it into your database with fload.
• unreferenced files that exist in the database but are not referenced by their SHA1 hash from any existing manifest. In itself, this only indicates some wasted space, and is not a problem; it’s possible it could arise under normal use (for instance, in some strange corner cases following an incomplete netsync). It could also arise, though, as a symptom of some other more serious problem.
• missing manifests that are referenced by their SHA1 hash from some revision but do not exist in the database. This is a serious problem; it means that your history is not fully reconstructible. You can fix it by finding a database containing the manifest, and using mdata on that database to create a manifest data packet, which can be loaded into your database with read.
• unreferenced rosters that exist in the database but are not referenced by their SHA1 hash from any existing revision. In itself, this only indicates some wasted space, and is not a problem; it’s possible it could arise under normal use (for instance, if you have run local kill_revision, or in some strange-but-harmless corner cases following an incomplete netsync). It could also arise, though, as a symptom of some other more serious problem.
• incomplete manifests that exist in the database but contain references to files that do not exist in the database. For diagnosis and solution, see “missing files” above.
• missing revisions that are referenced by their SHA1 hash from some other revision or revision cert but do not exist in the database. This may be a serious problem; it may indicate that your history is not fully reconstructible (if the reference is from another revision) or that someone is creating bogus certs (if the reference is from a cert). You can fix it by finding a database containing the revision, and using rdata on that database to create a revision data packet, which can be loaded into your database with read.
• incomplete revisions that exist in the database but contain references to missing manifests, incomplete manifests or missing revisions. This always occurs with some more detailed error; see above.
• revisions with mismatched parents that disagree with the cached revision ancestry on their parent revisions. This may cause problems in using the database, and suggests the presence of a bug in monotone’s caching system, but does not involve data loss.
• revisions with mismatched children that disagree with the cached revision ancestry on their child revisions. This may cause problems in using the database, and suggests the presence of a bug in monotone’s caching system, but does not involve data loss.
• revisions with bad history that exist in the database but fail monotone’s normal sanity checks for consistent and correct history. This is a serious problem; it indicates that your history record is somehow malformed. This should not be possible, since monotone carefully checks every revision before storing it into the database, but if it does, then please request assistance on the monotone mailing list. Fixing this generally means you may lose some history — for instance, renames may be degraded into delete/add pairs — but the actual contents of every revision will still be reproducible.
• revisions with missing certs that exist in the database lacking at least one author, branch, changelog or date cert. All revisions are expected to have at least one of each of these certs. In itself, this is not necessarily a problem, but it is peculiar, and some operations such as netsync may behave strangely.
• revisions with mismatched certs that exist in the database with differing numbers of author, changelog and date certs. These certs are expected to appear together, as each revision committed should have an author, changelog and date associated with it. In itself, this is not a problem, but it is peculiar. All operations should behave normally.
• missing keys that have been used to sign certs but do not exist in the database. In itself, this is not a problem, except that monotone will ignore any certs signed by the missing key. You can fix it by finding a database containing the key in question, and using pubkey on that database to create a public key packet, which can be loaded into your database with read.
• certs with bad signatures that exist in the database with signatures that are invalid. In itself, this is not a problem, except that monotone will ignore any such certs. You may also wish to find out who is creating certs with bad signatures; it may indicate some kind of security attack.
• certs with unchecked signatures that exist in the database but cannot have their signatures checked because the signing key is missing. In itself, this is not a problem, except that monotone will ignore any certs signed by the missing key. You can fix it by finding a database containing the key in question, and using pubkey on that database to create a public key packet, which can be loaded into your database with read.
• branches not used or with incorrect head count or missing in the cache of branch heads. This is a serious problem; it suggests the presence of a bug in monotone’s caching system, but does not involve data loss; please report this on the monotone mailing list. You can fix it by running db regenerate_caches.

This command also verifies that the SHA1 hash of every file, manifest, and revision is correct.

mtn db dump [--db=dbfile]

This command dumps a sequence of SQL instructions representing the entire state of dbfile to the standard output stream. It is a very low-level command, and produces the most “recoverable” dumps of your database possible. It is sometimes also useful when migrating databases between variants of the underlying SQLite database format.

mtn db execute [--db=dbfile] sql-statement

This is a debugging command which executes sql-statement against your database, and prints any results of the expression in a tabular form. It can be used to investigate the state of your database, or help diagnose failures.

mtn db fix_certs [--db=dbfile] [--drop-bad-certs]

Attempt to fix bad certs.

Older monotone versions could sometimes associate certs with the wrong key. This fixes such certs if you have the correct key, and if --drop-bad-certs is given, drops any certs that you don’t have the correct key for. This should only be needed if you had such certs in your db when upgrading from monotone 0.44 or earlier, or if you loaded such certs with ’mtn read’.

mtn db info [--db=dbfile] [--full | --concise]

This command prints information about the monotone database dbfile, including its schema version and various table size statistics. --full prints additional info about timestamps; the default is --concise.

mtn db init [--db=dbfile]

This command creates and initializes a new monotone database at dbfile.

mtn db load [--db=dbfile]

This command applies a raw SQL statement, read from the standard input stream, to the database dbfile. It is most useful when loading a database dumped with the dump command.

Note that when reloading a dumped database, the schema of the dumped database is included in the dump, so you should not try to init your database before a load.

mtn db migrate [--db=dbfile]

This command attempts to migrate the database dbfile to the newest schema known by the version of monotone you are currently running. If the migration fails, no changes should be made to the database.

If you have important information in your database, you should back up a copy of it before migrating, in case there is an untrapped error during migration.

mtn db regenerate_caches

Regenerates the caches stored in the database.

This is only needed to recover from a newly discovered bug in monotone, or if your database becomes corrupted for some other reason.

mtn db rosterify

Converts the database to the rosters format.

This is only needed when upgrading very old monotone databases, created with monotone versions less than 0.15.

mtn db set_epoch branch epoch

Sets the branch’s epoch. See Rebuilding ancestry for discussion of epochs.

mtn db version [--db=dbfile]

This command prints out just the schema version of the monotone database dbfile.

mtn local kill_certs selector certname [certval]

This command deletes certs with the given name on revisions that match the given selector (see Selectors). If a value is given, it restricts itself to only delete certs that also have that same value. Like mtn local kill_revision, it is a very dangerous command; it permanently and irrevocably deletes historical information from your database. Also like kill_revision, this only deletes the certs from your local database; if there are other databases that you sync with which have these certs they will reappear when you sync, unless the owners of those databases also delete those certificates locally.

Early versions of monotone had db kill_tag_locally and db kill_branch_certs_locally commands. These can be emulated with local kill_certs i: tag TAG and local kill_certs i: branch BRANCH, respectively.

mtn local kill_revision id

This command “kills”, i.e., deletes, a given revision (see Selectors), as well as any certs attached to it. It is a very dangerous command; it permanently and irrevocably deletes historical information from your database. If you execute this command in a workspace, whose parent revision is the one you are about to delete, the killed revision is re-applied to this workspace which makes it possible for you to fix a problem and commit again later on easily. For this to work, the workspace may not have any changes and/or missing files.

There are a number of other caveats with this command:

• It can only be applied to revisions that have no descendants. If you want to kill a revision that has descendants, you must kill all of the descendants first.
• It only removes the revision from your local database (hence the “local” in the command name). If you have already pushed this revision out to another database, then the next time you pull from that database it may come back again. There is no way to delete a revision from somebody else’s database except to ask them to delete it for you.
• It does not actually delete the revision’s files or manifest from your database. If you run this command, and then run db check, it will note that you have an “unreferenced roster”. If you wish to eliminate this data for good (and thus free up the space), you may use netsync to pull from your current database into a new database; this creates a copy of your old database, without the unreferenced data. However, having this data in your database will not cause any problems, and acts as a safety net; if you later realize that you do, after all, need to retrieve the data in id, then db check will let you see which manifest it was, and with some work you can extract id’s data.