FS/FS/upgrade_journal.pm

   1 package FS::upgrade_journal;
   2
   3 use strict;
   4 use base qw( FS::Record );
   5 use FS::Record qw( qsearch qsearchs );
   6
   7 =head1 NAME
   8
   9 FS::upgrade_journal - Object methods for upgrade_journal records
  10
  11 =head1 SYNOPSIS
  12
  13   use FS::upgrade_journal;
  14
  15   $record = new FS::upgrade_journal \%hash;
  16   $record = new FS::upgrade_journal { 'column' => 'value' };
  17
  18   $error = $record->insert;
  19
  20   # Typical use case
  21   my $upgrade = 'rename_all_customers_to_Bob';
  22   if ( ! FS::upgrade_journal->is_done($upgrade) ) {
  23     ... # do the upgrade, then, if it succeeds
  24     FS::upgrade_journal->set_done($upgrade);
  25   }
  26
  27 =head1 DESCRIPTION
  28
  29 An FS::upgrade_journal object records an upgrade procedure that was run
  30 on the database.  FS::upgrade_journal inherits from FS::Record.  The
  31 following fields are currently supported:
  32
  33 =over 4
  34
  35 =item upgradenum - primary key
  36
  37 =item _date - unix timestamp when the upgrade was run
  38
  39 =item upgrade - string identifier for the upgrade procedure; must match /^\w+$/
  40
  41 =item status - either 'done' or 'failed'
  42
  43 =item statustext - any other message that needs to be recorded
  44
  45 =back
  46
  47 =head1 METHODS
  48
  49 =over 4
  50
  51 =item new HASHREF
  52
  53 Creates a new upgrade record.  To add it to the database, see L<"insert">.
  54
  55 Note that this stores the hash reference, not a distinct copy of the hash it
  56 points to.  You can ask the object for a copy with the I<hash> method.
  57
  58 =cut
  59
  60 # the new method can be inherited from FS::Record, if a table method is defined
  61
  62 sub table { 'upgrade_journal'; }
  63
  64 =item insert
  65
  66 Adds this record to the database.  If there is an error, returns the error,
  67 otherwise returns false.
  68
  69 =cut
  70
  71 # the insert method can be inherited from FS::Record
  72
  73 sub delete  { die "upgrade_journal records can't be deleted" }
  74 sub replace { die "upgrade_journal records can't be modified" }
  75
  76 =item check
  77
  78 Checks all fields to make sure this is a valid example.  If there is
  79 an error, returns the error, otherwise returns false.  Called by the insert
  80 and replace methods.
  81
  82 =cut
  83
  84 # the check method should currently be supplied - FS::Record contains some
  85 # data checking routines
  86
  87 sub check {
  88   my $self = shift;
  89
  90   if ( !$self->_date ) {
  91     $self->_date(time);
  92   }
  93
  94   my $error =
  95     $self->ut_numbern('upgradenum')
  96     || $self->ut_number('_date')
  97     || $self->ut_alpha('upgrade')
  98     || $self->ut_text('status')
  99     || $self->ut_textn('statustext')
 100   ;
 101   return $error if $error;
 102
 103   $self->SUPER::check;
 104 }
 105
 106 =back
 107
 108 =head1 CLASS METHODS
 109
 110 =over 4
 111
 112 =item is_done UPGRADE
 113
 114 Returns the upgrade entry with identifier UPGRADE and status 'done', if
 115 there is one.  This is an easy way to check whether an upgrade has been done.
 116
 117 =cut
 118
 119 sub is_done {
 120   my ($class, $upgrade) = @_;
 121   qsearch('upgrade_journal', { 'status' => 'done', 'upgrade' => $upgrade })
 122 }
 123
 124 =item set_done UPGRADE
 125
 126 Creates and inserts an upgrade entry with the current time, status 'done',
 127 and identifier UPGRADE.  Dies on error.
 128
 129 =cut
 130
 131 sub set_done {
 132   my ($class, $upgrade) = @_;
 133   my $new = $class->new({ 'status' => 'done', 'upgrade' => $upgrade });
 134   my $error = $new->insert;
 135   die $error if $error;
 136   $new;
 137 }
 138
 139
 140 =head1 BUGS
 141
 142 Despite how it looks, this is not currently suitable for use as a mutex.
 143
 144 =head1 SEE ALSO
 145
 146 L<FS::Record>, schema.html from the base documentation.
 147
 148 =cut
 149
 150 1;
 151