NAME

DiaColloDB::Upgrade::Base - DiaColloDB utilities: auto-magic upgrade: base class / API

SYNOPSIS

##========================================================================
## PRELIMINARIES

use DiaColloDB::Upgrade::Base;

##========================================================================
## API

$version = $CLASS_OR_OBJECT->toversion();
$bool    = $CLASS_OR_OBJECT->needed($coldb);
$bool    = $CLASS_OR_OBJECT->upgrade($coldb, \%info);
\%uinfo  = $CLASS_OR_OBJECT->uinfo($coldb?,%info);
$bool    = $CLASS_OR_OBJECT->updateHeader($coldb, \%extra_uinfo);

DESCRIPTION

DiaColloDB::Upgrade::Base provides an API specification and common base class for automatic upgrade packages used by the dcdb-upgrade.perl script via the DiaColloDB::Upgrade package.

API

toversion

$version = $CLASS_OR_OBJECT->toversion();

Returns default target version; default just returns $DiaColloDB::VERSION.

needed

$bool = $CLASS_OR_OBJECT->needed($coldb);

Returns true iff $coldb needs upgrade from the current package.

upgrade

$bool = $CLASS_OR_OBJECT->upgrade($coldb, \%info);

Performs upgrade in-place on $coldb, returns true on success.

uinfo

\%uinfo = $CLASS_OR_OBJECT->uinfo($coldb?,%extra_uinfo);

Returns a default upgrade-info %uinfo structure, conventions:

version_from => $vfrom,    ##-- source version (default='unknown')
version_to   => $vto,      ##-- target version (default=$CLASS_OR_OBJECT->_toversion)
timestamp    => $time,     ##-- timestamp (default=DiaColloDB::Utils::timestamp(time))
by           => $who,      ##-- user or script-name (default=$CLASS)
...          => ...,       ##-- additional data from %extra_uinfo

The returned %uinfo hash will be prepended onto the upgraded field of $coldb's header file.

updateHeader

$bool = $CLASS_OR_OBJECT->updateHeader($coldb, \%extra_uinfo);

Updates $coldb header by prepending the upgrade-info structure returned by $CLASS_OR_OBJECT->uinfo($coldb,%extra_uinfo) onto the $coldb->{upgraded} array and setting $coldb->{version} = $uninfo->{version_to} if its value is true.

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2015-2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.

SEE ALSO

dcdb-upgrade.perl(1), DiaColloDB::Upgrade(3pm), DiaColloDB(3pm), perl(1), ...