lib/SQL/Translator/Schema.pm

   1 package SQL::Translator::Schema;
   2
   3 # ----------------------------------------------------------------------
   4 # $Id$
   5 # ----------------------------------------------------------------------
   6 # Copyright (C) 2002-2009 SQLFairy Authors
   7 #
   8 # This program is free software; you can redistribute it and/or
   9 # modify it under the terms of the GNU General Public License as
  10 # published by the Free Software Foundation; version 2.
  11 #
  12 # This program is distributed in the hope that it will be useful, but
  13 # WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 # General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with this program; if not, write to the Free Software
  19 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  20 # 02111-1307  USA
  21 # -------------------------------------------------------------------
  22
  23 =pod
  24
  25 =head1 NAME
  26
  27 SQL::Translator::Schema - SQL::Translator schema object
  28
  29 =head1 SYNOPSIS
  30
  31   use SQL::Translator::Schema;
  32   my $schema   =  SQL::Translator::Schema->new(
  33       name     => 'Foo',
  34       database => 'MySQL',
  35   );
  36   my $table    = $schema->add_table( name => 'foo' );
  37   my $view     = $schema->add_view( name => 'bar', sql => '...' );
  38
  39
  40 =head1 DESCSIPTION
  41
  42 C<SQL::Translator::Schema> is the object that accepts, validates, and
  43 returns the database structure.
  44
  45 =head1 METHODS
  46
  47 =cut
  48
  49 use strict;
  50 use SQL::Translator::Schema::Constants;
  51 use SQL::Translator::Schema::Procedure;
  52 use SQL::Translator::Schema::Table;
  53 use SQL::Translator::Schema::Trigger;
  54 use SQL::Translator::Schema::View;
  55
  56 use SQL::Translator::Utils 'parse_list_arg';
  57
  58 use base 'SQL::Translator::Schema::Object';
  59 use vars qw[ $TABLE_ORDER $VIEW_ORDER $TRIGGER_ORDER $PROC_ORDER ];
  60
  61 __PACKAGE__->_attributes(qw/name database translator/);
  62
  63 # ----------------------------------------------------------------------
  64 sub as_graph {
  65
  66 =pod
  67
  68 =head2 as_graph
  69
  70 Returns the schema as an L<SQL::Translator::Schema::Graph> object.
  71
  72 =cut
  73     require  SQL::Translator::Schema::Graph;
  74
  75     my $self = shift;
  76
  77     return SQL::Translator::Schema::Graph->new(
  78         translator => $self->translator );
  79 }
  80
  81 # ----------------------------------------------------------------------
  82 sub as_graph_pm {
  83
  84 =pod
  85
  86 =head2 as_graph_pm
  87
  88 Returns a Graph::Directed object with the table names for nodes.
  89
  90 =cut
  91
  92     require Graph::Directed;
  93
  94     my $self = shift;
  95     my $g    = Graph::Directed->new;
  96
  97     for my $table ( $self->get_tables ) {
  98         my $tname  = $table->name;
  99         $g->add_vertex( $tname );
 100
 101         for my $field ( $table->get_fields ) {
 102             if ( $field->is_foreign_key ) {
 103                 my $fktable = $field->foreign_key_reference->reference_table;
 104
 105                 $g->add_edge( $fktable, $tname );
 106             }
 107         }
 108     }
 109
 110     return $g;
 111 }
 112
 113 # ----------------------------------------------------------------------
 114 sub add_table {
 115
 116 =pod
 117
 118 =head2 add_table
 119
 120 Add a table object.  Returns the new SQL::Translator::Schema::Table object.
 121 The "name" parameter is required.  If you try to create a table with the
 122 same name as an existing table, you will get an error and the table will
 123 not be created.
 124
 125   my $t1 = $schema->add_table( name => 'foo' ) or die $schema->error;
 126   my $t2 = SQL::Translator::Schema::Table->new( name => 'bar' );
 127   $t2    = $schema->add_table( $table_bar ) or die $schema->error;
 128
 129 =cut
 130
 131     my $self        = shift;
 132     my $table_class = 'SQL::Translator::Schema::Table';
 133     my $table;
 134
 135     if ( UNIVERSAL::isa( $_[0], $table_class ) ) {
 136         $table = shift;
 137         $table->schema($self);
 138     }
 139     else {
 140         my %args = @_;
 141         $args{'schema'} = $self;
 142         $table = $table_class->new( \%args )
 143           or return $self->error( $table_class->error );
 144     }
 145
 146     $table->order( ++$TABLE_ORDER );
 147
 148     # We know we have a name as the Table->new above errors if none given.
 149     my $table_name = $table->name;
 150
 151     if ( defined $self->{'tables'}{$table_name} ) {
 152         return $self->error(qq[Can't create table: "$table_name" exists]);
 153     }
 154     else {
 155         $self->{'tables'}{$table_name} = $table;
 156     }
 157
 158     return $table;
 159 }
 160
 161 # ----------------------------------------------------------------------
 162 sub drop_table {
 163
 164 =pod
 165
 166 =head2 drop_table
 167
 168 Remove a table from the schema. Returns the table object if the table was found
 169 and removed, an error otherwise. The single parameter can be either a table
 170 name or an C<SQL::Translator::Schema::Table> object. The "cascade" parameter
 171 can be set to 1 to also drop all triggers on the table, default is 0.
 172
 173   $schema->drop_table('mytable');
 174   $schema->drop_table('mytable', cascade => 1);
 175
 176 =cut
 177
 178     my $self        = shift;
 179     my $table_class = 'SQL::Translator::Schema::Table';
 180     my $table_name;
 181
 182     if ( UNIVERSAL::isa( $_[0], $table_class ) ) {
 183         $table_name = shift->name;
 184     }
 185     else {
 186         $table_name = shift;
 187     }
 188     my %args    = @_;
 189     my $cascade = $args{'cascade'};
 190
 191     if ( !exists $self->{'tables'}{$table_name} ) {
 192         return $self->error(qq[Can't drop table: $table_name" doesn't exist]);
 193     }
 194
 195     my $table = delete $self->{'tables'}{$table_name};
 196
 197     if ($cascade) {
 198
 199         # Drop all triggers on this table
 200         $self->drop_trigger()
 201           for ( grep { $_->on_table eq $table_name } @{ $self->{'triggers'} } );
 202     }
 203     return $table;
 204 }
 205
 206 # ----------------------------------------------------------------------
 207 sub add_procedure {
 208
 209 =pod
 210
 211 =head2 add_procedure
 212
 213 Add a procedure object.  Returns the new SQL::Translator::Schema::Procedure
 214 object.  The "name" parameter is required.  If you try to create a procedure
 215 with the same name as an existing procedure, you will get an error and the
 216 procedure will not be created.
 217
 218   my $p1 = $schema->add_procedure( name => 'foo' );
 219   my $p2 = SQL::Translator::Schema::Procedure->new( name => 'bar' );
 220   $p2    = $schema->add_procedure( $procedure_bar ) or die $schema->error;
 221
 222 =cut
 223
 224     my $self            = shift;
 225     my $procedure_class = 'SQL::Translator::Schema::Procedure';
 226     my $procedure;
 227
 228     if ( UNIVERSAL::isa( $_[0], $procedure_class ) ) {
 229         $procedure = shift;
 230         $procedure->schema($self);
 231     }
 232     else {
 233         my %args = @_;
 234         $args{'schema'} = $self;
 235         return $self->error('No procedure name') unless $args{'name'};
 236         $procedure = $procedure_class->new( \%args )
 237           or return $self->error( $procedure_class->error );
 238     }
 239
 240     $procedure->order( ++$PROC_ORDER );
 241     my $procedure_name = $procedure->name
 242       or return $self->error('No procedure name');
 243
 244     if ( defined $self->{'procedures'}{$procedure_name} ) {
 245         return $self->error(
 246             qq[Can't create procedure: "$procedure_name" exists] );
 247     }
 248     else {
 249         $self->{'procedures'}{$procedure_name} = $procedure;
 250     }
 251
 252     return $procedure;
 253 }
 254
 255 # ----------------------------------------------------------------------
 256 sub drop_procedure {
 257
 258 =pod
 259
 260 =head2 drop_procedure
 261
 262 Remove a procedure from the schema. Returns the procedure object if the
 263 procedure was found and removed, an error otherwise. The single parameter
 264 can be either a procedure name or an C<SQL::Translator::Schema::Procedure>
 265 object.
 266
 267   $schema->drop_procedure('myprocedure');
 268
 269 =cut
 270
 271     my $self       = shift;
 272     my $proc_class = 'SQL::Translator::Schema::Procedure';
 273     my $proc_name;
 274
 275     if ( UNIVERSAL::isa( $_[0], $proc_class ) ) {
 276         $proc_name = shift->name;
 277     }
 278     else {
 279         $proc_name = shift;
 280     }
 281
 282     if ( !exists $self->{'procedures'}{$proc_name} ) {
 283         return $self->error(
 284             qq[Can't drop procedure: $proc_name" doesn't exist]);
 285     }
 286
 287     my $proc = delete $self->{'procedures'}{$proc_name};
 288
 289     return $proc;
 290 }
 291
 292 # ----------------------------------------------------------------------
 293 sub add_trigger {
 294
 295 =pod
 296
 297 =head2 add_trigger
 298
 299 Add a trigger object.  Returns the new SQL::Translator::Schema::Trigger object.
 300 The "name" parameter is required.  If you try to create a trigger with the
 301 same name as an existing trigger, you will get an error and the trigger will
 302 not be created.
 303
 304   my $t1 = $schema->add_trigger( name => 'foo' );
 305   my $t2 = SQL::Translator::Schema::Trigger->new( name => 'bar' );
 306   $t2    = $schema->add_trigger( $trigger_bar ) or die $schema->error;
 307
 308 =cut
 309
 310     my $self          = shift;
 311     my $trigger_class = 'SQL::Translator::Schema::Trigger';
 312     my $trigger;
 313
 314     if ( UNIVERSAL::isa( $_[0], $trigger_class ) ) {
 315         $trigger = shift;
 316         $trigger->schema($self);
 317     }
 318     else {
 319         my %args = @_;
 320         $args{'schema'} = $self;
 321         return $self->error('No trigger name') unless $args{'name'};
 322         $trigger = $trigger_class->new( \%args )
 323           or return $self->error( $trigger_class->error );
 324     }
 325
 326     $trigger->order( ++$TRIGGER_ORDER );
 327
 328     my $trigger_name = $trigger->name or return $self->error('No trigger name');
 329     if ( defined $self->{'triggers'}{$trigger_name} ) {
 330         return $self->error(qq[Can't create trigger: "$trigger_name" exists]);
 331     }
 332     else {
 333         $self->{'triggers'}{$trigger_name} = $trigger;
 334     }
 335
 336     return $trigger;
 337 }
 338
 339 # ----------------------------------------------------------------------
 340 sub drop_trigger {
 341
 342 =pod
 343
 344 =head2 drop_trigger
 345
 346 Remove a trigger from the schema. Returns the trigger object if the trigger was
 347 found and removed, an error otherwise. The single parameter can be either a
 348 trigger name or an C<SQL::Translator::Schema::Trigger> object.
 349
 350   $schema->drop_trigger('mytrigger');
 351
 352 =cut
 353
 354     my $self          = shift;
 355     my $trigger_class = 'SQL::Translator::Schema::Trigger';
 356     my $trigger_name;
 357
 358     if ( UNIVERSAL::isa( $_[0], $trigger_class ) ) {
 359         $trigger_name = shift->name;
 360     }
 361     else {
 362         $trigger_name = shift;
 363     }
 364
 365     if ( !exists $self->{'triggers'}{$trigger_name} ) {
 366         return $self->error(
 367             qq[Can't drop trigger: $trigger_name" doesn't exist]);
 368     }
 369
 370     my $trigger = delete $self->{'triggers'}{$trigger_name};
 371
 372     return $trigger;
 373 }
 374
 375 # ----------------------------------------------------------------------
 376 sub add_view {
 377
 378 =pod
 379
 380 =head2 add_view
 381
 382 Add a view object.  Returns the new SQL::Translator::Schema::View object.
 383 The "name" parameter is required.  If you try to create a view with the
 384 same name as an existing view, you will get an error and the view will
 385 not be created.
 386
 387   my $v1 = $schema->add_view( name => 'foo' );
 388   my $v2 = SQL::Translator::Schema::View->new( name => 'bar' );
 389   $v2    = $schema->add_view( $view_bar ) or die $schema->error;
 390
 391 =cut
 392
 393     my $self       = shift;
 394     my $view_class = 'SQL::Translator::Schema::View';
 395     my $view;
 396
 397     if ( UNIVERSAL::isa( $_[0], $view_class ) ) {
 398         $view = shift;
 399         $view->schema($self);
 400     }
 401     else {
 402         my %args = @_;
 403         $args{'schema'} = $self;
 404         return $self->error('No view name') unless $args{'name'};
 405         $view = $view_class->new( \%args ) or return $view_class->error;
 406     }
 407
 408     $view->order( ++$VIEW_ORDER );
 409     my $view_name = $view->name or return $self->error('No view name');
 410
 411     if ( defined $self->{'views'}{$view_name} ) {
 412         return $self->error(qq[Can't create view: "$view_name" exists]);
 413     }
 414     else {
 415         $self->{'views'}{$view_name} = $view;
 416     }
 417
 418     return $view;
 419 }
 420
 421 # ----------------------------------------------------------------------
 422 sub drop_view {
 423
 424 =pod
 425
 426 =head2 drop_view
 427
 428 Remove a view from the schema. Returns the view object if the view was found
 429 and removed, an error otherwise. The single parameter can be either a view
 430 name or an C<SQL::Translator::Schema::View> object.
 431
 432   $schema->drop_view('myview');
 433
 434 =cut
 435
 436     my $self       = shift;
 437     my $view_class = 'SQL::Translator::Schema::View';
 438     my $view_name;
 439
 440     if ( UNIVERSAL::isa( $_[0], $view_class ) ) {
 441         $view_name = shift->name;
 442     }
 443     else {
 444         $view_name = shift;
 445     }
 446
 447     if ( !exists $self->{'views'}{$view_name} ) {
 448         return $self->error(qq[Can't drop view: $view_name" doesn't exist]);
 449     }
 450
 451     my $view = delete $self->{'views'}{$view_name};
 452
 453     return $view;
 454 }
 455
 456 # ----------------------------------------------------------------------
 457 sub database {
 458
 459 =pod
 460
 461 =head2 database
 462
 463 Get or set the schema's database.  (optional)
 464
 465   my $database = $schema->database('PostgreSQL');
 466
 467 =cut
 468
 469     my $self = shift;
 470     $self->{'database'} = shift if @_;
 471     return $self->{'database'} || '';
 472 }
 473
 474 # ----------------------------------------------------------------------
 475 sub is_valid {
 476
 477 =pod
 478
 479 =head2 is_valid
 480
 481 Returns true if all the tables and views are valid.
 482
 483   my $ok = $schema->is_valid or die $schema->error;
 484
 485 =cut
 486
 487     my $self = shift;
 488
 489     return $self->error('No tables') unless $self->get_tables;
 490
 491     for my $object ( $self->get_tables, $self->get_views ) {
 492         return $object->error unless $object->is_valid;
 493     }
 494
 495     return 1;
 496 }
 497
 498 # ----------------------------------------------------------------------
 499 sub get_procedure {
 500
 501 =pod
 502
 503 =head2 get_procedure
 504
 505 Returns a procedure by the name provided.
 506
 507   my $procedure = $schema->get_procedure('foo');
 508
 509 =cut
 510
 511     my $self = shift;
 512     my $procedure_name = shift or return $self->error('No procedure name');
 513     return $self->error(qq[Table "$procedure_name" does not exist])
 514       unless exists $self->{'procedures'}{$procedure_name};
 515     return $self->{'procedures'}{$procedure_name};
 516 }
 517
 518 # ----------------------------------------------------------------------
 519 sub get_procedures {
 520
 521 =pod
 522
 523 =head2 get_procedures
 524
 525 Returns all the procedures as an array or array reference.
 526
 527   my @procedures = $schema->get_procedures;
 528
 529 =cut
 530
 531     my $self       = shift;
 532     my @procedures =
 533       map  { $_->[1] }
 534       sort { $a->[0] <=> $b->[0] }
 535       map  { [ $_->order, $_ ] } values %{ $self->{'procedures'} };
 536
 537     if (@procedures) {
 538         return wantarray ? @procedures : \@procedures;
 539     }
 540     else {
 541         $self->error('No procedures');
 542         return wantarray ? () : undef;
 543     }
 544 }
 545
 546 # ----------------------------------------------------------------------
 547 sub get_table {
 548
 549 =pod
 550
 551 =head2 get_table
 552
 553 Returns a table by the name provided.
 554
 555   my $table = $schema->get_table('foo');
 556
 557 =cut
 558
 559     my $self = shift;
 560     my $table_name = shift or return $self->error('No table name');
 561     my $case_insensitive = shift;
 562     if ( $case_insensitive ) {
 563         $table_name = uc($table_name);
 564         foreach my $table ( keys %{$self->{tables}} ) {
 565                 return $self->{tables}{$table} if $table_name eq uc($table);
 566         }
 567         return $self->error(qq[Table "$table_name" does not exist]);
 568     }
 569     return $self->error(qq[Table "$table_name" does not exist])
 570       unless exists $self->{'tables'}{$table_name};
 571     return $self->{'tables'}{$table_name};
 572 }
 573
 574 # ----------------------------------------------------------------------
 575 sub get_tables {
 576
 577 =pod
 578
 579 =head2 get_tables
 580
 581 Returns all the tables as an array or array reference.
 582
 583   my @tables = $schema->get_tables;
 584
 585 =cut
 586
 587     my $self   = shift;
 588     my @tables =
 589       map  { $_->[1] }
 590       sort { $a->[0] <=> $b->[0] }
 591       map  { [ $_->order, $_ ] } values %{ $self->{'tables'} };
 592
 593     if (@tables) {
 594         return wantarray ? @tables : \@tables;
 595     }
 596     else {
 597         $self->error('No tables');
 598         return wantarray ? () : undef;
 599     }
 600 }
 601
 602 # ----------------------------------------------------------------------
 603 sub get_trigger {
 604
 605 =pod
 606
 607 =head2 get_trigger
 608
 609 Returns a trigger by the name provided.
 610
 611   my $trigger = $schema->get_trigger('foo');
 612
 613 =cut
 614
 615     my $self = shift;
 616     my $trigger_name = shift or return $self->error('No trigger name');
 617     return $self->error(qq[Table "$trigger_name" does not exist])
 618       unless exists $self->{'triggers'}{$trigger_name};
 619     return $self->{'triggers'}{$trigger_name};
 620 }
 621
 622 # ----------------------------------------------------------------------
 623 sub get_triggers {
 624
 625 =pod
 626
 627 =head2 get_triggers
 628
 629 Returns all the triggers as an array or array reference.
 630
 631   my @triggers = $schema->get_triggers;
 632
 633 =cut
 634
 635     my $self     = shift;
 636     my @triggers =
 637       map  { $_->[1] }
 638       sort { $a->[0] <=> $b->[0] }
 639       map  { [ $_->order, $_ ] } values %{ $self->{'triggers'} };
 640
 641     if (@triggers) {
 642         return wantarray ? @triggers : \@triggers;
 643     }
 644     else {
 645         $self->error('No triggers');
 646         return wantarray ? () : undef;
 647     }
 648 }
 649
 650 # ----------------------------------------------------------------------
 651 sub get_view {
 652
 653 =pod
 654
 655 =head2 get_view
 656
 657 Returns a view by the name provided.
 658
 659   my $view = $schema->get_view('foo');
 660
 661 =cut
 662
 663     my $self = shift;
 664     my $view_name = shift or return $self->error('No view name');
 665     return $self->error('View "$view_name" does not exist')
 666       unless exists $self->{'views'}{$view_name};
 667     return $self->{'views'}{$view_name};
 668 }
 669
 670 # ----------------------------------------------------------------------
 671 sub get_views {
 672
 673 =pod
 674
 675 =head2 get_views
 676
 677 Returns all the views as an array or array reference.
 678
 679   my @views = $schema->get_views;
 680
 681 =cut
 682
 683     my $self  = shift;
 684     my @views =
 685       map  { $_->[1] }
 686       sort { $a->[0] <=> $b->[0] }
 687       map  { [ $_->order, $_ ] } values %{ $self->{'views'} };
 688
 689     if (@views) {
 690         return wantarray ? @views : \@views;
 691     }
 692     else {
 693         $self->error('No views');
 694         return wantarray ? () : undef;
 695     }
 696 }
 697
 698 # ----------------------------------------------------------------------
 699 sub make_natural_joins {
 700
 701 =pod
 702
 703 =head2 make_natural_joins
 704
 705 Creates foriegn key relationships among like-named fields in different
 706 tables.  Accepts the following arguments:
 707
 708 =over 4
 709
 710 =item * join_pk_only
 711
 712 A True or False argument which determins whether or not to perform
 713 the joins from primary keys to fields of the same name in other tables
 714
 715 =item * skip_fields
 716
 717 A list of fields to skip in the joins
 718
 719 =back 4
 720
 721   $schema->make_natural_joins(
 722       join_pk_only => 1,
 723       skip_fields  => 'name,department_id',
 724   );
 725
 726 =cut
 727
 728     my $self         = shift;
 729     my %args         = @_;
 730     my $join_pk_only = $args{'join_pk_only'} || 0;
 731     my %skip_fields  =
 732       map { s/^\s+|\s+$//g; $_, 1 } @{ parse_list_arg( $args{'skip_fields'} ) };
 733
 734     my ( %common_keys, %pk );
 735     for my $table ( $self->get_tables ) {
 736         for my $field ( $table->get_fields ) {
 737             my $field_name = $field->name or next;
 738             next if $skip_fields{$field_name};
 739             $pk{$field_name} = 1 if $field->is_primary_key;
 740             push @{ $common_keys{$field_name} }, $table->name;
 741         }
 742     }
 743
 744     for my $field ( keys %common_keys ) {
 745         next if $join_pk_only and !defined $pk{$field};
 746
 747         my @table_names = @{ $common_keys{$field} };
 748         next unless scalar @table_names > 1;
 749
 750         for my $i ( 0 .. $#table_names ) {
 751             my $table1 = $self->get_table( $table_names[$i] ) or next;
 752
 753             for my $j ( 1 .. $#table_names ) {
 754                 my $table2 = $self->get_table( $table_names[$j] ) or next;
 755                 next if $table1->name eq $table2->name;
 756
 757                 $table1->add_constraint(
 758                     type             => FOREIGN_KEY,
 759                     fields           => $field,
 760                     reference_table  => $table2->name,
 761                     reference_fields => $field,
 762                 );
 763             }
 764         }
 765     }
 766
 767     return 1;
 768 }
 769
 770 # ----------------------------------------------------------------------
 771 sub name {
 772
 773 =pod
 774
 775 =head2 name
 776
 777 Get or set the schema's name.  (optional)
 778
 779   my $schema_name = $schema->name('Foo Database');
 780
 781 =cut
 782
 783     my $self = shift;
 784     $self->{'name'} = shift if @_;
 785     return $self->{'name'} || '';
 786 }
 787
 788 # ----------------------------------------------------------------------
 789 sub translator {
 790
 791 =pod
 792
 793 =head2 translator
 794
 795 Get the SQL::Translator instance that instantiated the parser.
 796
 797 =cut
 798
 799     my $self = shift;
 800     $self->{'translator'} = shift if @_;
 801     return $self->{'translator'};
 802 }
 803
 804 # ----------------------------------------------------------------------
 805 sub DESTROY {
 806     my $self = shift;
 807     undef $_ for values %{ $self->{'tables'} };
 808     undef $_ for values %{ $self->{'views'} };
 809 }
 810
 811 1;
 812
 813 # ----------------------------------------------------------------------
 814
 815 =pod
 816
 817 =head1 AUTHOR
 818
 819 Ken Youens-Clark E<lt>kclark@cpan.orgE<gt>.
 820
 821 =cut
 822