notes/repos_upgrade_HOWTO

   1
   2 HOW-TO:  svn repository upgrade procedure
   3 =========================================
   4  $LastChangedDate$
   5
   6
   7 WHO IS AFFECTED:
   8 ---------------
   9
  10 Anyone upgrading between versions of subversion that have different
  11 repository schemas.  Schema versions are as follows:
  12
  13     SUBVERSION VERSION NUMBER           SCHEMA VERSION
  14     -------------------------           --------------
  15     Up to and including 0.27            1
  16     0.28 - 0.33.1                       2
  17     0.34 - 1.3                          3
  18     (no released version used this)     4
  19     1.4 -                               5
  20
  21 If necessary you can see which schema version your repository is
  22 currently using by looking at the format file in the repository.
  23
  24 It should be noted that these changes are extremely rare.  Now that
  25 subversion has reached 1.0.0 our compatibility guarantees require
  26 forward and backward compatible repository formats for all patch
  27 releases and backward compatible for minor releases.  So until
  28 2.0.0 comes out there will be no change that should require a
  29 dump for upgrading to newer versions.
  30
  31 While Subversion does create version 5 repositories by default as of
  32 version 1.4, it still supports reading and writing version 3
  33 repositories for backwards compatibility.  Additionally, a pre-1.3
  34 client can communicate with a 1.4+ server accessing a version 5
  35 repository.
  36
  37
  38 PROBLEM:
  39 -------
  40
  41 At times during the development of subversion it has and will be
  42 necessary to change the underlying database schema for subversion
  43 repositories (libsvn_fs).  Thus, if a 'new' libsvn_fs library tries
  44 to access an 'old' repository, you'll see an error like:
  45
  46    Expected version '2' of repository; found version '1'
  47
  48    or
  49
  50    svn: No repository found in '...URL...'
  51
  52 Or if you use an 'old' libsvn_fs library to access a 'new' repository,
  53 you might see an error like:
  54
  55    Expected version '1' of repository; found version '2'
  56
  57    or
  58
  59    svn: Malformed skeleton data
  60    svn: Malformed node-revision skeleton
  61
  62 So if you're seeing an error like these you will need to upgrade or
  63 downgrade your repository version.
  64
  65
  66 HOW TO UPGRADE/DOWNGRADE YOUR REPOSITORY:
  67 ----------------------------------------
  68
  69   1. Use an 'svnadmin' binary from a release with the same schema version
  70      as your repository to create a dumpfile of your repository:
  71
  72         $ mv myrepos old-repos
  73         $ svnadmin dump old-repos > dumpfile
  74
  75   2. Use an 'svnadmin' binary from a release with the same schema version
  76      as you want your repository to have to load the dumpfile into a new
  77      repository:
  78
  79         $ svnadmin create myrepos
  80         $ svnadmin load myrepos < dumpfile
  81
  82      OR, if you're feeling saucy, you can do it all at once with a pipe:
  83
  84         $ svnadmin-new create myrepos
  85         $ svnadmin-old dump old-repos | svnadmin-new load myrepos
  86
  87      (If you are running at least version 1.4 and would like to make a
  88      format 3 repository, pass the --pre-1.4-compatible flag to
  89      "svnadmin create".)
  90
  91   3. [OPTIONAL] Loading a dumpfile is both time- and disk-consuming,
  92      as it replays every commit.  If your new repository is a BDB
  93      respository, then after the load is complete, you may want to
  94      free up some disk space by removing unused BerkeleyDB logfiles:
  95
  96         $ svnadmin list-unused-dblogs newrepos | xargs rm
  97
  98      Note: If you're using BerkeleyDB 4.2 or newer this will be done
  99      automatically for you, unless you've configured the repository
 100      not to behave this way.
 101
 102   4. Don't forget to copy over any hook scripts (and DB_CONFIG for BDB
 103      repositories, if you changed it) from the old to the new
 104      repository:
 105
 106         $ cp old-repos/hooks/* repos/hooks/
 107         $ cp old-repos/db/DB_CONFIG repos/db/
 108
 109
 110 WHY DID YOU CHANGE THE SCHEMA?
 111 -----------------------------
 112
 113 Subversion was still pre-1.0 when the changes that required schema
 114 versions 2 and 3 were made, and thus constantly improving.  These
 115 changes were planned, and took a long time to complete.  They fix both
 116 efficiency and correctness problems in the database code.
 117
 118 The change made in schema version 5 is just that the "db" part of the
 119 repository now has its own independent schema version file; this was
 120 used in Subversion 1.4 to support a new version of FSFS which
 121 compresses some of its data for better space usage.  However, we will
 122 continue to support schema version 3 throughout all of Subversion 1.x.
 123
 124 In the future it may be necessary to make changes to support new
 125 features.  But we will do so in a manner that is consistent with our
 126 compatibility guarantees.