=head1 NAME

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

=head1 SYNOPSIS

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

=head1 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 L<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 C<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 ;)

=head1 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 C<pg_dump> utility visible in your C<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 C<_global>) is dumped out to a local SQL file under F<metamodel/>.

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

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

    $ bin/restore-metamodel.pl

This script will read all the F<.sql> files under F<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 F<bin/restore-metamodel.pl>, just like this:

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

=head1 AUTHOR

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

=head1 SEE ALSO

L<openresty>, L<OpenResty::Spec::MetaModel>, L<OpenResty>.

