/usr/share/doc/monotone/html/Database.html

<html lang="en">
<head>
<title>Database - monotone documentation</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="monotone documentation">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Command-Reference.html#Command-Reference" title="Command Reference">
<link rel="prev" href="Packet-I_002fO.html#Packet-I_002fO" title="Packet I/O">
<link rel="next" href="Automation.html#Automation" title="Automation">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="texinfo.css">
</head>
<body>
<div class="node">
<a name="Database"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Automation.html#Automation">Automation</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Packet-I_002fO.html#Packet-I_002fO">Packet I/O</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Command-Reference.html#Command-Reference">Command Reference</a>
<hr>
</div>

<h3 class="section">4.10 Database</h3>

<p>All of these commands require that the database is specified, either
via <samp><span class="option">--db</span></samp> or the current workspace.

     <dl>
<dt><samp><span class="command">mtn db changesetify [--db=</span><var>dbfile</var><span class="command">]</span></samp><a name="index-mtn-db-changesetify-_005b_002d_002ddb_003d_0040var_007bdbfile_007d_005d-177"></a><dd>Converts the database to the changeset format.

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

     <br><dt><samp><span class="command">mtn db check [--db=</span><var>dbfile</var><span class="command">]</span></samp><a name="index-mtn-db-check-_005b_002d_002ddb_003d_0040var_007bdbfile_007d_005d-178"></a><dd>
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.

     <p>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 <var>dbfile</var> to
ensure that it is complete and consistent. The following problems are
detected:

          <ul>
<li>missing files
that are referenced by their <span class="sc">sha1</span> 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
<samp><span class="command">fload</span></samp>.

          <li>unreferenced files
that exist in the database but are not referenced by their <span class="sc">sha1</span>
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.

          <li>missing manifests
that are referenced by their <span class="sc">sha1</span> 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 <samp><span class="command">mdata</span></samp> on that
database to create a manifest data packet, which can be loaded into your
database with <samp><span class="command">read</span></samp>.

          <li>unreferenced rosters
that exist in the database but are not referenced by their <span class="sc">sha1</span>
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 <samp><span class="command">local kill_revision</span></samp>,
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.

          <li>incomplete manifests
that exist in the database but contain references to files that do not
exist in the database.  For diagnosis and solution, see &ldquo;missing
files&rdquo; above.

          <li>missing revisions
that are referenced by their <span class="sc">sha1</span> 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 <samp><span class="command">rdata</span></samp> on
that database to create a revision data packet, which can be loaded into
your database with <samp><span class="command">read</span></samp>.

          <li>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.

          <li>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.

          <li>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.

          <li>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 &mdash; for instance, renames may be degraded into delete/add
pairs &mdash; but the actual contents of every revision will still be
reproducible.

          <li>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.

          <li>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.

          <li>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 <samp><span class="command">pubkey</span></samp> on that
database to create a public key packet, which can be loaded into your
database with <samp><span class="command">read</span></samp>.

          <li>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.

          <li>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 <samp><span class="command">pubkey</span></samp> on that database to create a public key packet,
which can be loaded into your database with <samp><span class="command">read</span></samp>.

          <li>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 <samp><span class="command">db regenerate_caches</span></samp>.

     </ul>

     <p>This command also verifies that the <span class="sc">sha1</span> hash of every file, manifest,
and revision is correct.

     <br><dt><samp><span class="command">mtn db dump [--db=</span><var>dbfile</var><span class="command">]</span></samp><a name="index-mtn-db-dump-_005b_002d_002ddb_003d_0040var_007bdbfile_007d_005d-179"></a><dd>
This command dumps a sequence of SQL instructions representing the
entire state of <var>dbfile</var> to the standard output stream. It is a
very low-level command, and produces the most &ldquo;recoverable&rdquo; dumps of
your database possible. It is sometimes also useful when migrating
databases between variants of the underlying SQLite database format.

     <br><dt><samp><span class="command">mtn db execute [--db=</span><var>dbfile</var><span class="command">] </span><var>sql-statement</var></samp><a name="index-mtn-db-execute-_005b_002d_002ddb_003d_0040var_007bdbfile_007d_005d-_0040var_007bsql_002dstatement_007d-180"></a><dd>
This is a debugging command which executes <var>sql-statement</var> 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.

     <br><dt><samp><span class="command">mtn db fix_certs [--db=</span><var>dbfile</var><span class="command">] [--drop-bad-certs]</span></samp><a name="index-mtn-db-fix_005fcerts-_005b_002d_002ddb_003d_0040var_007bdbfile_007d_005d-_005b_002d_002ddrop_002dbad_002dcerts_005d-181"></a><dd>Attempt to fix bad certs.

     <p>Older monotone versions could sometimes associate certs with the wrong
key. This fixes such certs if you have the correct key, and if
<samp><span class="option">--drop-bad-certs</span></samp> 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'.

     <br><dt><samp><span class="command">mtn db info [--db=</span><var>dbfile</var><span class="command">] [--full | --concise]</span></samp><a name="index-mtn-db-info-_005b_002d_002ddb_003d_0040var_007bdbfile_007d_005d-_005b_002d_002dfull-_007c-_002d_002dconcise_005d-182"></a><dd>This command prints information about the monotone database
<var>dbfile</var>, including its schema version and various table size
statistics. <samp><span class="option">--full</span></samp> prints additional info about timestamps;
the default is <samp><span class="option">--concise</span></samp>.

     <br><dt><samp><span class="command">mtn db init [--db=</span><var>dbfile</var><span class="command">]</span></samp><a name="index-mtn-db-init-_005b_002d_002ddb_003d_0040var_007bdbfile_007d_005d-183"></a><dd>This command creates and initializes a new monotone database at <var>dbfile</var>.

     <br><dt><samp><span class="command">mtn db load [--db=</span><var>dbfile</var><span class="command">]</span></samp><a name="index-mtn-db-load-_005b_002d_002ddb_003d_0040var_007bdbfile_007d_005d-184"></a><dd>This command applies a raw SQL statement, read from the standard input
stream, to the database <var>dbfile</var>. It is most useful when loading
a database dumped with the <samp><span class="command">dump</span></samp> command.

     <p>Note that when reloading a dumped database, the schema of the dumped
database is <em>included</em> in the dump, so you should not try to
<samp><span class="command">init</span></samp> your database before a <samp><span class="command">load</span></samp>.

     <br><dt><samp><span class="command">mtn db migrate [--db=</span><var>dbfile</var><span class="command">]</span></samp><a name="index-mtn-db-migrate-_005b_002d_002ddb_003d_0040var_007bdbfile_007d_005d-185"></a><dd>This command attempts to migrate the database <var>dbfile</var> 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.

     <p>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.

     <br><dt><samp><span class="command">mtn db regenerate_caches</span></samp><a name="index-mtn-db-regenerate_005fcaches-186"></a><dd>Regenerates the caches stored in the database.

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

     <br><dt><samp><span class="command">mtn db rosterify</span></samp><a name="index-mtn-db-rosterify-187"></a><dd>Converts the database to the rosters format.

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

     <br><dt><samp><span class="command">mtn db set_epoch </span><var>branch</var> <var>epoch</var></samp><a name="index-mtn-db-set_005fepoch-_0040var_007bbranch_007d-_0040var_007bepoch_007d-188"></a><dd>Sets the branch's epoch. See <a href="Rebuilding-ancestry.html#Rebuilding-ancestry">Rebuilding ancestry</a> for discussion of epochs.

     <br><dt><samp><span class="command">mtn db version [--db=</span><var>dbfile</var><span class="command">]</span></samp><a name="index-mtn-db-version-_005b_002d_002ddb_003d_0040var_007bdbfile_007d_005d-189"></a><dd>This command prints out just the schema version of the monotone
database <var>dbfile</var>.

     <br><dt><samp><span class="command">mtn local kill_certs </span><var>selector</var> <var>certname</var><span class="command"> [</span><var>certval</var><span class="command">]</span></samp><a name="index-mtn-local-kill_005fcerts-_0040var_007bselector_007d-_0040var_007bcertname_007d-_005b_0040var_007bcertval_007d_005d-190"></a><dd>This command deletes certs with the given name on revisions that match
the given selector. If a value is given, it restricts itself to only
delete certs that also have that same value. Like <samp><span class="command"><a href="mtn-local-kill_005frevision.html#mtn-local-kill_005frevision">mtn local kill_revision</a></span></samp>, it is a very dangerous command; it permanently
and irrevocably deletes historical information from your
database. Also like <samp><span class="command">kill_revision</span></samp>, 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.

     <p>Early versions of monotone had <samp><span class="command">db kill_tag_locally</span></samp> and
<samp><span class="command">db kill_branch_certs_locally</span></samp> commands. These can be emulated with
<samp><span class="command">local kill_certs i: tag TAG</span></samp> and
<samp><span class="command">local kill_certs i: branch BRANCH</span></samp>, respectively.

     <p><a name="mtn-local-kill_005frevision"></a><br><dt><samp><span class="command">mtn local kill_revision </span><var>id</var></samp><a name="index-mtn-local-kill_005frevision-_0040var_007bid_007d-191"></a><dd>This command &ldquo;kills&rdquo;, i.e., deletes, a given revision, 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.

     <p>There are a number of other caveats with this command:
          <ul>
<li>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. 
<li>It only removes the revision from your local database (hence the
&ldquo;local&rdquo; 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. 
<li>It does not actually delete the revision's files or manifest from your
database.  If you run this command, and then run <samp><span class="command">db check</span></samp>, it
will note that you have an &ldquo;unreferenced roster&rdquo;.  If you wish to
eliminate this data for good (and thus free up the space), you may use
netsync to <samp><span class="command">pull</span></samp> 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 <var>id</var>, then
<samp><span class="command">db check</span></samp> will let you see which manifest it was, and with some
work you can extract <var>id</var>'s data. 
</ul>

</dl>

</body></html>
monotone-doc 1.0-3 / usr / share / doc / monotone / html / Database.html
