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