DiaColloDB::Upgrade::Base - DiaColloDB utilities: auto-magic upgrade: base class / API
##======================================================================== ## PRELIMINARIES use DiaColloDB::Upgrade::Base; ##======================================================================== ## API $up = $CLASS_OR_OBJECT->new($dbdir?, %opts); $pkg = $CLASS_OR_OBJECT->label(); $version = $up->toversion(); $bool = $up->needed(); $bool = $up->upgrade(); ##======================================================================== ## Backup & Revert $bool = $up->backup(); $dir = $up->backupdir(); $bool = $up->revert(); @files = $up->revert_created(); @files = $up->revert_updated(); ##======================================================================== ## Utilities \%hdr = $CLASS_OR_OBJECT->dbheader($dbdir?); \%uinfo = $up->uinfo($dbdir?,%info); $bool = $up->updateHeader(\%extra_uinfo, \%extra_header_data);
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.
$up = $CLASS_OR_OBJECT->new($dbdir?, %opts);
Create and return new upgrader-instance for the local DiaColloDB directory $dbdir. If $dbdir is specified, it is stored in $up->{dbdir} and its header is loaded to $up->{hdr}. Common %opts, %$up:
$dbdir
$up->{dbdir}
$up->{hdr}
backup => $bool, ##-- perform auto-backup? (default=1) keep => $bool, ##-- keep temporary files? (default=0) timestamp=> $stamp, ##-- timestamp of this upgrade operation (default:DiaColloDB::Utils::timestamp(time))
$pkg = $CLASS_OR_OBJECT->label();
Returns upgrade package name.
$version = $CLASS_OR_OBJECT->toversion();
Returns default target version; default just returns $DiaColloDB::VERSION. By convention, auto-applied upgrades use a target version with an all-zero final version component, e.g. 0.09.000 or 0.10.000.
$DiaColloDB::VERSION
0.09.000
0.10.000
$bool = $up->needed();
Returns true iff the upgrade $up needs to be applied to the local DiaColloDB index in $dbdir. Default implementation returns true iff $up->dbheader($dbdir)->{version} < $up->toversion(), using the version package to parse and compare version strings.
$up
$up->dbheader($dbdir)->{version} < $up->toversion()
$bool = $up->upgrade();
Performs upgrade in-place on the local DiaColloDB index in $up->{dbdir}, returns true on success.
$bool = $up->backup();
Backup any files we expect to change during upgrade() to $up->backupdir(). Subclasses should call this from their upgrade() method. Default implementation just backs up "$dbdir/header.json", emitting a warning if $up->{backup} is false.
$up->backupdir()
"$dbdir/header.json"
$up->{backup}
$dir = $up->backupdir();
Returns name of a backup directory for this upgrade. Default generates a reasonably unique directory name by concatenating the upgrader's label() suffix with the "wordlike" characters of $up->{timestamp}. For revert() to work, this directory name should be unique given $dbdir and the HASH-ref returned by the uinfo() method.
$up->{timestamp}
$bool = $up->revert();
Reverts a previous upgrade by $up on the local DB directory $up->{dbdir}. Default implementation deletes files returned by $up->revert_created() and copies files returned by $up->revert_updated() from $up->backupdir().
@files = $up->revert_created();
Returns list of files created by this upgrade, for use with default revert() implementation
@files = $up->revert_updated();
Returns list of files updated by this upgrade, for use with default revert() implementation.
\%hdr = $CLASS_OR_OBJECT->dbheader($dbdir?);
Reads, parses, and returns the header information $dbdir/header.json for the local DiaColloDB index in $dbdir. Wraps DiaColloDB::Utils::loadJsonFile(). Default implementation uses cached $CLASS_OR_OBJECT->{hdr} if available.
$dbdir/header.json
$CLASS_OR_OBJECT->{hdr}
\%uinfo = $up->uinfo($dbdir?,%info);
Returns a default upgrade-info %uinfo structure for this upgrade, conventions:
%uinfo
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, ##-- upgrade class or DiaColloDB::Upgrade:: suffix #... => ..., ##-- additional data from %info
$bool = $up->updateHeader(\%extra_uinfo, \%extra_header_data);
Updates DiaColloDB header "$up->{dbdir}/header.json" by prepending the upgrade-info structure returned by $up->uinfo($coldb,%extra_uinfo) onto the headers "upgraded" array and setting header "version" to $uinfo->{version_to} if that value is true. Subclasses may call this from their upgrade() method.
"$up->{dbdir}/header.json"
$up->uinfo($coldb,%extra_uinfo)
"upgraded"
$uinfo->{version_to}
Bryan Jurish <moocow@cpan.org>
Copyright (C) 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.
dcdb-upgrade.perl(1), DiaColloDB::Upgrade(3pm), DiaColloDB(3pm), perl(1), ...
To install DiaColloDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DiaColloDB
CPAN shell
perl -MCPAN -e shell install DiaColloDB
For more information on module installation, please visit the detailed CPAN module installation guide.