=head1 CONSTANTS
-=over 4
+=over
+
+=item C<TABLES_FIRST>
+
+Because of L</"Referential Integrity">, certain tables must be created
+before other tables. L</ABSTRACT_SCHEMA> can't specify this, because
+it's a hash. So we specify it here. When calling C<get_table_list()>,
+these tables will be returned before the other tables.
+
+=cut
+
+use constant TABLES_FIRST => qw(
+ fielddefs
+ profiles
+);
=item C<SCHEMA_VERSION>
=back
+=head2 Referential Integrity
+
+Bugzilla::DB::Schema supports "foreign keys", a way of saying
+that "Column X may only contain values from Column Y in Table Z".
+For example, in Bugzilla, bugs.resolution should only contain
+values from the resolution.values field.
+
+It does this by adding an additional item to a column, called C<REFERENCES>.
+This is a hash with the following members:
+
+=over
+
+=item C<TABLE>
+
+The table the foreign key points at
+
+=item C<COLUMN>
+
+The column pointed at in that table.
+
+=item C<DELETE>
+
+What to do if the row in the parent table is deleted. Choices are
+C<RESTRICT> or C<CASCADE>.
+
+C<RESTRICT> means the deletion of the row in the parent table will
+be forbidden by the database if there is a row in I<this> table that
+still refers to it. This is the default, if you don't specify
+C<DELETE>.
+
+C<CASCADE> means that this row will be deleted along with that row.
+
+=item C<UPDATE>
+
+What to do if the value in the parent table is updated. It has the
+same choices as L</DELETE>, except it defaults to C<CASCADE>, which means
+"also update this column in this table."
+
+=back
+
+Note that not all our supported databases actually enforce C<RESTRICT>
+and C<CASCADE>, so don't depend on them.
+
=cut
use constant SCHEMA_VERSION => '2.00';
profiles_activity => {
FIELDS => [
- userid => {TYPE => 'INT3', NOTNULL => 1},
- who => {TYPE => 'INT3', NOTNULL => 1},
+ userid => {TYPE => 'INT3', NOTNULL => 1,
+ REFERENCES => {TABLE => 'profiles',
+ COLUMN => 'userid',
+ DELETE => 'CASCADE'}},
+ who => {TYPE => 'INT3', NOTNULL => 1,
+ REFERENCES => {TABLE => 'profiles',
+ COLUMN => 'userid'}},
profiles_when => {TYPE => 'DATETIME', NOTNULL => 1},
- fieldid => {TYPE => 'INT3', NOTNULL => 1},
+ fieldid => {TYPE => 'INT3', NOTNULL => 1,
+ REFERENCES => {TABLE => 'fielddefs',
+ COLUMN => 'id'}},
oldvalue => {TYPE => 'TINYTEXT'},
newvalue => {TYPE => 'TINYTEXT'},
],
=item C<get_type_ddl>
- Description: Public method to convert abstract (database-generic) field
- specifiers to database-specific data types suitable for use
- in a C<CREATE TABLE> or C<ALTER TABLE> SQL statment. If no
- database-specific field type has been defined for the given
- field type, then it will just return the same field type.
- Parameters: a hash or a reference to a hash of a field containing the
- following keys: C<TYPE> (required), C<NOTNULL> (optional),
- C<DEFAULT> (optional), C<PRIMARYKEY> (optional), C<REFERENCES>
- (optional)
- Returns: a DDL string suitable for describing a field in a
- C<CREATE TABLE> or C<ALTER TABLE> SQL statement
+=over
+
+=item B<Description>
+
+Public method to convert abstract (database-generic) field specifiers to
+database-specific data types suitable for use in a C<CREATE TABLE> or
+C<ALTER TABLE> SQL statment. If no database-specific field type has been
+defined for the given field type, then it will just return the same field type.
+
+=item B<Parameters>
+
+=over
+
+=item C<$def> - A reference to a hash of a field containing the following keys:
+C<TYPE> (required), C<NOTNULL> (optional), C<DEFAULT> (optional),
+C<PRIMARYKEY> (optional), C<REFERENCES> (optional)
+
+=back
+
+-item B<Returns>
+
+A DDL string suitable for describing a field in a C<CREATE TABLE> or
+C<ALTER TABLE> SQL statement
=cut
my $self = shift;
my $finfo = (@_ == 1 && ref($_[0]) eq 'HASH') ? $_[0] : { @_ };
-
my $type = $finfo->{TYPE};
die "A valid TYPE was not specified for this column." unless ($type);
$default = $self->{db_specific}->{$default};
}
- my $fkref = $self->{enable_references} ? $finfo->{REFERENCES} : undef;
my $type_ddl = $self->convert_type($type);
# DEFAULT attribute must appear before any column constraints
# (e.g., NOT NULL), for Oracle
$type_ddl .= " DEFAULT $default" if (defined($default));
$type_ddl .= " NOT NULL" if ($finfo->{NOTNULL});
$type_ddl .= " PRIMARY KEY" if ($finfo->{PRIMARYKEY});
- $type_ddl .= "\n\t\t\t\tREFERENCES $fkref" if $fkref;
return($type_ddl);
} #eosub--get_type_ddl
+
+# Used if you want to display the DDL to the user, as opposed to actually
+# use it in the database.
+sub get_display_ddl {
+ my ($self, $table, $column, $def) = @_;
+ my $ddl = $self->get_type_ddl($def);
+ if ($def->{REFERENCES}) {
+ $ddl .= $self->get_fk_ddl($table, $column, $def->{REFERENCES});
+ }
+ return $ddl;
+}
+
+sub get_fk_ddl {
+=item C<_get_fk_ddl>
+
+=over
+
+=item B<Description>
+
+Protected method. Translates the C<REFERENCES> item of a column into SQL.
+
+=item B<Params>
+
+=over
+
+=item C<$table> - The name of the table the reference is from.
+=item C<$column> - The name of the column the reference is from
+=item C<$references> - The C<REFERENCES> hashref from a column.
+
+=back
+
+Returns: SQL for to define the foreign key, or an empty string
+ if C<$references> is undefined.
+
+=cut
+
+ my ($self, $table, $column, $references) = @_;
+ return "" if !$references;
+
+ my $update = $references->{UPDATE} || 'CASCADE';
+ my $delete = $references->{DELETE} || 'RESTRICT';
+ my $to_table = $references->{TABLE} || die "No table in reference";
+ my $to_column = $references->{COLUMN} || die "No column in reference";
+ my $fk_name = $self->_get_fk_name($table, $column, $references);
+
+ return "\n CONSTRAINT $fk_name FOREIGN KEY ($column)\n"
+ . " REFERENCES $to_table($to_column)\n"
+ . " ON UPDATE $update ON DELETE $delete";
+}
+
+# Generates a name for a Foreign Key. It's separate from get_fk_ddl
+# so that certain databases can override it (for shorter identifiers or
+# other reasons).
+sub _get_fk_name {
+ my ($self, $table, $column, $references) = @_;
+ my $to_table = $references->{TABLE};
+ my $to_column = $references->{COLUMN};
+ return "fk_${table}_${column}_${to_table}_${to_column}";
+}
+
+sub _get_add_fk_sql {
+ my ($self, $table, $column, $new_def) = @_;
+
+ my $fk_string = $self->get_fk_ddl($table, $column, $new_def->{REFERENCES});
+ return ("ALTER TABLE $table ADD $fk_string");
+}
+
+sub _get_drop_fk_sql {
+ my ($self, $table, $column, $old_def) = @_;
+ my $fk_name = $self->_get_fk_name($table, $column, $old_def->{REFERENCES});
+
+ return ("ALTER TABLE $table DROP CONSTRAINT $fk_name");
+}
+
sub convert_type {
=item C<convert_type>
Description: Public method for discovering what tables should exist in the
Bugzilla database.
+
Parameters: none
- Returns: an array of table names
+
+ Returns: An array of table names. The tables specified
+ in L</TABLES_FIRST> will come first, in order. The
+ rest of the tables will be in random order.
=cut
my $self = shift;
- return(sort(keys %{ $self->{schema} }));
+ my %schema = %{$self->{schema}};
+ my @tables;
+ foreach my $table (TABLES_FIRST) {
+ push(@tables, $table);
+ delete $schema{$table};
+ }
+ push(@tables, keys %schema);
+ return @tables;
+}
-} #eosub--get_table_list
-#--------------------------------------------------------------------------
sub get_table_columns {
=item C<get_table_columns>
push(@ddl, $index_sql) if $index_sql;
}
+ my %fields = @{$self->{schema}{$table}{FIELDS}};
+ foreach my $col (keys %fields) {
+ my $def = $fields{$col};
+ if ($def->{REFERENCES}) {
+ push(@ddl, $self->_get_add_fk_sql($table, $col, $def));
+ }
+ }
+
push(@ddl, @{ $self->{schema}{$table}{DB_EXTRAS} })
if (ref($self->{schema}{$table}{DB_EXTRAS}));
push(@statements, "ALTER TABLE $table DROP PRIMARY KEY");
}
+ # If we went from not having an FK to having an FK
+ # XXX For right now, you can't change an FK's actual definition.
+ if (!$old_def->{REFERENCES} && $new_def->{REFERENCES}) {
+ push(@statements, $self->_get_add_fk_sql($table, $column, $new_def));
+ }
+ elsif ($old_def->{REFERENCES} && !$new_def->{REFERENCES}) {
+ push(@statements, $self->_get_drop_fk_sql($table, $column, $old_def));
+ }
+
return @statements;
}
$col_one->{TYPE} = uc($col_one->{TYPE});
$col_two->{TYPE} = uc($col_two->{TYPE});
- my @col_one_array = %$col_one;
- my @col_two_array = %$col_two;
+ # It doesn't work to compare the two REFERENCES items, because
+ # they look like 'HASH(0xaf3c434)' to diff_arrays--they'll never
+ # be equal.
+ my %col_one_def = %$col_one;
+ delete $col_one_def{REFERENCES};
+ my %col_two_def = %$col_two;
+ delete $col_two_def{REFERENCES};
+
+ my @col_one_array = %col_one_def;
+ my @col_two_array = %col_two_def;
my ($removed, $added) = diff_arrays(\@col_one_array, \@col_two_array);
- # If there are no differences between the arrays,
- # then they are equal.
- return !scalar(@$removed) && !scalar(@$added) ? 1 : 0;
+ # If there are no differences between the arrays, then they are equal.
+ my $defs_identical = !scalar(@$removed) && !scalar(@$added);
+
+ # If the basic definitions are identical, we still want to check
+ # if the two foreign key definitions are different.
+ my @fk_array_one = %{$col_one->{REFERENCES} || {}};
+ my @fk_array_two = %{$col_two->{REFERENCES} || {}};
+ my ($fk_removed, $fk_added) =
+ diff_arrays(\@fk_array_one, \@fk_array_two);
+ my $fk_identical = !scalar(@$fk_removed) && !scalar(@$fk_added);
+
+ return $defs_identical && $fk_identical ? 1 : 0;
}
}
}
+# This is used before adding a foreign key to a column, to make sure
+# that the database won't fail adding the key.
+sub check_references {
+ my ($table, $column, $foreign_table, $foreign_column) = @_;
+ my $dbh = Bugzilla->dbh;
+
+ my $bad_values = $dbh->selectcol_arrayref(
+ "SELECT DISTINCT $table.$column
+ FROM $table LEFT JOIN $foreign_table
+ ON $table.$column = $foreign_table.$foreign_column
+ WHERE $foreign_table.$foreign_column IS NULL");
+
+ if (@$bad_values) {
+ my $values = join(', ', @$bad_values);
+ print <<EOT;
+
+ERROR: There are invalid values for the $column column in the $table
+table. (These values do not exist in the $foreign_table table, in the
+$foreign_column column.)
+
+Before continuing with checksetup, you will need to fix these values,
+either by deleting these rows from the database, or changing the values
+of $column in $table to point to valid values in $foreign_table.$foreign_column.
+
+The bad values from the $table.$column column are:
+$values
+
+EOT
+ # I just picked a number above 2, to be considered "abnormal exit."
+ exit 3;
+ }
+}
+
# NOTE: This is NOT the function for general table updates. See
# update_table_definitions for that. This is only for the fielddefs table.
sub update_fielddefs_definition {
$dbh->bz_add_column('milestones', 'id',
{TYPE => 'MEDIUMSERIAL', NOTNULL => 1, PRIMARYKEY => 1});
+ # Referential Integrity begins here
+ check_references('profiles_activity', 'userid', 'profiles', 'userid');
+ $dbh->bz_alter_column('profiles_activity', 'userid',
+ {TYPE => 'INT3', NOTNULL => 1, REFERENCES =>
+ {TABLE => 'profiles', COLUMN => 'userid', DELETE => 'CASCADE'}});
+ check_references('profiles_activity', 'who', 'profiles', 'userid');
+ $dbh->bz_alter_column('profiles_activity', 'who',
+ {TYPE => 'INT3', NOTNULL => 1, REFERENCES =>
+ {TABLE => 'profiles', COLUMN => 'userid'}});
+ check_references('profiles_activity', 'fieldid', 'fielddefs', 'id');
+ $dbh->bz_alter_column('profiles_activity', 'fieldid',
+ {TYPE => 'INT3', NOTNULL => 1, REFERENCES =>
+ {TABLE => 'fielddefs', COLUMN => 'id'}});
+
################################################################
# New --TABLE-- changes should go *** A B O V E *** this point #
################################################################
projects / thirdparty / bugzilla.git / commitdiff
