Subsections


2.6 Upgrading Scoop

Eventually a new point release will come out, or a new bug fix or feature is in CVS, and you want it. To upgrade Scoop, you have to first upgrade the code, then the database. Backing both up before the upgrade is always a good idea.

For a busy production site, you will probably want to run the new code on a testbed before upgrading the live site, and also to take the site down to prevent any discrepancies in the database between the testbed database and the live database. When upgrading the live site, Scoop's `safe mode' (4.21) will allow you to perform a final test of the changes while keeping the regular users out temporarily.


2.6.1 Backing up

The Scoop code can be very easily backed up by making a copy of all the .pm files, or by making a copy of the entire directory tree. This can be done while Scoop is running.

The database is backed up by using mysqldump as described below (substitute an appropriate mysql username and the name of your database). That will get you a text copy of the current database that can be read into a blank database the same way the original database was created.

$ mysqldump -u <dbuser> -p <scoopdb> > dump.sql

The only caveat is that if your somebody makes a change to the database while mysqldump is running (ie, posts a comment or anything) things could go wrong. A better plan is to take your Scoop site down while backing up and upgrading your database. Very large databases can take a long time to dump, so a replacement page indicating that you're upgrading would be a good idea.


2.6.2 Upgrading the code

When moving between numbered releases, the easiest thing to do is to download the release tarball and unpack it on top of the old version. This can be done while Scoop is running, because the code changes don't take effect until you force a recompile by stopping and then starting Apache. (Note: a restart will not work properly; Apache must fully terminate and start fresh to properly recompile Scoop.)

If you're tracking CVS, you can issue the following commands. If you've updated via CVS before, you can skip the login command.

$ cvs -d:pserver:anonymous@scoop.versionhost.com:/cvs/scoop login
password: anonymous
$ cvs update -P -d

This will check each file, fetch any changed ones, then merge them together, as well as fetching completely new files. Unless you make changes to the code, this should go without any problems. Even if you do, most likely it'll merge just fine. However, watch for any lines that start with ``C'', since that means there were conflicts during the merge. You'll want to open that file and search for ``<<<<<'', which will show you where the problem was. The old lines will be first, then following the ``========'' line will be the new lines, up until ``>>>>>>''. You'll need to either work them together, or remove one of them. Otherwise, Apache won't start when you try to get it running the new code.

If you had been running a numbered release and want to upgrade to the CVS version, the following commands will bring your code up to date.

$ cvs -d:pserver:anonymous@scoop.versionhost.com:/cvs/scoop login
password: anonymous
$ cvs update -A -r STABLE

This will update your code as with `tracking CVS', above, but will move you from the numbered release to the latest stable code. If you want to do new feature development or just feel like living dangerously, you can leave off the `-r STABLE' to get the unstable CURRENT code. CURRENT is not guaranteed to work, nor even to be compatible with STABLE.

Before you take the site down to upgrade the database, running ``apachectl configtest'' will tell you if Apache will start properly when you try to bring the site back up again. This can be done while Apache is running (and probably should, so you still have a working site while you're trying to sort out any problems).


2.6.3 Upgrading the database

Don't forget to back up your database first! That way if things go horribly wrong, you have something to revert to while you figure out what happened.

Some new features or bug fixes require changes to the database, as well. This almost never interferes with your customization, and more often takes the form of simply adding things. Generally, if a patch will change a block or box that may have been customized, it will check for changes and simply warn you to fix it yourself if you've changed it.

Unless you have done something truly bizarre to your database, you will want to use the upgrade-db.pl script. The script will prompt you for a username and password to the database, and whatever other information it needs. Occasionally, a table will be created or altered, so giving the script a username that has those permissions (such as root) is recommended.

It will also ask you where the patches are kept. If you're just tracking CVS, the default (scoop/struct/patch-files/current) is probably what you want. If you are upgrading from one numbered release to another, you will have to name those directories. If you are making a large upgrade, such as from 0.6 to 0.9, you will have to run the upgrade-db.pl script more than once: in this example, once for the directory 0.6-0.8 and once for the directory 0.8-0.9.

If there has been a point release since the last time you updated, and you're tracking CVS, you'll have to first tell the script to use the appropriate numbered directory and then current, to make sure it gets all the patches.

The script keeps track of which patches it's applied already in the database.

The patches must be applied in order, because they assume that all previous patches have been applied, and some alter information that was inserted by a previous patch.

If you want to upgrade the database by hand, you have to apply the patches one at a time in numeric order, using the command:

mysql -u dbuser -p scoopdb <patch-xx-patchname.sql

Where xx is the patch number. If there are any scripts with the same number as a patch, they should be run either before (script-xx-pre.pl) or after (script-xx-post.pl) as available. Each script will prompt you for the username and password as upgrade-db.pl does. If there is no script present, the patch alone is sufficient.


janra
2004-03-26