NAME

OpenResty::Spec::Upgrading - Upgrading to new versions of OpenResty server

SYNOPSIS

# upgrade metamodel
$ bin/openresty upgrade foo
$ bin/openresty upgrade

DESCRIPTION

New versions of OpenResty server often contain modifications to the metamodel which is the data structure used by the server itself. So in order to run a newer version of OpenResty atop the database used to work with an older one, it's often required to upgrade the metamodel first. Basically it's as easy as

$ bin/openresty upgrade

This command will upgrade both the global metamodel (in the _global schema) as well as the local metamodel in all the OpenResty accounts' schemas. (See OpenResty::Spec::MetaModel for more details about the MetaModel.)

It's also possible to upgrade just a specified OpenResty account without upgrading either the global metamodel or other accounts. Just give the account name to the "upgrade" command:

$ bin/openresty upgrade foo

where foo is the account which we want to upgrade exclusively.

Note that it's highly recommended to use only the CPAN release for upgrading. The SVN head might contain some half-done MetaModel changes which may corrupt you metamodel in the database later.

If you're a developer, however, the use of the SVN head is certainly encouraged ;)

Failure Recovery

In case the upgrading failed (it should not happen very often but we know that it could happen), one might have to fix the failure himself.

So, for production servers it's highly recommended to save your metamodels using the following command before upgrading (ensure you have the pg_dump utility visible in your PATH environment):

$ bin/save-metamodel.pl

A typycal output might be:

Dumping account _global to metamodel/_global.sql...
Dumping account agentzh to metamodel/agentzh.sql...
Dumping account onccf to metamodel/onccf.sql...
Dumping account tester to metamodel/tester.sql...
Dumping account tester2 to metamodel/tester2.sql...
Dumping account zjjresty to metamodel/zjjresty.sql...
Dumping account zjjresty2 to metamodel/zjjresty2.sql...

As you might have figured out, every account (including the global metamodel schema _global) is dumped out to a local SQL file under metamodel/.

If the metamodel/ directory already exists, bin/save-metamodel.pl will gracefully moved it to metamodel.old/ before dumping. But existing metamodel.old/ will be overritten.

In case upgrading failed, one can restore the previous working metamodel saved by the bin/save-metamodel.pl script by the following command (ensure you have the psql utility visible in your PATH environment):

$ bin/restore-metamodel.pl

This script will read all the .sql files under metamodel/ and overwrite the (broken) metamodel in the database.

For PgFarm backend, the procedure is very similar. The only difference is taht one may have to specify the hostname suffix to bin/restore-metamodel.pl, just like this:

$ bin/restore-metamodel.pl .foo.bar.com

AUTHOR

Agent Zhang (agentzh) <agentzh@yahoo.cn>

SEE ALSO

openresty, OpenResty::Spec::MetaModel, OpenResty.