rename and document preinstall

[dbsrgits/DBIx-Class-DeploymentHandler.git] / lib / DBIx / Class / DeploymentHandler / DeployMethod / SQL / Translator.pm

diff --git a/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator.pm b/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator.pm
index 7adfa61..c56243b 100644 (file)
--- a/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator.pm
+++ b/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator.pm
@@ -203,7 +203,7 @@ sub deploy {
   ));
 }
 
-sub preinstall_scripts {
+sub preinstall {
   my $self = shift;
   my $version = shift || $self->schema_version;
 
@@ -493,7 +493,7 @@ like the best way to describe the layout is with the following example:
  $sql_migration_dir
  |- SQLite
  |  |- down
- |  |  `- 1-2
+ |  |  `- 2-1
  |  |     `- 001-auto.sql
  |  |- schema
  |  |  `- 1
@@ -505,14 +505,14 @@ like the best way to describe the layout is with the following example:
  |        `- 001-auto.sql
  |- _common
  |  |- down
- |  |  `- 1-2
+ |  |  `- 2-1
  |  |     `- 002-remove-customers.pl
  |  `- up
  |     `- 1-2
  |        `- 002-generate-customers.pl
  |- _generic
  |  |- down
- |  |  `- 1-2
+ |  |  `- 2-1
  |  |     `- 001-auto.sql
  |  |- schema
  |  |  `- 1
@@ -523,8 +523,12 @@ like the best way to describe the layout is with the following example:
  |        `- 002-create-stored-procedures.sql
  `- MySQL
     |- down
-    |  `- 1-2
+    |  `- 2-1
     |     `- 001-auto.sql
+    |- preinstall
+    |  `- 1
+    |     |- 001-create_database.pl
+    |     `- 002-create_users_and_permissions.pl
     |- schema
     |  `- 1
     |     `- 001-auto.sql
@@ -551,10 +555,17 @@ independent.
 C<_generic> exists for when you for some reason are sure that your SQL is
 generic enough to run on all databases.  Good luck with that one.
 
+Note that unlike most steps in the process, C<preinstall> will not run SQL, as
+there may not even be an database at preinstall time.  It will run perl scripts
+just like the other steps in the process, but nothing is passed to them.
+Until people have used this more it will remain freeform, but a recommended use
+of preinstall is to have it prompt for username and password, and then call the
+appropriate C<< CREATE DATABASE >> commands etc.
+
 =head1 PERL SCRIPTS
 
-A perl script for this tool is very simple.  It merely needs to contain a
-sub called C<run> that takes a L<DBIx::Class::Schema> as it's only argument.
+A perl script for this tool is very simple.  It merely needs to contain an
+anonymous sub that takes a L<DBIx::Class::Schema> as it's only argument.
 A very basic perl script might look like:
 
  #!perl
@@ -562,7 +573,7 @@ A very basic perl script might look like:
  use strict;
  use warnings;
 
- sub run {
+ sub {
    my $schema = shift;
 
    $schema->resultset('Users')->create({