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