Projekt

Allgemein

Profil

« Zurück | Weiter » 

Revision 8d7674a0

Von Moritz Bunkus vor mehr als 12 Jahren hinzugefügt

  • ID 8d7674a0865360ccb0f2797ed558c05d20dc680a
  • Vorgänger 5c41c19b
  • Nachfolger 7b6a3af9

POD-Dokumentation zu SL::DBUpgrade2

Unterschiede anzeigen:

SL/DBUpgrade2.pm
436 436
}
437 437

  
438 438
1;
439
__END__
440

  
441
=pod
442

  
443
=encoding utf8
444

  
445
=head1 NAME
446

  
447
SL::DBUpgrade2 - Parse database upgrade files stored in
448
C<sql/Pg-upgrade2> and C<sql/Pg-upgrade2-auth> (and also in
449
C<SQL/Pg-upgrade>)
450

  
451
=head1 SYNOPSIS
452

  
453
  use SL::User;
454
  use SL::DBUpgrade2;
455

  
456
  # Apply outstanding updates to the authentication database
457
  my $scripts = SL::DBUpgrade2->new(
458
    form     => $::form,
459
    dbdriver => 'Pg',
460
    auth     => 1
461
  );
462
  $scripts->apply_admin_dbupgrade_scripts(1);
463

  
464
  # Apply updates to a user database
465
  my $scripts = SL::DBUpgrade2->new(
466
    form     => $::form,
467
    dbdriver => $::form->{dbdriver},
468
    auth     => 1
469
  );
470
  User->dbupdate2($form, $scripts->parse_dbupdate_controls);
471

  
472
=head1 OVERVIEW
473

  
474
Database upgrade files are used to upgrade the database structure and
475
content of both the authentication database and the user
476
databases. They're applied when a user logs in. As long as the
477
authentication database is not up to date users cannot log in in
478
general, and the admin has to log in first in order to get his
479
database updated.
480

  
481
Database scripts form a tree by specifying which upgrade file depends
482
on which other upgrade file. This means that such files are always
483
applied in a well-defined order.
484

  
485
Each script is run in a separate transaction. If a script fails the
486
current transaction is rolled back and the whole upgrade process is
487
stopped. The user/admin is required to fix the issue manually.
488

  
489
A list of applied upgrade scripts is maintained in a table called
490
C<schema_info> for the user database and C<auth.schema_info>) for the
491
authentication database. They contain the tags, the login name of the
492
user having applied the script and the timestamp when the script was
493
applied.
494

  
495
Database upgrade files come in two flavours: SQL files and Perl
496
files. For both there are control fields that determine the order in
497
which they're executed, what charset the scripts are written in
498
etc. The control fields are tag/value pairs contained in comments.
499

  
500
=head1 OLD UPGRADE FILES
501

  
502
The files in C<sql/Pg-upgrade> are so old that I don't bother
503
documenting them. They're handled by this class, too, but new files
504
are only created as C<Pg-upgrade2> files.
505

  
506
=head1 CONTROL FIELDS
507

  
508
=head2 SYNTAX
509

  
510
Control fields for Perl files:
511

  
512
  # @tag1: value1
513
  # @tag2: some more values
514
  sub do_stuff {
515
  }
516
  1;
517

  
518
Control fields for SQL files:
519

  
520
  -- @tag1: value1
521
  -- @tag2: some more values
522
  ALTER TABLE ...;
523

  
524
=head2 TAGS AND THEIR MEANING
525

  
526
The following tags are recognized:
527

  
528
=over 4
529

  
530
=item tag
531

  
532
The name for this file. The C<tag> is also used for dependency
533
resolution (see C<depends>).
534

  
535
This is mandatory.
536

  
537
=item description
538

  
539
A description presented to the user when the update is applied.
540

  
541
This is mandatory.
542

  
543
=item depends
544

  
545
A space-separated list of tags of scripts this particular script
546
depends on. All other upgrades listed in C<depends> will be applied
547
before the current one is applied.
548

  
549
=item charset
550

  
551
The charset this file uses. Defaults to C<ISO-8859-15> if missing.
552

  
553
=item priority
554

  
555
Ordering the scripts by their dependencies alone produces a lot of
556
groups of scripts that could be applied at the same time (e.g. if both
557
B and C depend only on A then B could be applied before C or the other
558
way around). This field determines the order inside such a
559
group. Scripts with lower priority fields are executed before scripts
560
with higher priority fields.
561

  
562
If two scripts have equal priorities then their tag name decides.
563

  
564
The priority defaults to 1000.
565

  
566
=back
567

  
568
=head1 FUNCTIONS
569

  
570
=over 4
571

  
572
=item C<apply_admin_dbupgrade_scripts $called_from_admin>
573

  
574
Applies all unapplied upgrade files to the authentication/admin
575
database. The parameter C<$called_from_admin> should be truish if the
576
function is called from the web interface and falsish if it's called
577
from e.g. a command line script like C<scripts/dbupgrade2_tool.pl>.
578

  
579
=item C<init %params>
580

  
581
Initializes the object. Is called directly from L<new> and should not
582
be called again.
583

  
584
=item C<new %params>
585

  
586
Creates a new object. Possible parameters are:
587

  
588
=over 4
589

  
590
=item path
591

  
592
Path to the upgrade files to parse. Required.
593

  
594
=item form
595

  
596
C<SL::Form> object to use. Required.
597

  
598
=item dbdriver
599

  
600
Name of the database driver. Currently only C<Pg> for PostgreSQL is
601
supported.
602

  
603
=item auth
604

  
605
Optional parameter defaulting to 0. If trueish then the scripts read
606
are the ones applying to the authentication database.
607

  
608
=back
609

  
610
=item C<parse_dbupdate_controls>
611

  
612
Parses all files located in C<path> (see L<new>), ananlyzes their
613
control fields, builds the tree, and signals errors if control fields
614
are missing/wrong (e.g. a tag name listed in C<depends> is not
615
found). Sets C<$Self-&gt;{all_controls}> to the list of database
616
scripts.
617

  
618
=item C<process_file $dbh, $filename, $version_or_control, $db_charset>
619

  
620
Applies a single database upgrade file. Calls L<process_perl_script>
621
for Perl update files and C<process_query> for SQL update
622
files. Requires an open database handle(C<$dbh>), the file name
623
(C<$filename>), a hash structure of the file's control fields as
624
produced by L<parse_dbupdate_controls> (C<$version_or_control>) and
625
the database charset (for on-the-fly charset recoding of the script if
626
required, C<$db_charset>).
627

  
628
Returns the result of the actual function called.
629

  
630
=item C<process_perl_script $dbh, $filename, $version_or_control, $db_charset>
631

  
632
Applies a single Perl database upgrade file. Requires an open database
633
handle(C<$dbh>), the file name (C<$filename>), a hash structure of the
634
file's control fields as produced by L<parse_dbupdate_controls>
635
(C<$version_or_control>) and the database charset (for on-the-fly
636
charset recoding of the script if required, C<$db_charset>).
637

  
638
Perl scripts are executed via L<eval>. If L<eval> returns falsish then
639
an error is expected. There are two special return values: If the
640
script returns C<1> then the update was successful. Return code C<2>
641
means "needs more interaction from the user; remove users/nologin and
642
end current upgrade process". All other return codes are fatal errors.
643

  
644
Inside the Perl script several local variables exist that can be used:
645

  
646
=over 4
647

  
648
=item $dbup_locale
649

  
650
A locale object for translating messages
651

  
652
=item $dbh
653

  
654
The database handle (inside a transaction).
655

  
656
=item $::form
657

  
658
The global C<SL::Form> object.
659

  
660
=back
661

  
662
A Perl script can actually implement queries that fail while
663
continueing the process by handling the transaction itself, e.g. with
664
the following function:
665

  
666
  sub do_query {
667
    my ($query, $may_fail) = @_;
668

  
669
    if (!$dbh->do($query)) {
670
      die($dbup_locale->text("Database update error:") . "<br>$msg<br>" . $DBI::errstr) unless $may_fail;
671
      $dbh->rollback();
672
      $dbh->begin_work();
673
    }
674
  }
675

  
676
=item C<process_query $dbh, $filename, $version_or_control, $db_charset>
677

  
678
Applies a single SQL database upgrade file. Requires an open database
679
handle(C<$dbh>), the file name (C<$filename>), a hash structure of the
680
ofile's control fields as produced by L<parse_dbupdate_controls>
681
(C<$version_or_control>) and the database charset (for on-the-fly
682
charset recoding of the script if required, C<$db_charset>).
683

  
684
=item C<sort_dbupdate_controls>
685

  
686
Sorts the database upgrade scripts according to their C<tag> and
687
C<priority> control fields. Returns a list of their hash
688
representations that can be applied in order.
689

  
690
=item C<unapplied_upgrade_scripts $dbh>
691

  
692
Returns a list if upgrade scripts (their internal hash representation)
693
that haven't been applied to a database yet. C<$dbh> is an open handle
694
to the database that is checked.
695

  
696
Requires that the scripts have been parsed.
697

  
698
=item C<update2_available $dbh>
699

  
700
Returns trueish if at least one upgrade script hasn't been applied to
701
a database yet. C<$dbh> is an open handle to the database that is
702
checked.
703

  
704
Requires that the scripts have been parsed.
705

  
706
=back
707

  
708
=head1 BUGS
709

  
710
Nothing here yet.
711

  
712
=head1 AUTHOR
713

  
714
Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
715

  
716
=cut

Auch abrufbar als: Unified diff