SL/DBUpgrade2.pm

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