Upgrade from Tripal v1.1 to v2.1

The upgrade from Tripal v1.1 to 2.1 also includes a major upgrade of Drupal 6 to Drupal 7.  Therefore the upgrade process is more involved.

Step 1:  Backup your Site

Before proceeding with the upgade please review the site backup instructions to ensure you can restore your site if the upgrade fails.

Step 2: Export Custom View Integration

If you have  customized tables in the Views Integration functionality of Tripal then you will need to export any customized tables.  If you did not create customizations within the Views Integration then you can  skip this step. This step is necessary because of differences between Drupal Views 2.1 (used by Drupal 6) and Views 3.0 (used by Drupal 7).  Later these customizations will be imported after upgrade to Tripal 2.1.  To export your custom configurations, navigate to Administer -> Tripal Management -> Views Integration -> List of Integrated Tables.   Find the tables that you customized (will have a priority less than 9) and click the Export link beside each one.  A text box will appear containing a PHP-style array that contains the configuration setup.  Cut-and-paste this array into a file.  Export all tables you have customized.  If you forget to export a table or you prefer to skip this step you can reconfigure it later as needed.

Step 3:  Reset PostgreSQL's search_path variable

Prior to commencing the Drupal upgrade be sure that the Tripal user's PostgreSQL search_path is set to 'public'.   For example, check the $db_url variable in your Drupal 6 settings.php file.  There you will find the username and password that Drupal uses to connect to the database.  Within the PostgreSQL server, all users have a 'search path' that is used to help PostgreSQL locate tables within the database.  Some installations may have changed this search path.  However, before upgrading Drupal this must be reset back to the PostgreSQL default.  Execute the following command in PostgreSQL (using psql on the command-line or phppgadmin)  to do this:

ALTER USER [username] SET search_path TO public;

where [username] is the name of the user from the $db_url variable of the settings.php file.

If you did not set the search path you do not need to execute the statement above.   If you do not know if the search path was ever set then you should execute the command.

Step 4:  Upgrade Drupal 6 to Drupal 7

Note:  The following instructions are adapted  from the UPGRADE.TXT file that comes with the Drupal 7.x package:

  1. Before proceeding with the Drupal ugprade, be sure to check that all of the 3rd party modules that your site uses have been ported to Drupal 7.  These are modules that do not come with the base Drupal installation and were downloaded separately.  Sometimes, modules fail to be actively updated.  If a module is not available for Drupal 7 you'll have to consider alternative plans for functionality that the module may have provided.  Also, check to ensure the themes your site uses are also compatible with Drupal 7. You may decide at this point that you cannot upgrade your site, because needed modules or themes are not ready for Drupal 7.
  2. Place the site into maintenance mode.  This way visitors to the site will receive a message that the site is currently under maintenance.  You can easily do this with the following drush command:
    drush vset site_offline 1
  3. Change the default theme of the site to 'Garland' which is a theme that comes with the Drupal package.  The following drush command will do this:
    drush vset theme_default garland
  4. Update to the latest available version of Drupal 6.x.  This can be accomplished by using the following drush command:
    drush pm-update

    When this command is run it will first try to update all of the 3rd Party modules.  Once those are upgraded to the most recent level, you will need to re-run the above command to upgrade Drupal itself.   After Drupal 6 is updated to the most recent version you will be instructed to perform the database updates.  You can do this with Drush with this command:

    drush updatedb

    Once complete, if you re-run the 'drush pm-update' command it should show that all modules are "Up to date" and you can proceed with the upgrade

  5. Before continuing, it is a good idea (but not required) to create another backup of the Drupal database tables.  If anything goes awry during the upgrade process you can restore the database to its most updated state without repeating the steps above.  You do not need to backup the Chado schemas, just the public schema where Drupal tables are housed. If something does go wrong you can simply restore the Drupal schema.  If you want to take this precaution an example command to dump the public schema follows (alter it to fit your setup):
    pg_dump --no-owner --schema public -h [host] -U [user] [database] > [database].public.sql
  6. Disable all modules, including Tripal modules, except the Drupal core modules.  Be careful to not 'uninstall' the modules.  You can either use the Drupal interface to disable each module, or drush. To see a list of all modules issue the command:
    drush pm-list

    Then disable all of the modules that are not part of the 'Core' package:

    drush pm-disable [module name]

    There is no order requirement for disabling the modules.  If you know that you will not re-enable some modules for Drupal 7.x and you no longer need their data, then you can uninstall them. The following command can be used for disabling all of Tripal:

    drush pm-disable tripal_stock tripal_pub tripal_project tripal_phenotype 
    drush pm-disable tripal_organism tripal_natural_diversity tripal_library 
    drush pm-disable tripal_genetic tripal_featuremap tripal_feature tripal_db 
    drush pm-disable tripal_cv tripal_contact tripal_analysis tripal_bulk_loader 
    drush pm-disable tripal_core tripal
  7. Remove the Drupal 6.x files except the 'sites' directory and any other files or directories that were manually added.  The following command will remove only Drupal files and directories:
    cd [drupal dir]
    rm -rf CHANGELOG.txt  COPYRIGHT.txt  cron.php includes/ index.php INSTALL.mysql.txt 
    rm -rf INSTALL.pgsql.txt install.php INSTALL.txt LICENSE.txt MAINTAINERS.txt 
    rm -rf misc/ modules/ profiles/ scripts/ themes/ UPGRADE.txt xmlrpc.php update.php

    Rename the settings.php file simply to keep as a backup:

    mv ./sites/default/settings.php ./sites/default/settings-6.x.php

    If you have customizations added to the .htaccess or robots.txt files be sure to backup those files as a reference so you can restore customizations later.

  8. Download the most recent version of Drupal 7. It can be found here:  https://drupal.org/project/drupal.  Download into any directory where you can unpack it.  At the time of the last update of this document, Drupal 7.44 is the most recent version. Thus it can be downloaded and extracted in the following way:
    wget http://ftp.drupal.org/files/projects/drupal-7.44.tar.gz
    tar -zxvf drupal-7.44.tar.gz

    Next, copy the files into the directory where the previous Drupal installation was:

    cp -R drupal-7.44/* [drupal dir]
    cp -R drupal-7.44/.htaccess [drupal dir]

    Be sure to substitute the correct version number in the commands above and replace [drupal dir] with the location where Drupal will be installed.  

  9. If you had any previous modifications to the .htaccess or robots.txt file, reapply those modifications to the new files.
  10. Patch Drupal 7.  Sometimes an error occurs when upgrading Drupal's taxonomy infrastructure.  The following patch should be applied to fix this issue
    cd [drupal dir]
    wget  http://tripal.info/sites/default/files/book_pages/taxonomy_install.patch
    patch -p1 <  taxonomy_install.patch
  11. Copy the new sites/default/default.settings.php file to just sites/default/settings.php and set permissions so that the web user (typically www-data on an Ubuntu installation) can write to the file (depending on your setup, you may need to use sudo to make permission changes):
    cp [unpack dir]/sites/default/default.settings.php [drupal dir]/sites/default/settings.php
    cd [drupal dir]
    chmod g+rw sites/default/settings.php
    chgrp www-data sites/default/settings.php

    Next, we need to add our database connection information to the settings.php file.  Using your favorite editor, find the section of the settings.php file titled 'Database Settings' and scroll to line 213 where the $databses array is instantiated.  Add a new entry to the $databases array describing your connection details such that it appears as follows:

    $databases = array();
    $databases['default']['default'] = array(
        'driver' => 'pgsql',
        'database' => '[database]',
        'username' => '[user]',
        'password' => '[pass]',
        'host' => '[host]',
        'prefix' => '',

    [host] is the name of the server where the database resides
    [user] is the username used to log into PostgreSQL
    [pass] is the password
    [database] the name of the database.

    Save the file

  12. Navigate to your website and to the update.php page (e.g. http://[my drupal site]/update.php) and follow the instructions on the page.  Be sure that the page is titled Drupal database update. If the page title is Select an installation profile then you are being redirected to the installation script, which is not correct. If this occurs, check that the web user has access to the settings.php file and verify that your database connection details in the settings.php file are correct. 

    Follow the instructions as they appear on the update page.  This will perform the necessary database updates to upgrade Drupal 6 to Drupal 7 and may take some time to complete.   If you are unable to access update.php, then edit the settings.php file with a text editor, find the line that says:
         $update_free_access = FALSE;
     Change it into:
         $update_free_access = TRUE;
     Once the upgrade is done, $update_free_access must be reverted to FALSE.

  13. Tripal 2.1 now requires Views be installed and enabled and Views requires the Chaos Tools module.  Therefore, we must download the Drupal 7 version of each of these:
    drush pm-download views
    drush pm-download ctools

    The above commands will overwrite the Drupal 6 version if they were present.   Next apply any updates that these modules may have

    drush updatedb

    Now enable the modules

    drush pm-enable ctools views views_ui

    Follow these same steps for any other 3rd party module that you may require for your site.

  14. The Tripal modules must also be downloaded and updated.  To do this, delete the old Drupal 6 Tripal modules directories (be sure you have a backup before removing).  The following command will retrieve the Tripal 2.1 version:
    drush pm-download tripal-7.x-2.1-beta3
  15. Next, apply the Tripal updates:
    drush updatedb
  16. Now enable the Tripal modules.  First, we will enable the tirpal_core and tripal_views module.  
    drush pm-enable tripal_core
    drush pm-enable tripal_views
  17. After enabling tripal_views you may encountered the following warning:
     [site https://...] [TRIPAL NOTICE] [TRIPAL_VIEWS] DEPRECATED: Currently using tripal_views_handlers to store relationship for studyprop_feature => feature when you should be using tripal_views_joins.

    We can correct this by rebuilding the Views Integration setup. This stepis also required for Tripal to properly integrate with Views 3.0.  To do this, Go to Administration -> Tripal -> Views Integration  and click the link 'Delete All Integrations'.   After the integration has been deleted new default configurations will be created that are compatible with Views 3.0.  Now, you can import any of the intregrations that were exported in Step #2 at the beginning of the upgrade process.

  18. Next we can continue with the remaining Tripal modules.
    drush pm-enable tripal_db tripal_cv
    drush pm-enable tripal_organism
    drush pm-enable tripal_feature tripal_analysis tripal_stock tripal_contact
    drush pm-enable tripal_library tripal_project tripal_bulk_loader
    drush pm-enable tripal_pub tripal_featuremap tripal_phenotype
    drush pm-enable tripal_genetic tripal_natural_diversity

    Note:  you need not enable all Tripal modules, but only those you will use.

  19. Next download the Tripal 2.1 compatible Tripal extension module you will use.  Compatible Tripal 2.1 extension modules can be obtained via instructions for each one:  http://tripal.info/extensions?field_tripal_version_compatible__tid=7. Once downloaded, perform any updates that these modules may provide:
    drush updatedb

    And then enable them

    drush pm-enable [module name]
  20. With a new Drupal installation the administrative menu is presented along the top of the page, along with a shortcut bar just beneath it.  But, after an upgrade that menu is missing.  To turn that on, execute the following commands:
    drush pm-enable toolbar
    drush pm-enable shortcut
  21.  Ensure that $update_free_access is FALSE in settings.php in the event that you set it in step #10 above.
  22. Now that we've installed all of our modules we must clear the Drupal cache:
    drush cc all
  23. Using the admnistrative menu on the website, go to 'Reports' -> 'Status report' page and verify that everything is working as expected.
  24. Using the administrative menu on the website, go to 'People' and click the 'Permissions' tab.   Find the Tripal permissions, review them and set them as appropriate.
  25. A bug exists in Drupal related to the bytea data type in PostgreSQL.  At the writing of this document, a fix is not yet incorporated into Drupal, but a patch has been provided.  Execute the following commands to patch Drupal:
    cd [drupal dir]
    wget --no-check-certificat https://drupal.org/files/drupal.pgsql-bytea.27.patch
    patch -p1 < drupal.pgsql-bytea.27.patch
  26. There is also a bug in the Drupal Views 3.0 code that prevents Tripal's administrative views from functioning. The patch is provided within the tripal_veiws module.  To apply the patch execute the following:
    cd [drupal dir]/sites/all/modules/views
    patch -p1 < ../tripal/tripal_views/views-sql-compliant-three-tier-naming-1971160-22.patch
  27. Finally, the Views cache must be cleared.  This can be done simply by using the administrative menu to go to 'Structure' -> 'Views'.  Loading this page is enough to refresh the Views cache
  28. Re-enable your desired theme by  clicking the 'Appearance' link in the administrative menu and configuring appropriately.
  29. The Tripal theme, used in Tripal v1.1 (and previous versions), is no longer needed for Tripal and a Tripal 2.1 theme is not available.  Instead, Tripal themeing has been simplified and template files have been integrated into the Tripal package itself.  However, templates are backwards compatible.  If you had any customized Tripal templates, you can copy them into the directory of your default theme.  If you did not customize templates you can skip this step.  Afer copying your customized templates into the directory of your default theme, be sure to clear the Drupal cache (e.g. 'drush cc all).  If your templates worked for Tripal 1.1 then they should work for Tripal 2.1 (if they do not please contact the Tripal mailing list to let us know).  However, the templates for Tripal 2.1 are better at integrating with any default theme, so you may want to consider updating your templates to follow the style of the updated 2.1 templates.

Tripal is now upgraded to version 2.1!


Step 5:  Upgrade Extension Modules

In Concert with the release of Tripal v2.1 some of the functional annotation have also been released.   If you use the Tripal Blast Analysis, Tripal InterPro Analysis, Tripal KEGG Analysis or Tripal GO Analysis modules please consider upgrading those.  They can upgrade in the same way as any other Drupal module by using the following two commands:

drush pm-update
durhs updatedb

Note, the two steps above will upgrade all other 3rd party modules as well.


Step 6: (Optional) Upgrade Chado

Tripal v2.1 provides support for Chado v1.3.  It is not necessary to upgrade Chado as Tripal v2.1 supports both Chado v1.2 and v1.3.  But Chado v1.3 offers new tables and larger table sizes.  Before proceeding please review the following issues that you may encounter:

  • PostgreSQL version 9.1 is required to perform this upgrade. If your Tripal site uses an older version of PostgreSQL please upgrade before proceeding.
  • A major change between Chado v1.2 and v1.3 is that primary and foreign keys were upgraded from integers to big integers. If your site has custom materialized views that will hold data derived from fields then you may need to alter the views to change the fields from integers to big integers and repopulate those views. If you have not added any materialized views you can ignore this issue.
  • Custom PL/pgSQL functions that expect primary and foreign key fields to be integers will not work after the upgrade. Those functions will need to be altered to accept big integers. If you do not have any custom PL/pgSQL functions you can ignore this issue.
  • PostgreSQL Views that use fields that are converted to big integers will cause this upgrade to fail. You must first remove those views, perform the upgrade and then recreate them with the appropriate fields change to big integers. If you do not have custom PostgreSQL Views you can ignore this issue.
  • Several new tables were added to Chado v1.3. However, some groups have added these tables to their Chado v1.2 installation. The Tripal upgrader will alter the primary and foreign keys of those tables to be "bigints" if they already exist but will otherwise leave them the same. You should verify that any tables with Chado v1.3 names correctly match the v1.3 schema. Otherwise you may have problems using Tripal. If you have not added any Chado v1.3 tables to your Chado v1.2 database you can ignore this issue. These are the newly added tables: analysis_cvterm, analysis_dbxref, analysis_pub, analysis_relationship, contactprop, dbprop, feature_contact, featuremap_contact, featuremap_dbxref, featuremap_organism, featuremapprop, featureposprop, library_contact, library_expression, library_expressionprop, library_featureprop, library_relationship, library_relationship_pub, nd_experiment_analysis, organism_cvterm, organism_cvtermprop, organism_pub, organism_relationship, organismprop_pub, phenotypeprop, phylotreeprop, project_analysis, project_dbxref, project_feature, project_stock, pubauthor_contact, stock_feature, stock_featuremap, stock_library, stockcollection_db.

If you choose to upgrade Chado follow these steps:

  1. Navigate to Tripal → Setup Tripal → Install Chado Schema.  Select the radio button that reads 'Upgrade existing Chado v1.2 to v1.3 (no data is lost)
  2. Execute the job that was added:

    drush trp-run-jobs --username=administrator
  3. Return to the Tripal → Setup Tripal → Install Chado Schema page (or refresh if still there).  You should see that the current installed version of Chado is now 1.3.