Bedrock

1It is just a database. Watch.

Claims are cheap, so let us not make one — let us look. Below is a real terminal session against a real repository: fossil-scm.fossil, the 68-megabyte clone of Fossil's own source code made for this tour. Step through it one command at a time.

Look at what was actually typed. file and sqlite3 are generic Unix tools — they know nothing whatsoever about version control. They worked because the file genuinely is an SQLite database. Fossil even stamps every database it creates with an SQLite application id (the integer 252006673), a small marker in the file header — which is why file can name it so confidently as a “Fossil repository” rather than just “some SQLite database.”

That .tables command listed 28 names: 27 ordinary tables, plus one view named artifact (a view is a saved query that behaves like a table). No magic file format, no proprietary container. If you can read SQLite — and after this tour you will — you can read a Fossil repository with nothing but the standard sqlite3 shell.

2Actually, three databases.

One precise correction before we go deeper, because it saves endless confusion later. When someone says “the Fossil database” they could mean one of three different SQLite files. db.c opens by saying exactly this, in its own words:

The distinction that matters most: the repository is the project; the checkout is one working copy of it. One repository can have many checkouts (or none). The checkout database is small — it is just a notebook saying “I am a working copy of that repository, currently at this check-in.” The repository database is the real thing. We will live in the repository for most of this tour and visit the checkout properly in the Workshop, District 6.

3The foundation stone: the blob table.

Of the repository's 27 tables, one is the foundation that the rest merely annotate. It is called blob, and the rule is absolute: every artifact in a Fossil project is one row in the blob table. Every version of every file, every check-in, every wiki page, every forum post — a row here. Nothing else.

Here is its real schema, straight from the repository. Click any column to learn what it holds.

CREATE TABLE blob(
  rid      INTEGER PRIMARY KEY,
  rcvid    INTEGER,
  size     INTEGER,
  uuid     TEXT UNIQUE NOT NULL,
  content  BLOB,
  CHECK( length(uuid)>=40 AND rid>0 )
);

The explorer above shows that table as the running database reports it. Here is where the table is declared — and the first surprise is that it does not live in a .sql file at all. Unfold the blueprint.

Two names for one thing: rid and uuid

Notice that a blob row carries two quite different identifiers. This pairing is not an accident, and it recurs in nearly every table upstream — so it is worth meeting head-on now.

Two names for the same artifact, each good at what the other is bad at. The integer rid is for the machine; the hash uuid is for the world. Translating between them is one of the most common things Fossil's code does — watch for it.

4Source of truth, and derived cache.

The 27 tables are not a flat pile of equals. They fall into layers, and one distinction outranks all the others. schema.c — the file that defines the schema — states it plainly: blob and delta together hold “the global state of a Fossil repository.” Everything else is, in principle, derived.

This is one of the most important ideas in the whole city, so hold onto it: only blob and delta are irreplaceable. Every other table is a cache — an index built for speed, reconstructible at any time. It is why fossil rebuild exists and why it is safe to run. We will see the derived tables being built when we reach the Chronicle, District 3.