Upgrading from Grouper v1.4.2
- You should get v1.5.0 versions of the Grouper API, Grouper UI, Grouper WS, Grouper Daemon, etc. You will need to merge configuration files and JARs. See the change log for more information. The rest of this document focuses on upgrading the database.
- There have been a lot of updates to the Grouper schema for v1.5.0. We now have more database tables for the attribute framework, changelog, and audit. Also the default group attributes (name, display_name, extension, display_extension, description) are now stored in the grouper_groups table rather than the grouper_attributes table. And we've also refactored how we handle effective memberships. Effective memberships are no longer stored in the grouper_memberships table, but are rather formed by joining a Membership row with a GroupSet row in the database.
- Before performing any upgrade steps, using your current v1.4.2 API, export your Grouper registry to an XML file. For instance -- ./bin/gsh.sh -xmlexport GrouperSystem backup.xml
- There are two ways you can upgrade. Both options are described below.
Upgrade Method 1
- This option is generally easier, but also more time consuming for large deployments.
- Make sure you have an XML backup as described above. And make sure the XML file is complete and there were no errors generated in your logs during the export.
- Drop all of the Grouper objects from your database
Using the 1.5.0 API, create the new database schema. To do this, run: gsh -registry -runscript For instance..
Use XML Import to import your Grouper registry using the backup you created. For instance..
Upgrade Method 2
Using the 1.5.0 API, perform a registry check using GSH to create an SQL file that will contain the DDL to update your database. To do this, run: gsh -registry -check For instance..
- In this example above, an SQL script called /srv/grouper/grouperDdl_20091114_13_16_01_466.sql was created.
- Review the script to make sure it looks okay. The script shouldn't be dropping or truncating any tables. However, it will drop and recreate views, some constraints, and some indexes.
- If using postgres, you might see some tables being backed up and recreated
- If using postgres, you should see foreign keys being dropped at the top of the script. If not, try setting the ddlutils.schema grouper.properties setting and run again. If you still dont see foreign keys being dropped at the top of the script, manually drop all foreign keys before running the script.
If you are okay with the SQL script, execute using GSH again. To do this, run: gsh -registry -runsqlfile /path/to/sql/file.sql For instance..
- If you script fails on:
- If you are upgrading from 1.4, you might have rows with null hibernate_version_number, and hibernate will give exception:
2010-02-26 11:46:12,649: [main] ERROR GrouperStartup.startup(113) - Couldnt startup grouper: java.lang.NullPointerException: at org.hibernate.type.LongType.next(LongType.java:56)
You should run this script:
At this point, your DDL has been upgraded to v1.5.0. However, due to restructing in how we handle effective memberships, there is one additional step that needs to be taken for Grouper to be able to find memberships in your database. Membership objects are now creating by joining the grouper_memberships table with the grouper_group_set table. The latter table is a new table and needs to be populating now. To do so, start up GSH and run the following: new edu.internet2.middleware.grouper.misc.AddMissingGroupSets().addAllMissingGroupSets() For instance..
- Note that when GroupSets are added, memberships are going to appear to the API as if they are new. So if configured, membership hooks will fire, memberships will be added to the changelog and lastMembershipChange (used by LDAPPC) will be updated for groups and stems. To avoid this, simply update the grouper.properties file before adding GroupSets. To disable membership hooks, you can comment out the property hooks.membership.class. To disable the changeLog, set changeLog.enabled to false. And to prevent updates to lastMembershipChange, set groups.updateLastMembershipTime and stems.updateLastMembershipTime to false. After the GroupSets are added, you can set those properties back to the way they were.
Depending on the number of groups, folders and effective memberships you have, there may be a large number of GroupSets created. One GroupSet is created for each field for each group and stem and one GroupSet is created for each membership where the member is a group. By default, each GroupSet that is created will print a line. For instance, if you have one folder called "etc" and one group called "etc:wheel", you will see output similar to the following.
And for each membership where the member is a group, you will see output similar to the following.
If you would like to prevent output from being printed to your screen, you can call the showResults(boolean) method on AddMissingGroupSets. For instance..
- After you are satisified with the upgrade, there are some backup columns and a backup table that were creating during the registry upgrade that you can remove. If you would like to remove those, do the following.
Configure your grouper.properties file to have those backup columns and table dropped.
Run gsh -registry -deep For instance..
Check the SQL file to make sure it's okay and then run the SQL file. For instance..