Versions Compared

Old Version 34

changes.mady.by.user Benn Oshrin

Saved on

compared with

New Version Current

changes.mady.by.user Benn Oshrin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Warning
titleUpgrading Multiple Versions

It is not always possible to upgrade multiple versions in one step. When this is not the case, if you attempt to skip a critical release you will see this message when trying to update the database schema:

Cannot automatically upgrade past version x.y.z. Please upgrade to that version first.

You must download and upgrade successfully to the specified version. This is the list of versions that block upgrading:

If you are currently runningYou must upgrade to this releaseBefore being able to upgrade to this release
v0.9.3 or earlierv0.9.4v1.0.0
v0.9.4v1.0.0Any later release



Info
titleReview Installation Instructions

You should review the general installation instructions to check for any changes to minimum version (eg: minimum PHP version) and other requirements. 


Backup Your Database

While upgrading is usually a fairly straightforward process, from time to time fairly significant database changes are made. Efforts are made to make these changes transparent, but as a precaution you should create a backup of your database prior to upgrading in case you need to revert the upgrade.

Download New Source

Checkout the source as described in Registry Installation - Source.

...

For versions after v1.0.0, copy your local directory from your previous installation, or symlink to it.

  1. (warning) When upgrading to or past v2.0.0, before continuing you may need to create symlinks to Plugins you were previously using. For more details, see Upgrading Registry to v2.0.0.

For versions prior to v1.0.0, depending on how you set things up previously you will likely need to:

  1. Update app/tmp to point to your production tmp directory.
  2. Re-install your authentication configuration. (eg: On Apache, copy app/webroot/auth/login/.htaccess and app/webroot/auth/logout/.htaccess.
  3. Re-install your database configuration. (app/Config/database.php)
  4. If you updated app/Config/email.php, re-install that file as well.
  5. Copy app/Config/security.salt and app/Config/security.seed.
  6. Update your registry-source link to point to the new directory.
  7. Re-install your Shibboleth Embedded Discovery Service Plugin configuration, if in use.

Clear Caches

Info

When running the console steps under v0.9.4, you may notice deprecation messages like

Deprecated (16384): Validation::notEmpty() is deprecated.

These messages may be safely ignored, and will be addressed in a future release (CO-1119).

(warning) Regardless of version, update your registry-current link to point to the new directory.

Clear Caches

Various caches are maintained to improve performance, but can cause problems during upgrades. Clear existing caches prior to continuing.

Note

In order to avoid problems with file ownership, you should run console commands as the web server user. Otherwise, make make sure the cache directory (wherever app/tmp points to) and all of its subdirectories and files are writeable by the web server. chown -R and chgrp -R may be in order after running console commands.

Version 1.0.6 and Later

Use the clearcache command.

No Format
$ cd app
$ su -c "./Console/clearcache" ${APACHE_USER}
Done clearing caches

Version 1.0.5 and Earlier

Info

When running the console steps under v0.9.4, you may notice deprecation messages like

Deprecated (16384): Validation::notEmpty() is deprecated.

These messages may be safely ignored, and will be addressed in a future release (CO-1119).


No Format
$ cd app
$ su -c "./Console/cake cache" ${APACHE_USER}
[...]
Done clearing cache


Warning

If you do not see the "Done cleaning cache" message (without any errors) then the caches have not been cleared. If you do not have write permission to the cache directories, this command may fail without producing any output. If necessary, clear the caches manually, as described below.


Note

Sometimes the cache clearing fails due to "internal error", which is usually Cake being confused by cached models not matching the new code. In this case you will need to manually clear the cache. Remove the cache files, but leave the directory structure in place. Something like

Code Block
# rm tmp/cache/models/*
# rm tmp/cache/persistent/*


Update Database Schema

Generally, updating the database schema is required when upgrading COmanage Registry. You may need to run this command as a user that has permission to write to your tmp directory.

...

Note

If you see an error like the following when upgrading, it may indicate the caches were not properly cleared:. Try clearing the caches again (manually emptying the registry/cache directory as described above, if necessary), then try running upgradeVersion again.

No Format
Migrating address configurations
Error: SQLSTATE[42601]: Syntax error: 7 ERROR:  syntax error at or near "_ug094"
LINE 1: _ug094
Try clearing the caches again (manually emptying the registry/cache directory if necessary), then try running upgradeVersion again.
or
 No Format
Current version: 1.0.0
Target version: 1.0.2
Unknown version "1.0.2"
ERROR: Upgrade failed


 Info
titleUpdating May Throw Error
When upgrading the database schema, you may see "Possibly failed to update database schema" instead. In all likelihood, the database schema successfully updated. (CO-165)
...
The following list of tables can be dropped as of the listed version:
Once you upgrade to this version
You should drop these tables (if present)
Registry 0.8.2
cm_co_changelog_provisioner_exports
Registry 2.0.0cm_organizations
Registry 3.3.0
cm_co_service_tokens (but be sure to convert any tokens you wish to keep)
Registry 1
cm_co_service_token_settings
Registry 4.1.0cm_
organizations
password_reset_tokens
Version Specific Database Updates
Run the appropriate steps for the versions you are upgrading past AND to. For example, if you are upgrading from v0.8.2 to v0.9, you must run the upgrade steps for both v0.8.3 and v0.9.
...