From 8d7674a0865360ccb0f2797ed558c05d20dc680a Mon Sep 17 00:00:00 2001 From: Moritz Bunkus Date: Thu, 16 Aug 2012 10:50:40 +0200 Subject: [PATCH] POD-Dokumentation zu SL::DBUpgrade2 --- SL/DBUpgrade2.pm | 278 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 278 insertions(+) diff --git a/SL/DBUpgrade2.pm b/SL/DBUpgrade2.pm index ce9db4261..dfd5536b2 100644 --- a/SL/DBUpgrade2.pm +++ b/SL/DBUpgrade2.pm @@ -436,3 +436,281 @@ sub sort_dbupdate_controls { } 1; +__END__ + +=pod + +=encoding utf8 + +=head1 NAME + +SL::DBUpgrade2 - Parse database upgrade files stored in +C and C (and also in +C) + +=head1 SYNOPSIS + + use SL::User; + use SL::DBUpgrade2; + + # Apply outstanding updates to the authentication database + my $scripts = SL::DBUpgrade2->new( + form => $::form, + dbdriver => 'Pg', + auth => 1 + ); + $scripts->apply_admin_dbupgrade_scripts(1); + + # Apply updates to a user database + my $scripts = SL::DBUpgrade2->new( + form => $::form, + dbdriver => $::form->{dbdriver}, + auth => 1 + ); + User->dbupdate2($form, $scripts->parse_dbupdate_controls); + +=head1 OVERVIEW + +Database upgrade files are used to upgrade the database structure and +content of both the authentication database and the user +databases. They're applied when a user logs in. As long as the +authentication database is not up to date users cannot log in in +general, and the admin has to log in first in order to get his +database updated. + +Database scripts form a tree by specifying which upgrade file depends +on which other upgrade file. This means that such files are always +applied in a well-defined order. + +Each script is run in a separate transaction. If a script fails the +current transaction is rolled back and the whole upgrade process is +stopped. The user/admin is required to fix the issue manually. + +A list of applied upgrade scripts is maintained in a table called +C for the user database and C) for the +authentication database. They contain the tags, the login name of the +user having applied the script and the timestamp when the script was +applied. + +Database upgrade files come in two flavours: SQL files and Perl +files. For both there are control fields that determine the order in +which they're executed, what charset the scripts are written in +etc. The control fields are tag/value pairs contained in comments. + +=head1 OLD UPGRADE FILES + +The files in C are so old that I don't bother +documenting them. They're handled by this class, too, but new files +are only created as C files. + +=head1 CONTROL FIELDS + +=head2 SYNTAX + +Control fields for Perl files: + + # @tag1: value1 + # @tag2: some more values + sub do_stuff { + } + 1; + +Control fields for SQL files: + + -- @tag1: value1 + -- @tag2: some more values + ALTER TABLE ...; + +=head2 TAGS AND THEIR MEANING + +The following tags are recognized: + +=over 4 + +=item tag + +The name for this file. The C is also used for dependency +resolution (see C). + +This is mandatory. + +=item description + +A description presented to the user when the update is applied. + +This is mandatory. + +=item depends + +A space-separated list of tags of scripts this particular script +depends on. All other upgrades listed in C will be applied +before the current one is applied. + +=item charset + +The charset this file uses. Defaults to C if missing. + +=item priority + +Ordering the scripts by their dependencies alone produces a lot of +groups of scripts that could be applied at the same time (e.g. if both +B and C depend only on A then B could be applied before C or the other +way around). This field determines the order inside such a +group. Scripts with lower priority fields are executed before scripts +with higher priority fields. + +If two scripts have equal priorities then their tag name decides. + +The priority defaults to 1000. + +=back + +=head1 FUNCTIONS + +=over 4 + +=item C + +Applies all unapplied upgrade files to the authentication/admin +database. The parameter C<$called_from_admin> should be truish if the +function is called from the web interface and falsish if it's called +from e.g. a command line script like C. + +=item C + +Initializes the object. Is called directly from L and should not +be called again. + +=item C + +Creates a new object. Possible parameters are: + +=over 4 + +=item path + +Path to the upgrade files to parse. Required. + +=item form + +C object to use. Required. + +=item dbdriver + +Name of the database driver. Currently only C for PostgreSQL is +supported. + +=item auth + +Optional parameter defaulting to 0. If trueish then the scripts read +are the ones applying to the authentication database. + +=back + +=item C + +Parses all files located in C (see L), ananlyzes their +control fields, builds the tree, and signals errors if control fields +are missing/wrong (e.g. a tag name listed in C is not +found). Sets C<$Self->{all_controls}> to the list of database +scripts. + +=item C + +Applies a single database upgrade file. Calls L +for Perl update files and C for SQL update +files. Requires an open database handle(C<$dbh>), the file name +(C<$filename>), a hash structure of the file's control fields as +produced by L (C<$version_or_control>) and +the database charset (for on-the-fly charset recoding of the script if +required, C<$db_charset>). + +Returns the result of the actual function called. + +=item C + +Applies a single Perl database upgrade file. Requires an open database +handle(C<$dbh>), the file name (C<$filename>), a hash structure of the +file's control fields as produced by L +(C<$version_or_control>) and the database charset (for on-the-fly +charset recoding of the script if required, C<$db_charset>). + +Perl scripts are executed via L. If L returns falsish then +an error is expected. There are two special return values: If the +script returns C<1> then the update was successful. Return code C<2> +means "needs more interaction from the user; remove users/nologin and +end current upgrade process". All other return codes are fatal errors. + +Inside the Perl script several local variables exist that can be used: + +=over 4 + +=item $dbup_locale + +A locale object for translating messages + +=item $dbh + +The database handle (inside a transaction). + +=item $::form + +The global C object. + +=back + +A Perl script can actually implement queries that fail while +continueing the process by handling the transaction itself, e.g. with +the following function: + + sub do_query { + my ($query, $may_fail) = @_; + + if (!$dbh->do($query)) { + die($dbup_locale->text("Database update error:") . "
$msg
" . $DBI::errstr) unless $may_fail; + $dbh->rollback(); + $dbh->begin_work(); + } + } + +=item C + +Applies a single SQL database upgrade file. Requires an open database +handle(C<$dbh>), the file name (C<$filename>), a hash structure of the +ofile's control fields as produced by L +(C<$version_or_control>) and the database charset (for on-the-fly +charset recoding of the script if required, C<$db_charset>). + +=item C + +Sorts the database upgrade scripts according to their C and +C control fields. Returns a list of their hash +representations that can be applied in order. + +=item C + +Returns a list if upgrade scripts (their internal hash representation) +that haven't been applied to a database yet. C<$dbh> is an open handle +to the database that is checked. + +Requires that the scripts have been parsed. + +=item C + +Returns trueish if at least one upgrade script hasn't been applied to +a database yet. C<$dbh> is an open handle to the database that is +checked. + +Requires that the scripts have been parsed. + +=back + +=head1 BUGS + +Nothing here yet. + +=head1 AUTHOR + +Moritz Bunkus Em.bunkus@linet-services.deE + +=cut -- 2.20.1