Sakai/OSPortfolio

ID #1041

How to migrate (conversion) from an older Sakai/OSP to a newer one?

So you're wondering how to go about upgrading your Sakai/OSPortfolio server...

Well, you'll need the updated code, of course. :)

Other than that, you'll need to upgrade your database schema as well -- when new features are added (or old cruft is mothballed) the database columns often change a bit to match, so your database will need some tender attention to bring it up to speed.

Here are the steps we recommend:

  1. Install the new version of Sakai/OSP in a new area of your directory tree (leaving the old one intact!)
  2. Shut down your current Tomcat (driving your instance of Sakai/OSP)
  3. Back up your current database!
  4. Create a new instance of the database, and that'll be the one you upgrade
  5. 'Restore' your backup information into the new database
  6. Run the appropriate CONVERSION scripts
  7. Configure the new server to use the updated database
  8. Start up the new Tomcat

That's it, in a nutshell.


Below, we flesh out those ideas a bit, showing -- by way of example -- and upgrade from version 2.0 to 2.4 (old database was "sakai20", new database will be "sakai24"). All this will happen on Linux, using MySQL...

Install the new version of Sakai/OSP in a new area of your directory tree (leaving the old one intact!)

You can find installation instructions here (look for "INSTALL GUIDE").

Shut down your current Tomcat (driving your instance of Sakai/OSP)

This one's easy: just call your $CATALINA_HOME/bin/shutdown.sh script. When you see $CATALINA_HOME/logs/catalina.out activity die off, and one of the last lines is something like "INFO: Stopping Coyote HTTP/1.1" then you know your server is completely down.

Back up your current database!

Take a full snapshot of your current (old) database -- the one you're migrating from (FROMVER):

TODAY=`date +%F`
FROMVER='20'
mysqldump sakai$FROMVER > sakai$FROMVER.$TODAY.sql

Create a new instance of the database, and that'll be the one you upgrade

Now you create a new database, which will become the version you're migrating to (TOVER):

TOVER='24'
cat <<EOF | sed -e s%TOVER%$TOVER%g | mysql

create database sakaiTOVER default character set utf8;
grant all on sakaiTOVER.* to sakaiuser@localhost identified by 'SekritPassword';
grant all on sakaiTOVER.* to sakaiuser@127.0.0.1 identified by 'SekritPassword';
EOF

For more details, see Create the Sakai database, being sure to substitute reasonable values to match your setup.

You'll use your own password, of course, both here and below...

'Restore' your backup information into the new database

With this, you'll have two exact copies of your current database. You can always return to the original setup if needed, in case you run into troubles upgrading the new one.

mysql -u sakaiuser -p sakai$TOVER < sakai$FROMVER.$TODAY.sql

Migrate to the new version

From the top level of your Sakai source tree:

cd sakai/reference/docs/conversion
ls -l

total 932
-rw-r--r-- 1 sakai 37477 2005-11-29 sakai_1_5-2_0_conversion.sql
-rw-r--r-- 1 sakai 36526 2006-06-16 sakai_1_5-2_0_mysql_conversion.sql
-rw-r--r-- 1 sakai 76242 2006-06-26 sakai_2_0-2_1_mysql_conversion.sql
-rw-r--r-- 1 sakai 77443 2006-06-26 sakai_2_0-2_1_oracle_conversion.sql
-rw-r--r-- 1 sakai 2891 2006-02-03 sakai_2_1_0-2_1_1_mysql_conversion.sql
-rw-r--r-- 1 sakai 2236 2006-01-26 sakai_2_1_0-2_1_1_oracle_conversion.sql
-rw-r--r-- 1 sakai 2868 2006-06-16 sakai_2_1_1-2_1_2_mysql_conversion.sql
-rw-r--r-- 1 sakai 2815 2006-06-16 sakai_2_1_1-2_1_2_oracle_conversion.sql
-rw-r--r-- 1 sakai 133590 2007-01-17 sakai_2_1_2-2_2_0_mysql_conversion.sql
-rw-r--r-- 1 sakai 136518 2007-01-17 sakai_2_1_2-2_2_0_oracle_conversion.sql
-rw-r--r-- 1 sakai 2703 2006-07-31 sakai_2_2_0-2_2_1_mysql_conversion.sql
-rw-r--r-- 1 sakai 2661 2006-07-31 sakai_2_2_0-2_2_1_oracle_conversion.sql
-rw-r--r-- 1 sakai 24239 2007-05-30 sakai_2_2_1-2_3_1_mysql_conversion.sql
-rw-r--r-- 1 sakai 22885 2007-05-30 sakai_2_2_1-2_3_1_oracle_conversion.sql
-rw-r--r-- 1 sakai 5999 2007-01-29 sakai_2_3_0-2_3_1_mysql_conversion.sql
-rw-r--r-- 1 sakai 6024 2007-01-23 sakai_2_3_0-2_3_1_oracle_conversion.sql
-rw-r--r-- 1 sakai 165177 2007-06-22 sakai_2_3_1-2_4_0_mysql_conversion.sql
-rw-r--r-- 1 sakai 163581 2007-05-21 sakai_2_3_1-2_4_0_oracle_conversion.sql

Here you'll use the scripts appropriate to your database server (MySQL and Oracle are the only two supported as of July 2007). You'll also need to migrate through the full set to get from your current version to the target version.

sakai_1_5-2_0_mysql_conversion.sql <== not needed
sakai_2_0-2_1_mysql_conversion.sql
sakai_2_1_0-2_1_1_mysql_conversion.sql
sakai_2_1_1-2_1_2_mysql_conversion.sql
sakai_2_1_2-2_2_0_mysql_conversion.sql
sakai_2_2_0-2_2_1_mysql_conversion.sql
sakai_2_2_1-2_3_1_mysql_conversion.sql
sakai_2_3_0-2_3_1_mysql_conversion.sql <== not needed
sakai_2_3_1-2_4_0_mysql_conversion.sql

To migrate, using our example here, from 2.0 to 2.4 on MySQL, we'd need to run all the scripts listed here (except for the two flagged in red), in sequence. That is, we first migrate from v2.0 to 2.1, then from 2.1.0 to 2.1.1, then to 2.1.2, then 2.2.0, then 2.3.1, and finally to 2.4.0.

Note that you may encounter errors along the migration path -- such as when an index is being created, that already exists. Check the comments in the source code to be sure which errors are expected, to minimize your surprises.

Configure the new server to use the updated database

Notably, in sakai.properties, you'll need to set the database connection parameters (and also confirm that your username and password are set properly, too):

# The username and password.
username@javax.sql.BaseDataSource=sakaiuser
password@javax.sql.BaseDataSource=SekritPassword

## MySQL settings - make sure to alter as appropriate
vendor@org.sakaiproject.db.api.SqlService=mysql
driverClassName@javax.sql.BaseDataSource=com.mysql.jdbc.Driver
hibernate.dialect=org.hibernate.dialect.MySQLDialect
url@javax.sql.BaseDataSource=jdbc:mysql://127.0.0.1:3306/sakai24?useUnicode=true&characterEncoding=UTF-8
validationQuery@javax.sql.BaseDataSource=select 1 from DUAL
defaultTransactionIsolationString@javax.sql.BaseDataSource=TRANSACTION_READ_COMMITTED

Make sure that the settings you specify here match exactly what you told mysql above, when you created the database and specified your username/password.

Start up your new Tomcat (driving your new instance of Sakai/OSP)

Simple: just call your $CATALINA_HOME/bin/startup.sh script. When you see something like "INFO: Server Startup in ##### ms" in $CATALINA_HOME/logs/catalina.out, then you know your server is ready for action.


Sakai is an open-source CLE (collaboration and learning environment) or LMS (learning management system); OSP is an electronic portfolio toolkit built into Sakai.

Categories for this entry

Last update: 2007-10-12 11:57
Author: will trillich
Revision: 1.2

Print this record Print this record
Send to a friend Send to a friend
Show this as PDF file Show this as PDF file
Export as XML-File Export as XML-File

Please rate this entry:

Average rating: 4.81 out of 5 (27 Votes )

completely useless 1 2 3 4 5 most valuable

You cannot comment on this entry