Upgrading the Archiveopteryx schema

New releases of Archiveopteryx sometimes change the database schema, either to add new functionality or to fix bugs. The aox upgrade schema command checks that the database tables use the current schema revision, and show or execute the SQL commands necessary to update the tables.

You have to run upgrade schema whenever you upgrade or downgrade archiveopteryx. The command generally runs very quickly.

There are two command-line options, -n and -v. -n instructs aox to start the upgrade transaction and do everything that's needed, but then issue rollback instead of commit. -v instructs aox to show the queries it executes.

The most careful way to upgrade Archiveopteryx is to check that the upgrade will work, then stop the server, upgrade, and start. In this example, aox runs the installed version while ./bin/aox runs the new version.

# ./bin/aox show schema 75 (2.11 - needs to be upgraded) # ./bin/aox upgrade schema -n aox: Upgrading schema from revision 75 to revision 76. aox: 75-76: Miscellaneous cleanups. aox: Checking/granting privileges. aox: Schema upgraded to revision 76, but not committed.

At this point, you know that the schema upgrade works with your database, so you can stop the installed server.

# aox stop

You can now install the new version, e.g. with make install, and go on:

# aox upgrade schema aox: Upgrading schema from revision 75 to revision 76. aox: 75-76: Miscellaneous cleanups. aox: Checking/granting privileges. aox: Schema upgraded to revision 76. # aox start

In this example, aox upgrade schema did a few cleanups (schema 76 is like 75 minus one unused column plus one index), then it checked that all the right privileges are granted (and no wrong privileges).

Upgrading from newer versions

Starting with 3.0.7 and 3.1.0, it is also possible to downgrade the schema. If you run some later version and wish to downgrade to 3.0.7, you install 3.0.7 and run

# aox upgrade schema aox: Downgrading schema from revision 89 to revision 82. #

Unfortunately, you do not get any closer description of what's happening. 3.0.7 doesn't actually know what it's doing, it just invokes a series of pl/pgsql functions which future versions stored in the database while upgrading the schema.

In case of questions, please write to info@aox.org.

Relevant links

About this page

Last modified: 2010-11-19
Location: aox.org/aox/upgradeschema