notes/repos_upgrade_HOWTO

HOW-TO:  svn repository upgrade procedure
=========================================
 $LastChangedDate$


WHO IS AFFECTED:
---------------

Anyone upgrading to svn 0.28 (or later) who has a repository created
with an earlier release.


PROBLEM:
-------

In revision (6752, /trunk) [August 16, 2003], the underlying database
schema for subversion repositories (libsvn_fs) was changed.  Thus, if
a 'new' libsvn_fs library tries to access an 'old' repository, you'll
see an error like:

   Expected version '2' of repository; found version '1'

   or

   svn: No repository found in '...URL...'

Or if you use an 'old' libsvn_fs library to access a 'new' repository,
you might see an error like:
  
   Expected version '1' of repository; found version '2'

   or

   svn: Malformed skeleton data
   svn: Malformed node-revision skeleton

This schema change became public in svn 0.28.  So if you're upgrading
a server to svn 0.28 or later, you need to convert your repository to
the new schema.


HOW TO UPGRADE YOUR REPOSITORY:
------------------------------

  1. Use an 'svnadmin' binary from release 0.27 (or older) to create a
     dumpfile of your repository:

        $ mv myrepos old-repos
        $ svnadmin dump old-repos > dumpfile

  2. Use an 'svnadmin' binary from release 0.28 (or newer) to load the
     dumpfile into a new repository:

        $ svnadmin create myrepos
        $ svnadmin load myrepos < dumpfile

     OR, if you're feeling saucy, you can do it all at once with a pipe:

        $ svnadmin-new create myrepos
        $ svnadmin-old dump old-repos | svnadmin-new load myrepos

  3. [OPTIONAL] Loading a dumpfile is both time- and disk-consuming,
     as it replays every commit.  After the load is complete, you may
     want to free up some disk space by removing unused BerkeleyDB
     logfiles:

        $ svnadmin list-unused-dblogs newrepos | xargs rm

  4. Don't forget to copy over any hook scripts (and DB_CONFIG, if you
     changed it) from the old to the new repository:

        $ cp old-repos/hooks/* repos/hooks/
        $ cp old-repos/db/DB_CONFIG repos/db/


WHY DID YOU CHANGE THE SCHEMA?
-----------------------------

Subversion is still pre-1.0, and thus constantly improving.  These
changes were planned long ago, and took a long time to complete.
They fix both efficiency and correctness problems in the database
code.

More tangible results of this change are:

  * 'svn log branch/foo.c' now shows the branch-creation as a real
    event in foo.c's history, even though foo.c itself was only
    *implicitly* copied when its parent got copied.

  * 'svn log -rX:Y' is doing less work.

  * Fixes bugs in 'svn log --strict'.

  * We have a new fs API for walking the history of a node using a
    cursor-like interface.

  * Internally, the mechanism for choosing copyids was broken.  (OK,
    that's not tangible, but a matter of correctness.)