head	1.2;
access;
symbols;
locks; strict;
comment	@# @;


1.2
date	2001.05.16.18.28.17;	author leonardr;	state dead;
branches;
next	1.1;

1.1
date	2001.05.16.16.35.24;	author leonardr;	state Exp;
branches;
next	;


desc
@@


1.2
log
@Moved document into migration directory.
@
text
@<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
 <head>
  <title>How to Use and Write Migration Scripts</title>
 </head>

<body>

<h1>How to Use and Write Migration Scripts</h1>

<p>Leonard Richardson &lt;leonardr at collab dot net&gt;<br>
May 16, 2001<br>
<small>$Id: migration.html,v 1.1 2001/05/16 16:35:24 leonardr Exp $</small>

<h2>Introduction</h2>

<p>The goal of Tigris' suite of migration scripts is to allow seamless
and in-place migration of data and database schema from previous
versions to later versions. Although the migration scripts are kept
under <code>helm/scripts/migrate/</code>, the scripts in that
directory will migrate an entire Tigris installation from one version
to another.

<h2>Terminology</h2>

<p>Tigris version numbers look like a.b.c. The incrementing of a
represents a "major release"; the incrementing of b a "minor release",
and the incrementing of c a "point release" or a "bugfix release".

<h2>The Golden Rule</h2>

<p>Every Tigris developer needs to follow this rule. It mostly applies
to developers who are changing database schemas, but any large change
may invoke it. If everyone follows this rule, life will be good.

<p><b>If you make any change which breaks the ability of an existing
Tigris installation to run on the most recent version of the code, you
are responsible for writing and testing a migration script which can
be run to bring a previous installation up to speed.</b>

<p>The rest of this document will explain the migration infrastructure
and show you how to follow this rule.

<h2><code>upgrade_tigris</code></h2>

<p><code>upgrade_tigris</code> is a master script; it runs multiple
other scripts. It takes as its arguments the current version of your
Tigris install and the version to which you want to upgrade the
install.

<p>If there are changes found in x.y which are not in x.y-1, the
directory <code>helm/scripts/migrate/x.y/</code> should contain any
migration scripts neccessary to take x.y-1 to x.y. Similarily, any
scripts that need to be run to bring an installation to point release
x.y.z should be in the directory
<code>helm/scripts/migrate/x.y.z/</code> (but see below).

<p>When you run <code>upgrade_tigris</code>, you specify the version
number of your installation and the version number to which you want
to upgrade. If you run <code>upgrade_tigris a.b.c x.y.z</code>,
<code>upgrade_tigris</code> will run scripts in all directories with
version numbers l.m.n such that a.b.c < l.m.n <= x.y.z. For example,
<code>upgrade_tigris 0.9.2 1.0.5</code> would run any scripts in
directories 1.0, 1.0.3, and 1.0.5, in ascending order; however, it
would not run any scripts in directories 1.0.8 or 0.9.2.

<p>A few directories have two version numbers, separated by a
dash. This is because certain old versions have two incoming paths
(for instance, 0.9.0 can be upgraded to 0.9.2, but 0.8.4 can also be
upgraded to 0.9.2). This practice is deprecated and should no longer
be followed. However, <code>upgrade_tigris</code> knows how to do the
right thing when there are multiple paths to a version.

<h2>Adding to and changing migration scripts</h2>

<p>All work requiring migration should initially be done on the HEAD
of the source tree. The new and changed migration scripts which
correspond to these changes should therefore be placed in the
directory <code>helm/scripts/migrate/x.y</code>, where x.y is the next
planned minor release. For example, if the minor version is currently
1.0, changes which require migration should be placed in the directory
<code>helm/scripts/migrate/1.1</code>.

<p>The same commit which makes a change that needs to be migrated
should also add to or change the current migration scripts. That is,
the HEAD should never be in a state which violates the Golden Rule
(ie. there should never be any changes not backed up by migration
scripts).

<p>If you later port a change from the HEAD of the tree to a branch
representing a point release, you may have to create a directory
corresponding to the version number of the point release. See the next
section for details. Remember to move the appropriate migration script
out of its old location, so that it doesn't get run twice.

<h2>Creating a new set of migration scripts</h2>

<p>Every migration directory needs to contain an executable script
called <code>migrate</code>, which takes care of any and all migration
duties for the version named by the directory. When you create a
directory, follow the most current idiom by copying the
<code>migrate</code> script from the most recent set of migration
scripts follow the current idiom. 

<p>The <code>migrate</code> script usually runs SQL scripts, as well
as more complex scripts in scripting languages. You may use whatever
tools you wish in your migration script, provided you do not create
new dependancies. Again, for examples, look at existing migration
scripts.

<h2>Worked Example</h2>

<p>Let's suppose that the most recent released version is 1.0, and
that the HEAD is what will become 1.1. We have the following
directories under <code>helm/scripts/migrate/</code>:

<ul>
<li>0.9.0
<li>0.9.2
<li>1.0
<li>1.0.4
<li>1.0.5
<li>1.1
</ul>

<p>Suppose you make a change to the HEAD which requires a change to
the database schema. Before committing the change, you need to add to
the scripts in the directory so that an upgrade to
1.1 will make your schema change.

<p>Suppose you then need to backport your change to the 1.0 branch in
preparation for the tagging of the upcoming 1.0.6 point release. You
would make whatever code changes were neccessary in the 1.0 branch,
and add (in the branch) a <code>1.0.6</code> directory. Add a
<code>migrate</code> script to the <code>1.0.6</code> directory, and
move the script or script fragment you originally had in the
<code>1.1</code> directory into 1.0.6. Then commit to the branch.
Immediately afterwards, make a 1.0.6 directory in the HEAD and reflect
your changes to the branch there.

</body>
</html>
@


1.1
log
@New document: How to Use and Write Migration Scripts. The migration script architecture has not quite caught up with this document, but it should soon.
@
text
@d13 1
a13 1
<small>$Id: migration.html,v 1.5 2001/03/13 02:09:08 leonardr Exp $</small>
@

