1. Background and Purpose

This procedure addresses the requirement for testing upgrade when adding new features or changing existing features in the dataserver. It applies to all developers working on the dataserver product. It also contains notes for reviewers, suggesting things to look out for when reviewing changes.

Upgrade is nearly the first thing continuing customers see of a new dataserver, and typically one of the last things developers consider when adding new features to the product. Often in the past, it has happened that new features get checked in, or changes made that have upgrade implications, and the change break upgrade but the break is not caught until months after the fact. This makes it very difficult to identify exactly which changes caused the problem.

2. Considerations for Coders and Reviewers

If you are adding new server features, or are changing functional areas that could have upgrade considerations, you must test upgrade before your changes can be considered complete. Changes that affect upgrade include at least:

• Changes to system table DDL, including any new system tables or any tables made obsolete
• Changes to existing log records (but not newly added log records, since those records cannot be produced by older servers)
• Log records made obsolete
• Changes to page formats or layouts
• Newly added required databases

However, these are certainly not the only changes that might have upgrade implications. Consider each change carefully to decide whether it might affect upgrade. For example, if you are changing the way table statistics are stored within the server, your change will require upgrade: statistical data is changing form, whether or not any database DDL is changing. If a change could require an upgrade, or if you think it might, test upgrade. If you're not sure, test upgrade.

When testing upgrade, you must test at least upgrading from the oldest supported server release to the present version. Because of how upgrade works (by replaying a history of changes to various databases) testing from the oldest supported version is generally sufficient to test that version and all server versions after it.

Additionally, if you are changing data structures stored in log records, you must test upgrading all supported server versions to the present version, and your test must generate the log records you are changing so as to prove that the upgrade handles them correctly. This will be an issue for customers loading transaction logs from older version servers.

If you are a reviewer assigned to review any changes made to upgrade-sensitive files, please ensure that the author documents having run upgrade tests. Reviews do not pass until reviewers are satisfied that any upgrade considerations have been addressed and upgrade will pass successfully. The upgrade-sensitive files include at least (but again, are not limited to):

• generic/source/utils/intupgd.c
• generic/source/utils/cfg_options
• generic/source/access/logx*.c
• generic/source/demo/syscoldata.c
• generic/source/include/dbinfo.h
• generic/source/include/intupgd.h
• generic/upgrade/upgrade.c
• generic/upgrade/preupgrade.c

3. Steps

There are QuaSR tests for upgrade: see /calm/svr/qtst/utilities/upgrade, where there are README files explaining how to run them. Please note about those tests, though, that QuaSR may act in ways you don't expect when you try to test more than one old server version. In particular, we have seen it fail to note a changed "old" server version specified by your $UPGDFROM variable. If that happens, you may find it helpful to remove files stored in your ./.quasr directory. (Remember, though, that you must use quasr release to release your existing session before changing to a new source server version!)

Existing QuaSR upgrade tests may not be sufficient for your needs, particularly if you are testing how upgrade handles changed log records, so you may need to run tests manually. To do so, follow these steps:

1. If you are upgrading from server version 12.0 or later, set your $SYBASE_ASE and $SYBASE_OCS variables appropriately for the older version you're working with. For instance, for version 12.0, you should "setenv SYBASE_ASE ASE-12_0".
2. Build an old release master device using the old release directory. In general, old releases are available at /remote/releases/$PLATFORM/<version>. (Note that there will probably be quite a few versions available for a given platform, and not all of those directories will be fully populated.)
    
   So, for example, to build a 12.0 master device named "d_1200master" on Solaris, you might use:

   /remote/releases/solaris/rel120/ASE-12_0/bin/buildmaster -dd_1200master -s20484
   

   Note too that only server versions 12.0.x and older use buildmaster. Newer versions use ASE to build its own installation, specifying the installation's logical page size; for example:

   /remote/releases/solaris/rel125/ASE-12_5/bin/dataserver -dd_1250master -z2k -b100M
   

3. Boot the older version server. Again using the same examples, you might use these commands for the 12.0 and 12.5 servers, respectively:

   /remote/releases/solaris/rel120/ASE-12_0/bin/dataserver -dd_1200master
   /remote/releases/solaris/rel125/ASE-12_5/bin/dataserver -dd_1250master
   

4. Using that server, create a device for sybsystemprocs and run installmaster. If you have added upgrade steps that change user tables in any way, also create a test database and tables within that database, populating them with data that will exercise your upgrade steps. If you are testing log record changes, run any commands necessary to generate the log records you're testing.
5. Although not required, you may find it useful to run preupgrade and follow any recommendations it may make for preparing the older installation to be upgraded. This is particularly an issue where required database sizes may have changed, or where the new server may have added new reserved words. You can find preupgrade at:

   $SYBASE/$SYBASE_ASE/upgrade/preupgrade
   

   In this instance, $SYBASE_ASE is that of your new server, not the old one.
6. Shut the old server down.
7. If you changed them earlier, reset your $SYBASE_ASE and $SYBASE_OCS variables to be correct for the server version you will be testing.
8. Start your changed server.
9. Run upgrade by invoking the 'upgrade' binary and capture the output. For example:

   $SYBASE/upgrade/upgrade -P |& tee upgrade.log
   

Reviewers should reject the review or ask the author to fix the problems before passing the review if there are problems on upgrading from any of the old releases.

Procedure History