C <b>Design\sNote:</b>\sAbout\sthe\s"Irreversible\sSchema\sChange"
D 2011-05-06T18:24:09.405
E 2011-04-27T02:15:00 a1f9f17b603022c2b032bc3b2bff81118fd68d36
P b1e5452c82fd9769ef473b67bee4ac2f076d6f73
T +bgcolor * #c0ffc0
U drh
W 4710
<title>The Irreversible Schema Change</title>
The config-sync changes involve what is labeled as an
"irreversible schema change". (See check-in [1654456ef5aa8d].)
Here is what that means:
The Fossil repository database schema has two components.
The "persistent" schema contains source information and the
"auxiliary" schema contains secondary information. The
auxiliary schema is rebuilt from scratch from the source
information whenever you run "fossil rebuild". So, in other
words, the auxiliary schema does not contain any information
that is not also inherent in the persistent schema - it merely
expresses that information in a more convenient form.
Most schema changes involve changes to the auxiliary schema only.
That means that if you upgrade to a newer version of Fossil that
contains a schema change but later decide do not like the new version and
want to revert back to an older version, you can. After reverting,
simply run "fossil rebuild" again, which deletes all of the auxiliary
schema tables and rebuilds them from scratch based on the persistent
schema.
But the recent config-sync enhancement makes changes to the persistent
schema, using ALTER TABLE statements. The config-sync enhancement
adds an "mtime" column to all of the persistent tables that store
server configuration data (things like USER, and REPORTFMT). The
mtime field records the time that each row was last modified. Then
when two repositories want to synchronize their configuration, they
can take the most recent edits from each repository. The config-sync
enhancement addresses (among other things) the problem of
ticket [9b8333b29826deba].
When you upgrade to a version of Fossil that support config-sync,
you have to run "fossil rebuild". And this rebuild uses ALTER TABLE
to add the mtime column to various persistent tables (as well as make
a few other minor tweaks). Because it uses ALTER TABLE on a primary
data source, there is no way easy way to back out the schema change.
Once you update to a version of Fossil that supports config-sync, you
are mostly committed to staying with the later versions.
There is one escape route back to an older version of Fossil. You
can run a newer Fossil in server mode on the converted database, then
clone the repository using an older version of Fossil:
<blockquote><pre>
new-fossil server new-repo.fossil -localauth
old-fossil clone http://localhost:8080/ old-repo.fossil
</pre></blockquote>
One could probably also come up with an SQL script that would remove
the "mtime" columns and other changes from the new schema as well, but
that would be tricky and is not recommended.
<h2>About The Config-Sync Capability</h2>
The config-sync enhancement allows configuration changes on two
different servers to be synchronized. For example, suppose Alice
changes her password on server P and Bob changes his password on
server Q. By running a "user" configuration sync between P and Q,
Alice's password change would be copied from P to Q while Bob's change
would be copied from Q to P. Prior to the config-sync change, one
could copy the user password information from one repository to another,
but you could not merge together changes made on separate repositories.
The config-sync enhancement also changes the protocol for sending
configuration content from one repo to another. Formerly, many of
the configuration changes were sent by shipping raw SQL statements over
the wire. This was dangerous since it opened one up to SQL injection
attacks if you sync with a compromised server and it was brittle since
it assumed the exact same schema on both ends of the connection. A
new protocol is now in place that does not use raw SQL and does not
make unreasonable assumptions about the schemas.
The older configuration transfer protocol is retained for compatibility.
The plan is to discontinue the older protocol after one year, after
everyone has had plenty of time to upgrade. In the meantime, newer
servers will automatically recognize that they are talking with older
clients and will use the older protocol. Newer clients will not
exchange configuration information with older servers, though, unless
the --legacy option is included on the "fossil configuration pull"
command-line. And even then, "shun" configuration information cannot
be moved from older servers into newer clients - if you try the process
will fail with a database error. Hence, the best strategy is to upgrade
servers first, and then clients. Note that the 50 different Fossil
repositories that are hosted on the [http://www.fossil-scm.org/] server
have all already been upgraded.
Z 2f6223f9221d4b590b96ef1022216c93