SL/DBUpgrade2.pm

   1 package SL::DBUpgrade2;
   2
   3 use IO::File;
   4 use List::MoreUtils qw(any);
   5
   6 use SL::Common;
   7 use SL::DBUtils;
   8 use SL::Iconv;
   9
  10 use strict;
  11
  12 sub new {
  13   my $package = shift;
  14
  15   return bless({}, $package)->init(@_);
  16 }
  17
  18 sub init {
  19   my ($self, %params) = @_;
  20
  21   if ($params{auth}) {
  22     $params{path_suffix} = "-auth";
  23     $params{schema}      = "auth.";
  24   }
  25
  26   $params{path_suffix} ||= '';
  27   $params{schema}      ||= '';
  28   $params{path}          = "sql/" . $params{dbdriver} . "-upgrade2" . $params{path_suffix};
  29
  30   map { $self->{$_} = $params{$_} } keys %params;
  31
  32   return $self;
  33 }
  34
  35 sub path {
  36   $_[0]{path};
  37 }
  38
  39 sub parse_dbupdate_controls {
  40   $::lxdebug->enter_sub();
  41
  42   my ($self) = @_;
  43
  44   my $form   = $self->{form};
  45   my $locale = $::locale;
  46
  47   local *IN;
  48   my %all_controls;
  49
  50   my $path = $self->path;
  51
  52   foreach my $file_name (<$path/*.sql>, <$path/*.pl>) {
  53     next unless (open(IN, $file_name));
  54
  55     my $file = $file_name;
  56     $file =~ s|.*/||;
  57
  58     my $control = {
  59       "priority" => 1000,
  60       "depends"  => [],
  61     };
  62
  63     while (<IN>) {
  64       chomp();
  65       next unless (/^(--|\#)\s*\@/);
  66       s/^(--|\#)\s*\@//;
  67       s/\s*$//;
  68       next if ($_ eq "");
  69
  70       my @fields = split(/\s*:\s*/, $_, 2);
  71       next unless (scalar(@fields) == 2);
  72
  73       if ($fields[0] eq "depends") {
  74         push(@{$control->{"depends"}}, split(/\s+/, $fields[1]));
  75       } else {
  76         $control->{$fields[0]} = $fields[1];
  77       }
  78     }
  79
  80     next if ($control->{ignore});
  81
  82     $control->{charset} = $control->{charset} || $control->{encoding} || Common::DEFAULT_CHARSET;
  83
  84     if (!$control->{"tag"}) {
  85       _control_error($form, $file_name, $locale->text("Missing 'tag' field.")) ;
  86     }
  87
  88     if ($control->{"tag"} =~ /[^a-zA-Z0-9_\(\)\-]/) {
  89       _control_error($form, $file_name, $locale->text("The 'tag' field must only consist of alphanumeric characters or the carachters - _ ( )"))
  90     }
  91
  92     if (defined($all_controls{$control->{"tag"}})) {
  93       _control_error($form, $file_name, sprintf($locale->text("More than one control file with the tag '%s' exist."), $control->{"tag"}))
  94     }
  95
  96     if (!$control->{"description"}) {
  97       _control_error($form, $file_name, sprintf($locale->text("Missing 'description' field."))) ;
  98     }
  99
 100     $control->{"priority"}  *= 1;
 101     $control->{"priority"} ||= 1000;
 102     $control->{"file"}       = $file;
 103
 104     delete @{$control}{qw(depth applied)};
 105
 106     $all_controls{$control->{"tag"}} = $control;
 107
 108     close(IN);
 109   }
 110
 111   foreach my $control (values(%all_controls)) {
 112     foreach my $dependency (@{$control->{"depends"}}) {
 113       _control_error($form, $control->{"file"}, sprintf($locale->text("Unknown dependency '%s'."), $dependency)) if (!defined($all_controls{$dependency}));
 114     }
 115
 116     map({ $_->{"loop"} = 0; } values(%all_controls));
 117     _check_for_loops($form, $control->{"file"}, \%all_controls, $control->{"tag"});
 118   }
 119
 120   map({ _dbupdate2_calculate_depth(\%all_controls, $_->{"tag"}) }
 121       values(%all_controls));
 122
 123   $self->{all_controls} = \%all_controls;
 124
 125   $::lxdebug->leave_sub();
 126
 127   return $self;
 128 }
 129
 130 sub process_query {
 131   $::lxdebug->enter_sub();
 132
 133   my ($self, $dbh, $filename, $version_or_control, $db_charset) = @_;
 134
 135   my $form  = $self->{form};
 136   my $fh    = IO::File->new($filename, "r") or $form->error("$filename : $!\n");
 137   my $query = "";
 138   my $sth;
 139   my @quote_chars;
 140
 141   my $file_charset = Common::DEFAULT_CHARSET;
 142   while (<$fh>) {
 143     last if !/^--/;
 144     next if !/^--\s*\@(?:charset|encoding):\s*(.+)/;
 145     $file_charset = $1;
 146     last;
 147   }
 148   $fh->seek(0, SEEK_SET);
 149
 150   $db_charset ||= Common::DEFAULT_CHARSET;
 151
 152   $dbh->begin_work();
 153
 154   while (<$fh>) {
 155     $_ = SL::Iconv::convert($file_charset, $db_charset, $_);
 156
 157     # Remove DOS and Unix style line endings.
 158     chomp;
 159
 160     # remove comments
 161     s/--.*$//;
 162
 163     for (my $i = 0; $i < length($_); $i++) {
 164       my $char = substr($_, $i, 1);
 165
 166       # Are we inside a string?
 167       if (@quote_chars) {
 168         if ($char eq $quote_chars[-1]) {
 169           pop(@quote_chars);
 170         } elsif (length $quote_chars[-1] > 1
 171              &&  substr($_, $i, length $quote_chars[-1]) eq $quote_chars[-1]) {
 172           $i   += length $quote_chars[-1] - 1;
 173           $char = $quote_chars[-1];
 174           pop(@quote_chars);
 175         }
 176         $query .= $char;
 177
 178       } else {
 179         my ($tag, $tag_end);
 180         if (($char eq "'") || ($char eq "\"")) {
 181           push(@quote_chars, $char);
 182
 183         } elsif ($char eq '$'                                            # start of dollar quoting
 184              && ($tag_end  = index($_, '$', $i + 1)) > -1                # ends on same line
 185              && (do { $tag = substr($_, $i + 1, $tag_end - $i - 1); 1 }) # extract tag
 186              &&  $tag      =~ /^ (?= [A-Za-z_] [A-Za-z0-9_]* | ) $/x) {  # tag is identifier
 187           push @quote_chars, $char = '$' . $tag . '$';
 188           $i = $tag_end;
 189         } elsif ($char eq ";") {
 190
 191           # Query is complete. Send it.
 192
 193           $sth = $dbh->prepare($query);
 194           if (!$sth->execute()) {
 195             my $errstr = $dbh->errstr;
 196             $sth->finish();
 197             $dbh->rollback();
 198             $form->dberror("The database update/creation did not succeed. " .
 199                            "The file ${filename} containing the following " .
 200                            "query failed:<br>${query}<br>" .
 201                            "The error message was: ${errstr}<br>" .
 202                            "All changes in that file have been reverted.");
 203           }
 204           $sth->finish();
 205
 206           $char  = "";
 207           $query = "";
 208         }
 209
 210         $query .= $char;
 211       }
 212     }
 213
 214     # Insert a space at the end of each line so that queries split
 215     # over multiple lines work properly.
 216     if ($query ne '') {
 217       $query .= @quote_chars ? "\n" : ' ';
 218     }
 219   }
 220
 221   if (ref($version_or_control) eq "HASH") {
 222     $dbh->do("INSERT INTO " . $self->{schema} . "schema_info (tag, login) VALUES (" . $dbh->quote($version_or_control->{"tag"}) . ", " . $dbh->quote($form->{"login"}) . ")");
 223   } elsif ($version_or_control) {
 224     $dbh->do("UPDATE defaults SET version = " . $dbh->quote($version_or_control));
 225   }
 226   $dbh->commit();
 227
 228   $fh->close();
 229
 230   $::lxdebug->leave_sub();
 231 }
 232
 233 # Process a Perl script which updates the database.
 234 # If the script returns 1 then the update was successful.
 235 # Return code "2" means "needs more interaction; remove
 236 # users/nologin and end current request".
 237 # All other return codes are fatal errors.
 238 sub process_perl_script {
 239   $::lxdebug->enter_sub();
 240
 241   my ($self, $dbh, $filename, $version_or_control, $db_charset) = @_;
 242
 243   my $form         = $self->{form};
 244   my $fh           = IO::File->new($filename, "r") or $form->error("$filename : $!\n");
 245   my $file_charset = Common::DEFAULT_CHARSET;
 246
 247   if (ref($version_or_control) eq "HASH") {
 248     $file_charset = $version_or_control->{charset};
 249
 250   } else {
 251     while (<$fh>) {
 252       last if !/^--/;
 253       next if !/^--\s*\@(?:charset|encoding):\s*(.+)/;
 254       $file_charset = $1;
 255       last;
 256     }
 257     $fh->seek(0, SEEK_SET);
 258   }
 259
 260   my $contents = join "", <$fh>;
 261   $fh->close();
 262
 263   $db_charset ||= Common::DEFAULT_CHARSET;
 264
 265   my $iconv = SL::Iconv->new($file_charset, $db_charset);
 266
 267   $dbh->begin_work();
 268
 269   # setup dbup_ export vars
 270   my %dbup_myconfig = ();
 271   map({ $dbup_myconfig{$_} = $form->{$_}; } qw(dbname dbuser dbpasswd dbhost dbport dbconnect));
 272
 273   my $dbup_locale = $::locale;
 274
 275   my $result = eval($contents);
 276
 277   if (1 != $result) {
 278     $dbh->rollback();
 279     $dbh->disconnect();
 280   }
 281
 282   if (!defined($result)) {
 283     print $form->parse_html_template("dbupgrade/error",
 284                                      { "file"  => $filename,
 285                                        "error" => $@ });
 286     ::end_of_request();
 287   } elsif (1 != $result) {
 288     unlink("users/nologin") if (2 == $result);
 289     ::end_of_request();
 290   }
 291
 292   if (ref($version_or_control) eq "HASH") {
 293     $dbh->do("INSERT INTO " . $self->{schema} . "schema_info (tag, login) VALUES (" . $dbh->quote($version_or_control->{"tag"}) . ", " . $dbh->quote($form->{"login"}) . ")");
 294   } elsif ($version_or_control) {
 295     $dbh->do("UPDATE defaults SET version = " . $dbh->quote($version_or_control));
 296   }
 297   $dbh->commit();
 298
 299   $::lxdebug->leave_sub();
 300 }
 301
 302 sub process_file {
 303   my ($self, $dbh, $filename, $version_or_control, $db_charset) = @_;
 304
 305   if ($filename =~ m/sql$/) {
 306     $self->process_query($dbh, $filename, $version_or_control, $db_charset);
 307   } else {
 308     $self->process_perl_script($dbh, $filename, $version_or_control, $db_charset);
 309   }
 310 }
 311
 312 sub update_available {
 313   my ($self, $cur_version) = @_;
 314
 315   local *SQLDIR;
 316
 317   my $dbdriver = $self->{dbdriver};
 318   opendir SQLDIR, "sql/${dbdriver}-upgrade" || error("", "sql/${dbdriver}-upgrade: $!");
 319   my @upgradescripts = grep /${dbdriver}-upgrade-\Q$cur_version\E.*\.(sql|pl)$/, readdir SQLDIR;
 320   closedir SQLDIR;
 321
 322   return ($#upgradescripts > -1);
 323 }
 324
 325 sub update2_available {
 326   $::lxdebug->enter_sub();
 327
 328   my ($self, $dbh) = @_;
 329
 330   map { $_->{applied} = 0; } values %{ $self->{all_controls} };
 331
 332   my $sth = $dbh->prepare(qq|SELECT tag FROM | . $self->{schema} . qq|schema_info|);
 333   if ($sth->execute) {
 334     while (my ($tag) = $sth->fetchrow_array) {
 335       $self->{all_controls}->{$tag}->{applied} = 1 if defined $self->{all_controls}->{$tag};
 336     }
 337   }
 338   $sth->finish();
 339
 340   my $needs_update = any { !$_->{applied} } values %{ $self->{all_controls} };
 341
 342   $::lxdebug->leave_sub();
 343
 344   return $needs_update;
 345 }
 346
 347 sub unapplied_upgrade_scripts {
 348   my ($self, $dbh) = @_;
 349
 350   my @all_scripts = map { $_->{applied} = 0; $_ } $self->sort_dbupdate_controls;
 351
 352   my $query = qq|SELECT tag FROM | . $self->{schema} . qq|schema_info|;
 353   my $sth   = $dbh->prepare($query);
 354   $sth->execute || $self->{form}->dberror($query);
 355   while (my ($tag) = $sth->fetchrow_array()) {
 356     $self->{all_controls}->{$tag}->{applied} = 1 if defined $self->{all_controls}->{$tag};
 357   }
 358   $sth->finish;
 359
 360   return grep { !$_->{applied} } @all_scripts;
 361 }
 362
 363 sub apply_admin_dbupgrade_scripts {
 364   my ($self, $called_from_admin) = @_;
 365
 366   return 0 if !$self->{auth};
 367
 368   my $dbh               = $::auth->dbconnect;
 369   my @unapplied_scripts = $self->unapplied_upgrade_scripts($dbh);
 370
 371   return 0 if !@unapplied_scripts;
 372
 373   my $db_charset           = $::lx_office_conf{system}->{dbcharset} || Common::DEFAULT_CHARSET;
 374   $self->{form}->{login} ||= 'admin';
 375
 376   map { $_->{description} = SL::Iconv::convert($_->{charset}, $db_charset, $_->{description}) } values %{ $self->{all_controls} };
 377
 378   if ($called_from_admin) {
 379     $self->{form}->{title} = $::locale->text('Dataset upgrade');
 380     $self->{form}->header;
 381   }
 382
 383   print $self->{form}->parse_html_template("dbupgrade/header", { dbname => $::auth->{DB_config}->{db} });
 384
 385   foreach my $control (@unapplied_scripts) {
 386     $::lxdebug->message(LXDebug->DEBUG2(), "Applying Update $control->{file}");
 387     print $self->{form}->parse_html_template("dbupgrade/upgrade_message2", $control);
 388
 389     $self->process_file($dbh, "sql/$self->{dbdriver}-upgrade2-auth/$control->{file}", $control, $db_charset);
 390   }
 391
 392   print $self->{form}->parse_html_template("dbupgrade/footer", { is_admin => 1 }) if $called_from_admin;
 393
 394   return 1;
 395 }
 396
 397 sub _check_for_loops {
 398   my ($form, $file_name, $controls, $tag, @path) = @_;
 399
 400   push(@path, $tag);
 401
 402   my $ctrl = $controls->{$tag};
 403
 404   if ($ctrl->{"loop"} == 1) {
 405     # Not done yet.
 406     _control_error($form, $file_name, $::locale->text("Dependency loop detected:") . " " . join(" -> ", @path))
 407
 408   } elsif ($ctrl->{"loop"} == 0) {
 409     # Not checked yet.
 410     $ctrl->{"loop"} = 1;
 411     map({ _check_for_loops($form, $file_name, $controls, $_, @path); } @{ $ctrl->{"depends"} });
 412     $ctrl->{"loop"} = 2;
 413   }
 414 }
 415
 416 sub _control_error {
 417   my ($form, $file_name, $message) = @_;
 418
 419   $form = $::form;
 420   my $locale = $::locale;
 421
 422   $form->error(sprintf($locale->text("Error in database control file '%s': %s"), $file_name, $message));
 423 }
 424
 425 sub _dbupdate2_calculate_depth {
 426   $::lxdebug->enter_sub(2);
 427
 428   my ($tree, $tag) = @_;
 429
 430   my $node = $tree->{$tag};
 431
 432   return $::lxdebug->leave_sub(2) if (defined($node->{"depth"}));
 433
 434   my $max_depth = 0;
 435
 436   foreach $tag (@{$node->{"depends"}}) {
 437     _dbupdate2_calculate_depth($tree, $tag);
 438     my $value = $tree->{$tag}->{"depth"};
 439     $max_depth = $value if ($value > $max_depth);
 440   }
 441
 442   $node->{"depth"} = $max_depth + 1;
 443
 444   $::lxdebug->leave_sub(2);
 445 }
 446
 447 sub sort_dbupdate_controls {
 448   my $self = shift;
 449
 450   $self->parse_dbupdate_controls unless $self->{all_controls};
 451
 452   return sort { ($a->{depth} <=> $b->{depth}) || ($a->{priority} <=> $b->{priority}) || ($a->{tag} cmp $b->{tag}) } values %{ $self->{all_controls} };
 453 }
 454
 455 1;
 456 __END__
 457
 458 =pod
 459
 460 =encoding utf8
 461
 462 =head1 NAME
 463
 464 SL::DBUpgrade2 - Parse database upgrade files stored in
 465 C<sql/Pg-upgrade2> and C<sql/Pg-upgrade2-auth> (and also in
 466 C<SQL/Pg-upgrade>)
 467
 468 =head1 SYNOPSIS
 469
 470   use SL::User;
 471   use SL::DBUpgrade2;
 472
 473   # Apply outstanding updates to the authentication database
 474   my $scripts = SL::DBUpgrade2->new(
 475     form     => $::form,
 476     dbdriver => 'Pg',
 477     auth     => 1
 478   );
 479   $scripts->apply_admin_dbupgrade_scripts(1);
 480
 481   # Apply updates to a user database
 482   my $scripts = SL::DBUpgrade2->new(
 483     form     => $::form,
 484     dbdriver => $::form->{dbdriver},
 485     auth     => 1
 486   );
 487   User->dbupdate2($form, $scripts->parse_dbupdate_controls);
 488
 489 =head1 OVERVIEW
 490
 491 Database upgrade files are used to upgrade the database structure and
 492 content of both the authentication database and the user
 493 databases. They're applied when a user logs in. As long as the
 494 authentication database is not up to date users cannot log in in
 495 general, and the admin has to log in first in order to get his
 496 database updated.
 497
 498 Database scripts form a tree by specifying which upgrade file depends
 499 on which other upgrade file. This means that such files are always
 500 applied in a well-defined order.
 501
 502 Each script is run in a separate transaction. If a script fails the
 503 current transaction is rolled back and the whole upgrade process is
 504 stopped. The user/admin is required to fix the issue manually.
 505
 506 A list of applied upgrade scripts is maintained in a table called
 507 C<schema_info> for the user database and C<auth.schema_info>) for the
 508 authentication database. They contain the tags, the login name of the
 509 user having applied the script and the timestamp when the script was
 510 applied.
 511
 512 Database upgrade files come in two flavours: SQL files and Perl
 513 files. For both there are control fields that determine the order in
 514 which they're executed, what charset the scripts are written in
 515 etc. The control fields are tag/value pairs contained in comments.
 516
 517 =head1 OLD UPGRADE FILES
 518
 519 The files in C<sql/Pg-upgrade> are so old that I don't bother
 520 documenting them. They're handled by this class, too, but new files
 521 are only created as C<Pg-upgrade2> files.
 522
 523 =head1 CONTROL FIELDS
 524
 525 =head2 SYNTAX
 526
 527 Control fields for Perl files:
 528
 529   # @tag1: value1
 530   # @tag2: some more values
 531   sub do_stuff {
 532   }
 533   1;
 534
 535 Control fields for SQL files:
 536
 537   -- @tag1: value1
 538   -- @tag2: some more values
 539   ALTER TABLE ...;
 540
 541 =head2 TAGS AND THEIR MEANING
 542
 543 The following tags are recognized:
 544
 545 =over 4
 546
 547 =item tag
 548
 549 The name for this file. The C<tag> is also used for dependency
 550 resolution (see C<depends>).
 551
 552 This is mandatory.
 553
 554 =item description
 555
 556 A description presented to the user when the update is applied.
 557
 558 This is mandatory.
 559
 560 =item depends
 561
 562 A space-separated list of tags of scripts this particular script
 563 depends on. All other upgrades listed in C<depends> will be applied
 564 before the current one is applied.
 565
 566 =item charset
 567 =item encoding
 568
 569 The charset this file uses. Defaults to C<ISO-8859-15> if
 570 missing. Both terms are recognized.
 571
 572 =item priority
 573
 574 Ordering the scripts by their dependencies alone produces a lot of
 575 groups of scripts that could be applied at the same time (e.g. if both
 576 B and C depend only on A then B could be applied before C or the other
 577 way around). This field determines the order inside such a
 578 group. Scripts with lower priority fields are executed before scripts
 579 with higher priority fields.
 580
 581 If two scripts have equal priorities then their tag name decides.
 582
 583 The priority defaults to 1000.
 584
 585 =back
 586
 587 =head1 FUNCTIONS
 588
 589 =over 4
 590
 591 =item C<apply_admin_dbupgrade_scripts $called_from_admin>
 592
 593 Applies all unapplied upgrade files to the authentication/admin
 594 database. The parameter C<$called_from_admin> should be truish if the
 595 function is called from the web interface and falsish if it's called
 596 from e.g. a command line script like C<scripts/dbupgrade2_tool.pl>.
 597
 598 =item C<init %params>
 599
 600 Initializes the object. Is called directly from L<new> and should not
 601 be called again.
 602
 603 =item C<new %params>
 604
 605 Creates a new object. Possible parameters are:
 606
 607 =over 4
 608
 609 =item path
 610
 611 Path to the upgrade files to parse. Required.
 612
 613 =item form
 614
 615 C<SL::Form> object to use. Required.
 616
 617 =item dbdriver
 618
 619 Name of the database driver. Currently only C<Pg> for PostgreSQL is
 620 supported.
 621
 622 =item auth
 623
 624 Optional parameter defaulting to 0. If trueish then the scripts read
 625 are the ones applying to the authentication database.
 626
 627 =back
 628
 629 =item C<parse_dbupdate_controls>
 630
 631 Parses all files located in C<path> (see L<new>), ananlyzes their
 632 control fields, builds the tree, and signals errors if control fields
 633 are missing/wrong (e.g. a tag name listed in C<depends> is not
 634 found). Sets C<$Self-&gt;{all_controls}> to the list of database
 635 scripts.
 636
 637 =item C<process_file $dbh, $filename, $version_or_control, $db_charset>
 638
 639 Applies a single database upgrade file. Calls L<process_perl_script>
 640 for Perl update files and C<process_query> for SQL update
 641 files. Requires an open database handle(C<$dbh>), the file name
 642 (C<$filename>), a hash structure of the file's control fields as
 643 produced by L<parse_dbupdate_controls> (C<$version_or_control>) and
 644 the database charset (for on-the-fly charset recoding of the script if
 645 required, C<$db_charset>).
 646
 647 Returns the result of the actual function called.
 648
 649 =item C<process_perl_script $dbh, $filename, $version_or_control, $db_charset>
 650
 651 Applies a single Perl database upgrade file. Requires an open database
 652 handle(C<$dbh>), the file name (C<$filename>), a hash structure of the
 653 file's control fields as produced by L<parse_dbupdate_controls>
 654 (C<$version_or_control>) and the database charset (for on-the-fly
 655 charset recoding of the script if required, C<$db_charset>).
 656
 657 Perl scripts are executed via L<eval>. If L<eval> returns falsish then
 658 an error is expected. There are two special return values: If the
 659 script returns C<1> then the update was successful. Return code C<2>
 660 means "needs more interaction from the user; remove users/nologin and
 661 end current upgrade process". All other return codes are fatal errors.
 662
 663 Inside the Perl script several local variables exist that can be used:
 664
 665 =over 4
 666
 667 =item $dbup_locale
 668
 669 A locale object for translating messages
 670
 671 =item $dbh
 672
 673 The database handle (inside a transaction).
 674
 675 =item $::form
 676
 677 The global C<SL::Form> object.
 678
 679 =back
 680
 681 A Perl script can actually implement queries that fail while
 682 continueing the process by handling the transaction itself, e.g. with
 683 the following function:
 684
 685   sub do_query {
 686     my ($query, $may_fail) = @_;
 687
 688     if (!$dbh->do($query)) {
 689       die($dbup_locale->text("Database update error:") . "<br>$msg<br>" . $DBI::errstr) unless $may_fail;
 690       $dbh->rollback();
 691       $dbh->begin_work();
 692     }
 693   }
 694
 695 =item C<process_query $dbh, $filename, $version_or_control, $db_charset>
 696
 697 Applies a single SQL database upgrade file. Requires an open database
 698 handle(C<$dbh>), the file name (C<$filename>), a hash structure of the
 699 ofile's control fields as produced by L<parse_dbupdate_controls>
 700 (C<$version_or_control>) and the database charset (for on-the-fly
 701 charset recoding of the script if required, C<$db_charset>).
 702
 703 =item C<sort_dbupdate_controls>
 704
 705 Sorts the database upgrade scripts according to their C<tag> and
 706 C<priority> control fields. Returns a list of their hash
 707 representations that can be applied in order.
 708
 709 =item C<unapplied_upgrade_scripts $dbh>
 710
 711 Returns a list if upgrade scripts (their internal hash representation)
 712 that haven't been applied to a database yet. C<$dbh> is an open handle
 713 to the database that is checked.
 714
 715 Requires that the scripts have been parsed.
 716
 717 =item C<update2_available $dbh>
 718
 719 Returns trueish if at least one upgrade script hasn't been applied to
 720 a database yet. C<$dbh> is an open handle to the database that is
 721 checked.
 722
 723 Requires that the scripts have been parsed.
 724
 725 =back
 726
 727 =head1 BUGS
 728
 729 Nothing here yet.
 730
 731 =head1 AUTHOR
 732
 733 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
 734
 735 =cut