##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

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

=cut

##========================================================================
## SYNOPSIS
=pod

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

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

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

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Upgrade::Base: API
=pod

=head2 API

=over 4

=item toversion

 $version = $CLASS_OR_OBJECT->toversion();

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

=item needed

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

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

=item upgrade

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

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

=item 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 C<upgraded> field of C<$coldb>'s
header file.

=item updateHeader

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

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

=back

=cut

##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 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.

=head1 SEE ALSO

L<dcdb-upgrade.perl(1)|dcdb-ugprade.perl>,
L<DiaColloDB::Upgrade(3pm)|DiaColloDB::Upgrade>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
