Re: [Monotone-devel] Overview about tables in database?

[Nathaniel Smith]

On Sat, May 05, 2007 at 11:17:51PM +0900, Boris wrote:
> Is there any overview what the tables in the database mean and how they  
> are related? Some are easy to undertand (like revision_certs or  
> revision_ancestry). Others I have no idea what they mean (like rosters,  
> roster_deltas or heights). I ask as I try to understand what data could be  
> read and displayed in a viewer to create reports which contain more than  
> revisions and links between them. I wonder for example what SQL  
> statement(s) I would need to see source code differences for two given  
> revision IDs? I also wonder what tables have probably no meaning for a  
> viewer and could be dropped from the database (imagine a developer wants  
> to pass monotone's database to management so they can create reports;  
> however the developer doesn't want to send a huge database with all the  
> source code inside as management doesn't know anyway what to do with it).

Monotone essentially treats the database as an internal file format --
one that happens to be very convenient, robust, and with lots of the
maintainence outsourced to D. Richard Hipp, but still just an internal
file format.  So, in particular, the data layout is heavily optimized
for monotone's internal view of the world and the operations that
monotone has to perform, and not very suitable for generating random
reports using simple SELECT statements.  Also, the layout can and does
change in arbitrary ways between releases.  If you want to generate
reports, a more suitable interface to use might be the 'monotone
automate' commands, which are a stable and documented way to do
various queries on monotone's database.

If you really want to understand how the database itself is put
together, though, there isn't any better documentation than schema.sql
and database.cc.  ("rosters" and "roster_deltas" store, well, rosters
and roster deltas -- rosters are the internal data structure that
monotone uses to represent a tree snapshot.  "heights" stores,
approximately, the length of the longest path from each revision to
the root of the anceestry graph, which is a very useful piece of
information for doing various graph algorithms efficiently.)

-- Nathaniel

-- 
Details are all that matters; God dwells there, and you never get to
see Him if you don't struggle to get them right. -- Stephen Jay Gould