lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator.pm

   1 package DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator;
   2 use Moose;
   3
   4 # ABSTRACT: Manage your SQL and Perl migrations in nicely laid out directories
   5
   6 use autodie;
   7 use Carp qw( carp croak );
   8 use DBIx::Class::DeploymentHandler::Logger;
   9 use Log::Contextual qw(:log :dlog), -package_logger =>
  10   DBIx::Class::DeploymentHandler::Logger->new({
  11     env_prefix => 'DBICDH'
  12   });
  13
  14 use Method::Signatures::Simple;
  15 use Try::Tiny;
  16
  17 use SQL::Translator;
  18 require SQL::Translator::Diff;
  19
  20 require DBIx::Class::Storage;   # loaded for type constraint
  21 use DBIx::Class::DeploymentHandler::Types;
  22
  23 use File::Path 'mkpath';
  24 use File::Spec::Functions;
  25
  26 with 'DBIx::Class::DeploymentHandler::HandlesDeploy';
  27
  28 has ignore_ddl => (
  29   isa      => 'Bool',
  30   is       => 'ro',
  31   default  => undef,
  32 );
  33
  34 has schema => (
  35   isa      => 'DBIx::Class::Schema',
  36   is       => 'ro',
  37   required => 1,
  38 );
  39
  40 has storage => (
  41   isa        => 'DBIx::Class::Storage',
  42   is         => 'ro',
  43   lazy_build => 1,
  44 );
  45
  46 method _build_storage {
  47   my $s = $self->schema->storage;
  48   $s->_determine_driver;
  49   $s
  50 }
  51
  52 has sql_translator_args => (
  53   isa => 'HashRef',
  54   is  => 'ro',
  55   default => sub { {} },
  56 );
  57 has script_directory => (
  58   isa      => 'Str',
  59   is       => 'ro',
  60   required => 1,
  61   default  => 'sql',
  62 );
  63
  64 has databases => (
  65   coerce  => 1,
  66   isa     => 'DBIx::Class::DeploymentHandler::Databases',
  67   is      => 'ro',
  68   default => sub { [qw( MySQL SQLite PostgreSQL )] },
  69 );
  70
  71 has txn_wrap => (
  72   is => 'ro',
  73   isa => 'Bool',
  74   default => 1,
  75 );
  76
  77 has schema_version => (
  78   is => 'ro',
  79   isa => 'Str',
  80   lazy_build => 1,
  81 );
  82
  83 # this will probably never get called as the DBICDH
  84 # will be passing down a schema_version normally, which
  85 # is built the same way, but we leave this in place
  86 method _build_schema_version { $self->schema->schema_version }
  87
  88 method __ddl_consume_with_prefix($type, $versions, $prefix) {
  89   my $base_dir = $self->script_directory;
  90
  91   my $main    = catfile( $base_dir, $type      );
  92   my $common  =
  93     catfile( $base_dir, '_common', $prefix, join q(-), @{$versions} );
  94
  95   my $dir;
  96   if (-d $main) {
  97     $dir = catfile($main, $prefix, join q(-), @{$versions})
  98   } else {
  99     if ($self->ignore_ddl) {
 100       return []
 101     } else {
 102       croak "$main does not exist; please write/generate some SQL"
 103     }
 104   }
 105
 106   my %files;
 107   try {
 108      opendir my($dh), $dir;
 109      %files =
 110        map { $_ => "$dir/$_" }
 111        grep { /\.(?:sql|pl|sql-\w+)$/ && -f "$dir/$_" }
 112        readdir $dh;
 113      closedir $dh;
 114   } catch {
 115     die $_ unless $self->ignore_ddl;
 116   };
 117   if (-d $common) {
 118     opendir my($dh), $common;
 119     for my $filename (grep { /\.(?:sql|pl)$/ && -f catfile($common,$_) } readdir $dh) {
 120       unless ($files{$filename}) {
 121         $files{$filename} = catfile($common,$filename);
 122       }
 123     }
 124     closedir $dh;
 125   }
 126
 127   return [@files{sort keys %files}]
 128 }
 129
 130 method _ddl_initialize_consume_filenames($type, $version) {
 131   $self->__ddl_consume_with_prefix($type, [ $version ], 'initialize')
 132 }
 133
 134 method _ddl_schema_consume_filenames($type, $version) {
 135   $self->__ddl_consume_with_prefix($type, [ $version ], 'deploy')
 136 }
 137
 138 method _ddl_protoschema_upgrade_consume_filenames($versions) {
 139   my $base_dir = $self->script_directory;
 140
 141   my $dir = catfile( $base_dir, '_preprocess_schema', 'upgrade', join q(-), @{$versions});
 142
 143   return [] unless -d $dir;
 144
 145   opendir my($dh), $dir;
 146   my %files = map { $_ => "$dir/$_" } grep { /\.pl$/ && -f "$dir/$_" } readdir $dh;
 147   closedir $dh;
 148
 149   return [@files{sort keys %files}]
 150 }
 151
 152 method _ddl_protoschema_downgrade_consume_filenames($versions) {
 153   my $base_dir = $self->script_directory;
 154
 155   my $dir = catfile( $base_dir, '_preprocess_schema', 'downgrade', join q(-), @{$versions});
 156
 157   return [] unless -d $dir;
 158
 159   opendir my($dh), $dir;
 160   my %files = map { $_ => "$dir/$_" } grep { /\.pl$/ && -f "$dir/$_" } readdir $dh;
 161   closedir $dh;
 162
 163   return [@files{sort keys %files}]
 164 }
 165
 166 method _ddl_protoschema_produce_filename($version) {
 167   my $dirname = catfile( $self->script_directory, '_source', 'deploy',  $version );
 168   mkpath($dirname) unless -d $dirname;
 169
 170   return catfile( $dirname, '001-auto.yml' );
 171 }
 172
 173 method _ddl_schema_produce_filename($type, $version) {
 174   my $dirname = catfile( $self->script_directory, $type, 'deploy', $version );
 175   mkpath($dirname) unless -d $dirname;
 176
 177   return catfile( $dirname, '001-auto.sql' );
 178 }
 179
 180 method _ddl_schema_upgrade_consume_filenames($type, $versions) {
 181   $self->__ddl_consume_with_prefix($type, $versions, 'upgrade')
 182 }
 183
 184 method _ddl_schema_downgrade_consume_filenames($type, $versions) {
 185   $self->__ddl_consume_with_prefix($type, $versions, 'downgrade')
 186 }
 187
 188 method _ddl_schema_upgrade_produce_filename($type, $versions) {
 189   my $dir = $self->script_directory;
 190
 191   my $dirname = catfile( $dir, $type, 'upgrade', join q(-), @{$versions});
 192   mkpath($dirname) unless -d $dirname;
 193
 194   return catfile( $dirname, '001-auto.sql' );
 195 }
 196
 197 method _ddl_schema_downgrade_produce_filename($type, $versions, $dir) {
 198   my $dirname = catfile( $dir, $type, 'downgrade', join q(-), @{$versions} );
 199   mkpath($dirname) unless -d $dirname;
 200
 201   return catfile( $dirname, '001-auto.sql');
 202 }
 203
 204 method _run_sql_array($sql) {
 205   my $storage = $self->storage;
 206
 207   $sql = [grep {
 208     $_ && # remove blank lines
 209     !/^(BEGIN|BEGIN TRANSACTION|COMMIT)/ # strip txn's
 210   } map {
 211     s/^\s+//; s/\s+$//; # trim whitespace
 212     join '', grep { !/^--/ } split /\n/ # remove comments
 213   } @$sql];
 214
 215   Dlog_trace { "Running SQL $_" } $sql;
 216   foreach my $line (@{$sql}) {
 217     $storage->_query_start($line);
 218     # the whole reason we do this is so that we can see the line that was run
 219     try {
 220       $storage->dbh_do (sub { $_[1]->do($line) });
 221     }
 222     catch {
 223       die "$_ (running line '$line')"
 224     };
 225     $storage->_query_end($line);
 226   }
 227   return join "\n", @$sql
 228 }
 229
 230 method _run_sql($filename) {
 231   log_debug { "Running SQL from $filename" };
 232   return $self->_run_sql_array($self->_read_sql_file($filename));
 233 }
 234
 235 method _run_perl($filename) {
 236   log_debug { "Running Perl from $filename" };
 237   my $filedata = do { local( @ARGV, $/ ) = $filename; <> };
 238
 239   no warnings 'redefine';
 240   my $fn = eval "$filedata";
 241   use warnings;
 242   Dlog_trace { "Running Perl $_" } $fn;
 243
 244   if ($@) {
 245     carp "$filename failed to compile: $@";
 246   } elsif (ref $fn eq 'CODE') {
 247     $fn->($self->schema)
 248   } else {
 249     carp "$filename should define an anonymouse sub that takes a schema but it didn't!";
 250   }
 251 }
 252
 253 method _run_sql_and_perl($filenames, $sql_to_run) {
 254   my @files   = @{$filenames};
 255   my $guard   = $self->schema->txn_scope_guard if $self->txn_wrap;
 256
 257   $self->_run_sql_array($sql_to_run) if $self->ignore_ddl;
 258
 259   my $sql = ($sql_to_run)?join ";\n", @$sql_to_run:'';
 260   FILENAME:
 261   for my $filename (@files) {
 262     if ($self->ignore_ddl && $filename =~ /^[^_]*-auto.*\.sql$/) {
 263       next FILENAME
 264     } elsif ($filename =~ /\.sql$/) {
 265        $sql .= $self->_run_sql($filename)
 266     } elsif ( $filename =~ /\.pl$/ ) {
 267        $self->_run_perl($filename)
 268     } else {
 269       croak "A file ($filename) got to deploy that wasn't sql or perl!";
 270     }
 271   }
 272
 273   $guard->commit if $self->txn_wrap;
 274
 275   return $sql;
 276 }
 277
 278 sub deploy {
 279   my $self = shift;
 280   my $version = (shift @_ || {})->{version} || $self->schema_version;
 281   log_info { "deploying version $version" };
 282   my $sqlt_type = $self->storage->sqlt_type;
 283   my $sql;
 284   if ($self->ignore_ddl) {
 285      $sql = $self->_sql_from_yaml({},
 286        '_ddl_protoschema_produce_filename', $sqlt_type
 287      );
 288   }
 289   return $self->_run_sql_and_perl($self->_ddl_schema_consume_filenames(
 290     $sqlt_type,
 291     $version,
 292   ), $sql);
 293 }
 294
 295 sub initialize {
 296   my $self         = shift;
 297   my $args         = shift;
 298   my $version      = $args->{version}      || $self->schema_version;
 299   log_info { "initializing version $version" };
 300   my $storage_type = $args->{storage_type} || $self->storage->sqlt_type;
 301
 302   my @files = @{$self->_ddl_initialize_consume_filenames(
 303     $storage_type,
 304     $version,
 305   )};
 306
 307   for my $filename (@files) {
 308     # We ignore sql for now (till I figure out what to do with it)
 309     if ( $filename =~ /^(.+)\.pl$/ ) {
 310       my $filedata = do { local( @ARGV, $/ ) = $filename; <> };
 311
 312       no warnings 'redefine';
 313       my $fn = eval "$filedata";
 314       use warnings;
 315
 316       if ($@) {
 317         carp "$filename failed to compile: $@";
 318       } elsif (ref $fn eq 'CODE') {
 319         $fn->()
 320       } else {
 321         carp "$filename should define an anonymous sub but it didn't!";
 322       }
 323     } else {
 324       croak "A file ($filename) got to initialize_scripts that wasn't sql or perl!";
 325     }
 326   }
 327 }
 328
 329 method _sqldiff_from_yaml($from_version, $to_version, $db, $direction) {
 330   my $dir       = $self->script_directory;
 331   my $sqltargs = {
 332     add_drop_table => 1,
 333     ignore_constraint_names => 1,
 334     ignore_index_names => 1,
 335     %{$self->sql_translator_args}
 336   };
 337
 338   my $source_schema;
 339   {
 340     my $prefilename = $self->_ddl_protoschema_produce_filename($from_version, $dir);
 341
 342     # should probably be a croak
 343     carp("No previous schema file found ($prefilename)")
 344        unless -e $prefilename;
 345
 346     my $t = SQL::Translator->new({
 347        %{$sqltargs},
 348        debug => 0,
 349        trace => 0,
 350        parser => 'SQL::Translator::Parser::YAML',
 351     });
 352
 353     my $out = $t->translate( $prefilename )
 354       or croak($t->error);
 355
 356     $source_schema = $t->schema;
 357
 358     $source_schema->name( $prefilename )
 359       unless  $source_schema->name;
 360   }
 361
 362   my $dest_schema;
 363   {
 364     my $filename = $self->_ddl_protoschema_produce_filename($to_version, $dir);
 365
 366     # should probably be a croak
 367     carp("No next schema file found ($filename)")
 368        unless -e $filename;
 369
 370     my $t = SQL::Translator->new({
 371        %{$sqltargs},
 372        debug => 0,
 373        trace => 0,
 374        parser => 'SQL::Translator::Parser::YAML',
 375     });
 376
 377     my $out = $t->translate( $filename )
 378       or croak($t->error);
 379
 380     $dest_schema = $t->schema;
 381
 382     $dest_schema->name( $filename )
 383       unless $dest_schema->name;
 384   }
 385
 386   my $transform_files_method =  "_ddl_protoschema_${direction}_consume_filenames";
 387   my $transforms = $self->_coderefs_per_files(
 388     $self->$transform_files_method([$from_version, $to_version])
 389   );
 390   $_->($source_schema, $dest_schema) for @$transforms;
 391
 392   return [SQL::Translator::Diff::schema_diff(
 393      $source_schema, $db,
 394      $dest_schema,   $db,
 395      $sqltargs
 396   )];
 397 }
 398
 399 method _sql_from_yaml($sqltargs, $from_file, $db) {
 400   my $schema    = $self->schema;
 401   my $version   = $self->schema_version;
 402
 403   my $sqlt = SQL::Translator->new({
 404     add_drop_table          => 0,
 405     parser                  => 'SQL::Translator::Parser::YAML',
 406     %{$sqltargs},
 407     producer => $db,
 408   });
 409
 410   my $yaml_filename = $self->$from_file($version);
 411
 412   my @sql = $sqlt->translate($yaml_filename);
 413   if(!@sql) {
 414     carp("Failed to translate to $db, skipping. (" . $sqlt->error . ")");
 415     return undef;
 416   }
 417   return \@sql;
 418 }
 419
 420 sub _prepare_install {
 421   my $self      = shift;
 422   my $sqltargs  = { %{$self->sql_translator_args}, %{shift @_} };
 423   my $from_file = shift;
 424   my $to_file   = shift;
 425   my $dir       = $self->script_directory;
 426   my $databases = $self->databases;
 427   my $version   = $self->schema_version;
 428
 429   foreach my $db (@$databases) {
 430     my $sql = $self->_sql_from_yaml($sqltargs, $from_file, $db ) or next;
 431
 432     my $filename = $self->$to_file($db, $version, $dir);
 433     if (-e $filename ) {
 434       carp "Overwriting existing DDL file - $filename";
 435       unlink $filename;
 436     }
 437     open my $file, q(>), $filename;
 438     print {$file} join ";\n", @$sql;
 439     close $file;
 440   }
 441 }
 442
 443 sub _resultsource_install_filename {
 444   my ($self, $source_name) = @_;
 445   return sub {
 446     my ($self, $type, $version) = @_;
 447     my $dirname = catfile( $self->script_directory, $type, 'deploy', $version );
 448     mkpath($dirname) unless -d $dirname;
 449
 450     return catfile( $dirname, "001-auto-$source_name.sql" );
 451   }
 452 }
 453
 454 sub _resultsource_protoschema_filename {
 455   my ($self, $source_name) = @_;
 456   return sub {
 457     my ($self, $version) = @_;
 458     my $dirname = catfile( $self->script_directory, '_source', 'deploy', $version );
 459     mkpath($dirname) unless -d $dirname;
 460
 461     return catfile( $dirname, "001-auto-$source_name.yml" );
 462   }
 463 }
 464
 465 sub install_resultsource {
 466   my ($self, $args) = @_;
 467   my $source          = $args->{result_source};
 468   my $version         = $args->{version};
 469   log_info { 'installing_resultsource ' . $source->source_name . ", version $version" };
 470   my $rs_install_file =
 471     $self->_resultsource_install_filename($source->source_name);
 472
 473   my $files = [
 474      $self->$rs_install_file(
 475       $self->storage->sqlt_type,
 476       $version,
 477     )
 478   ];
 479   $self->_run_sql_and_perl($files);
 480 }
 481
 482 sub prepare_resultsource_install {
 483   my $self = shift;
 484   my $source = (shift @_)->{result_source};
 485   log_info { 'preparing install for resultsource ' . $source->source_name };
 486
 487   my $install_filename = $self->_resultsource_install_filename($source->source_name);
 488   my $proto_filename = $self->_resultsource_protoschema_filename($source->source_name);
 489   $self->prepare_protoschema({
 490       parser_args => { sources => [$source->source_name], }
 491   }, $proto_filename);
 492   $self->_prepare_install({}, $proto_filename, $install_filename);
 493 }
 494
 495 sub prepare_deploy {
 496   log_info { 'preparing deploy' };
 497   my $self = shift;
 498   $self->prepare_protoschema({
 499       # Exclude __VERSION so that it gets installed separately
 500       parser_args => { sources => [grep { $_ ne '__VERSION' } $self->schema->sources], }
 501   }, '_ddl_protoschema_produce_filename');
 502   $self->_prepare_install({}, '_ddl_protoschema_produce_filename', '_ddl_schema_produce_filename');
 503 }
 504
 505 sub prepare_upgrade {
 506   my ($self, $args) = @_;
 507   log_info {
 508      "preparing upgrade from $args->{from_version} to $args->{to_version}"
 509   };
 510   $self->_prepare_changegrade(
 511     $args->{from_version}, $args->{to_version}, $args->{version_set}, 'upgrade'
 512   );
 513 }
 514
 515 sub prepare_downgrade {
 516   my ($self, $args) = @_;
 517   log_info {
 518      "preparing downgrade from $args->{from_version} to $args->{to_version}"
 519   };
 520   $self->_prepare_changegrade(
 521     $args->{from_version}, $args->{to_version}, $args->{version_set}, 'downgrade'
 522   );
 523 }
 524
 525 method _coderefs_per_files($files) {
 526   no warnings 'redefine';
 527   [map eval do { local( @ARGV, $/ ) = $_; <> }, @$files]
 528 }
 529
 530 method _prepare_changegrade($from_version, $to_version, $version_set, $direction) {
 531   my $schema    = $self->schema;
 532   my $databases = $self->databases;
 533   my $dir       = $self->script_directory;
 534
 535   my $schema_version = $self->schema_version;
 536   my $diff_file_method = "_ddl_schema_${direction}_produce_filename";
 537   foreach my $db (@$databases) {
 538     my $diff_file = $self->$diff_file_method($db, $version_set, $dir );
 539     if(-e $diff_file) {
 540       carp("Overwriting existing $direction-diff file - $diff_file");
 541       unlink $diff_file;
 542     }
 543
 544     open my $file, q(>), $diff_file;
 545     print {$file} join ";\n", @{$self->_sqldiff_from_yaml($from_version, $to_version, $db, $direction)};
 546     close $file;
 547   }
 548 }
 549
 550 method _read_sql_file($file) {
 551   return unless $file;
 552
 553   open my $fh, '<', $file;
 554   my @data = split /;\n/, join '', <$fh>;
 555   close $fh;
 556
 557   @data = grep {
 558     $_ && # remove blank lines
 559     !/^(BEGIN|BEGIN TRANSACTION|COMMIT)/ # strip txn's
 560   } map {
 561     s/^\s+//; s/\s+$//; # trim whitespace
 562     join '', grep { !/^--/ } split /\n/ # remove comments
 563   } @data;
 564
 565   return \@data;
 566 }
 567
 568 sub downgrade_single_step {
 569   my $self = shift;
 570   my $version_set = (shift @_)->{version_set};
 571   Dlog_info { "downgrade_single_step'ing $_" } $version_set;
 572
 573   my $sqlt_type = $self->storage->sqlt_type;
 574   my $sql_to_run;
 575   if ($self->ignore_ddl) {
 576      $sql_to_run = $self->_sqldiff_from_yaml(
 577        $version_set->[0], $version_set->[1], $sqlt_type, 'downgrade',
 578      );
 579   }
 580   my $sql = $self->_run_sql_and_perl($self->_ddl_schema_downgrade_consume_filenames(
 581     $sqlt_type,
 582     $version_set,
 583   ), $sql_to_run);
 584
 585   return ['', $sql];
 586 }
 587
 588 sub upgrade_single_step {
 589   my $self = shift;
 590   my $version_set = (shift @_)->{version_set};
 591   Dlog_info { "upgrade_single_step'ing $_" } $version_set;
 592
 593   my $sqlt_type = $self->storage->sqlt_type;
 594   my $sql_to_run;
 595   if ($self->ignore_ddl) {
 596      $sql_to_run = $self->_sqldiff_from_yaml(
 597        $version_set->[0], $version_set->[1], $sqlt_type, 'upgrade',
 598      );
 599   }
 600   my $sql = $self->_run_sql_and_perl($self->_ddl_schema_upgrade_consume_filenames(
 601     $sqlt_type,
 602     $version_set,
 603   ), $sql_to_run);
 604   return ['', $sql];
 605 }
 606
 607 sub prepare_protoschema {
 608   my $self      = shift;
 609   my $sqltargs  = { %{$self->sql_translator_args}, %{shift @_} };
 610   my $to_file   = shift;
 611   my $filename
 612     = $self->$to_file($self->schema_version);
 613
 614   # we do this because the code that uses this sets parser args,
 615   # so we just need to merge in the package
 616   $sqltargs->{parser_args}{package} = $self->schema;
 617   my $sqlt = SQL::Translator->new({
 618     parser                  => 'SQL::Translator::Parser::DBIx::Class',
 619     producer                => 'SQL::Translator::Producer::YAML',
 620     %{ $sqltargs },
 621   });
 622
 623   my $yml = $sqlt->translate;
 624
 625   croak("Failed to translate to YAML: " . $sqlt->error)
 626     unless $yml;
 627
 628   if (-e $filename ) {
 629     carp "Overwriting existing DDL-YML file - $filename";
 630     unlink $filename;
 631   }
 632
 633   open my $file, q(>), $filename;
 634   print {$file} $yml;
 635   close $file;
 636 }
 637
 638 __PACKAGE__->meta->make_immutable;
 639
 640 1;
 641
 642 # vim: ts=2 sw=2 expandtab
 643
 644 __END__
 645
 646 =head1 DESCRIPTION
 647
 648 This class is the meat of L<DBIx::Class::DeploymentHandler>.  It takes care
 649 of generating serialized schemata  as well as sql files to move from one
 650 version of a schema to the rest.  One of the hallmark features of this class
 651 is that it allows for multiple sql files for deploy and upgrade, allowing
 652 developers to fine tune deployment.  In addition it also allows for perl
 653 files to be run at any stage of the process.
 654
 655 For basic usage see L<DBIx::Class::DeploymentHandler::HandlesDeploy>.  What's
 656 documented here is extra fun stuff or private methods.
 657
 658 =head1 DIRECTORY LAYOUT
 659
 660 Arguably this is the best feature of L<DBIx::Class::DeploymentHandler>.
 661 It's spiritually based upon L<DBIx::Migration::Directories>, but has a
 662 lot of extensions and modifications, so even if you are familiar with it,
 663 please read this.  I feel like the best way to describe the layout is with
 664 the following example:
 665
 666  $sql_migration_dir
 667  |- _source
 668  |  |- deploy
 669  |     |- 1
 670  |     |  `- 001-auto.yml
 671  |     |- 2
 672  |     |  `- 001-auto.yml
 673  |     `- 3
 674  |        `- 001-auto.yml
 675  |- SQLite
 676  |  |- downgrade
 677  |  |  `- 2-1
 678  |  |     `- 001-auto.sql
 679  |  |- deploy
 680  |  |  `- 1
 681  |  |     `- 001-auto.sql
 682  |  `- upgrade
 683  |     |- 1-2
 684  |     |  `- 001-auto.sql
 685  |     `- 2-3
 686  |        `- 001-auto.sql
 687  |- _common
 688  |  |- downgrade
 689  |  |  `- 2-1
 690  |  |     `- 002-remove-customers.pl
 691  |  `- upgrade
 692  |     `- 1-2
 693  |        `- 002-generate-customers.pl
 694  `- MySQL
 695     |- downgrade
 696     |  `- 2-1
 697     |     `- 001-auto.sql
 698     |- initialize
 699     |  `- 1
 700     |     |- 001-create_database.pl
 701     |     `- 002-create_users_and_permissions.pl
 702     |- deploy
 703     |  `- 1
 704     |     `- 001-auto.sql
 705     `- upgrade
 706        `- 1-2
 707           `- 001-auto.sql
 708
 709 So basically, the code
 710
 711  $dm->deploy(1)
 712
 713 on an C<SQLite> database that would simply run
 714 C<$sql_migration_dir/SQLite/deploy/1/001-auto.sql>.  Next,
 715
 716  $dm->upgrade_single_step([1,2])
 717
 718 would run C<$sql_migration_dir/SQLite/upgrade/1-2/001-auto.sql> followed by
 719 C<$sql_migration_dir/_common/upgrade/1-2/002-generate-customers.pl>.
 720
 721 C<.pl> files don't have to be in the C<_common> directory, but most of the time
 722 they should be, because perl scripts are generally database independent.
 723
 724 Note that unlike most steps in the process, C<initialize> will not run SQL, as
 725 there may not even be an database at initialize time.  It will run perl scripts
 726 just like the other steps in the process, but nothing is passed to them.
 727 Until people have used this more it will remain freeform, but a recommended use
 728 of initialize is to have it prompt for username and password, and then call the
 729 appropriate C<< CREATE DATABASE >> commands etc.
 730
 731 =head2 Directory Specification
 732
 733 The following subdirectories are recognized by this DeployMethod:
 734
 735 =over 2
 736
 737 =item C<_source> This directory can contain the following directories:
 738
 739 =over 2
 740
 741 =item C<deploy> This directory merely contains directories named after schema
 742 versions, which in turn contain C<yaml> files that are serialized versions
 743 of the schema at that version.  These files are not for editing by hand.
 744
 745 =back
 746
 747 =item C<_preprocess_schema> This directory can contain the following
 748 directories:
 749
 750 =over 2
 751
 752 =item C<downgrade> This directory merely contains directories named after
 753 migrations, which are of the form C<$from_version-$to_version>.  Inside of
 754 these directories you may put Perl scripts which are to return a subref
 755 that takes the arguments C<< $from_schema, $to_schema >>, which are
 756 L<SQL::Translator::Schema> objects.
 757
 758 =item C<upgrade> This directory merely contains directories named after
 759 migrations, which are of the form C<$from_version-$to_version>.  Inside of
 760 these directories you may put Perl scripts which are to return a subref
 761 that takes the arguments C<< $from_schema, $to_schema >>, which are
 762 L<SQL::Translator::Schema> objects.
 763
 764 =back
 765
 766 =item C<$storage_type> This is a set of scripts that gets run depending on what
 767 your storage type is.  If you are not sure what your storage type is, take a
 768 look at the producers listed for L<SQL::Translator>.  Also note, C<_common>
 769 is a special case.  C<_common> will get merged into whatever other files you
 770 already have.  This directory can containt the following directories itself:
 771
 772 =over 2
 773
 774 =item C<initialize> Gets run before the C<deploy> is C<deploy>ed.  Has the
 775 same structure as the C<deploy> subdirectory as well; that is, it has a
 776 directory for each schema version.  Unlike C<deploy>, C<upgrade>, and C<downgrade>
 777 though, it can only run C<.pl> files, and the coderef in the perl files get
 778 no arguments passed to them.
 779
 780 =item C<deploy> Gets run when the schema is C<deploy>ed.  Structure is a
 781 directory per schema version, and then files are merged with C<_common> and run
 782 in filename order.  C<.sql> files are merely run, as expected.  C<.pl> files are
 783 run according to L</PERL SCRIPTS>.
 784
 785 =item C<upgrade> Gets run when the schema is C<upgrade>d.  Structure is a directory
 786 per upgrade step, (for example, C<1-2> for upgrading from version 1 to version
 787 2,) and then files are merged with C<_common> and run in filename order.
 788 C<.sql> files are merely run, as expected.  C<.pl> files are run according
 789 to L</PERL SCRIPTS>.
 790
 791 =item C<downgrade> Gets run when the schema is C<downgrade>d.  Structure is a directory
 792 per downgrade step, (for example, C<2-1> for downgrading from version 2 to version
 793 1,) and then files are merged with C<_common> and run in filename order.
 794 C<.sql> files are merely run, as expected.  C<.pl> files are run according
 795 to L</PERL SCRIPTS>.
 796
 797
 798 =back
 799
 800 =back
 801
 802 =head1 PERL SCRIPTS
 803
 804 A perl script for this tool is very simple.  It merely needs to contain an
 805 anonymous sub that takes a L<DBIx::Class::Schema> as it's only argument.
 806 A very basic perl script might look like:
 807
 808  #!perl
 809
 810  use strict;
 811  use warnings;
 812
 813  sub {
 814    my $schema = shift;
 815
 816    $schema->resultset('Users')->create({
 817      name => 'root',
 818      password => 'root',
 819    })
 820  }
 821
 822 =attr ignore_ddl
 823
 824 This attribute will, when set to true (default is false), cause the DM to use
 825 L<SQL::Translator> to use the C<_source>'s serialized SQL::Translator::Schema
 826 instead of any pregenerated SQL.  If you have a development server this is
 827 probably the best plan of action as you will not be putting as many generated
 828 files in your version control.  Goes well with with C<databases> of C<[]>.
 829
 830 =attr schema
 831
 832 The L<DBIx::Class::Schema> (B<required>) that is used to talk to the database
 833 and generate the DDL.
 834
 835 =attr storage
 836
 837 The L<DBIx::Class::Storage> that is I<actually> used to talk to the database
 838 and generate the DDL.  This is automatically created with L</_build_storage>.
 839
 840 =attr sql_translator_args
 841
 842 The arguments that get passed to L<SQL::Translator> when it's used.
 843
 844 =attr script_directory
 845
 846 The directory (default C<'sql'>) that scripts are stored in
 847
 848 =attr databases
 849
 850 The types of databases (default C<< [qw( MySQL SQLite PostgreSQL )] >>) to
 851 generate files for
 852
 853 =attr txn_wrap
 854
 855 Set to true (which is the default) to wrap all upgrades and deploys in a single
 856 transaction.
 857
 858 =attr schema_version
 859
 860 The version the schema on your harddrive is at.  Defaults to
 861 C<< $self->schema->schema_version >>.