From: Arthur Axel 'fREW' Schmidt Date: Mon, 12 Apr 2010 05:30:41 +0000 (-0500) Subject: lots more doc X-Git-Tag: v0.001000_01~5 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits%2FDBIx-Class-DeploymentHandler.git;a=commitdiff_plain;h=bcc722970a94f2ba2debdeb630168bde1f8a6830 lots more doc --- diff --git a/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator.pm b/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator.pm index 29a9e27..1082ab2 100644 --- a/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator.pm +++ b/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator.pm @@ -428,10 +428,32 @@ __PACKAGE__->meta->make_immutable; __END__ +=head1 DESCRIPTION + +This class is the meat of L. It takes care of +generating sql files representing schemata as well as sql files to move from +one version of a schema to the rest. One of the hallmark features of this +class is that it allows for multiple sql files for deploy and upgrade, allowing +developers to fine tune deployment. In addition it also allows for perl files +to be run at any stage of the process. + +For basic usage see L. What's +documented here is extra fun stuff or private methods. + +=head1 DIRECTORY LAYOUT + +It's heavily based upon L. + =attr schema +The L (B) that is used to talk to the database +and generate the DDL. + =attr storage +The L that is I used to talk to the database +and generate the DDL. This is automatically created with L. + =attr sqltargs #rename @@ -447,43 +469,97 @@ generate files for =attr txn_wrap +Set to true (which is the default) to wrap all upgrades and deploys in a single +transaction. + =method __ddl_consume_with_prefix + $dm->__ddl_consume_with_prefix( 'SQLite', [qw( 1.00 1.01 )], 'up' ) + +This is the meat of the multi-file upgrade/deploy stuff. It returns a list of +files in the order that they should be run for a generic "type" of upgrade. +You should not be calling this in user code. + =method _ddl_schema_consume_filenames + $dm->__ddl_schema_consume_filenames( 'SQLite', [qw( 1.00 )] ) + +Just a curried L. Get's a list of files for an +initial deploy. + =method _ddl_schema_produce_filename + $dm->__ddl_schema_produce_filename( 'SQLite', [qw( 1.00 )] ) + +Returns a single file in which an initial schema will be stored. + =method _ddl_schema_up_consume_filenames + $dm->_ddl_schema_up_consume_filenames( 'SQLite', [qw( 1.00 )] ) + +Just a curried L. Get's a list of files for an +upgrade. + =method _ddl_schema_down_consume_filenames + $dm->_ddl_schema_down_consume_filenames( 'SQLite', [qw( 1.00 )] ) + +Just a curried L. Get's a list of files for a +downgrade. + =method _ddl_schema_up_produce_filenames -=method _ddl_schema_down_produce_filenames + $dm->_ddl_schema_up_produce_filename( 'SQLite', [qw( 1.00 1.01 )] ) + +Returns a single file in which the sql to upgrade from one schema to another +will be stored. + +=method _ddl_schema_down_produce_filename + + $dm->_ddl_schema_down_produce_filename( 'SQLite', [qw( 1.00 1.01 )] ) + +Returns a single file in which the sql to downgrade from one schema to another +will be stored. =method _resultsource_install_filename + my $filename_fn = $dm->_resultsource_install_filename('User'); + $dm->$filename_fn('SQLite', '1.00') + +Returns a function which in turn returns a single filename used to install a +single resultsource. Weird interface is convenient for me. Deal with it. + =method _run_sql_and_perl -=method _prepare_install + $dm->_run_sql_and_perl([qw( list of filenames )]) -=method _prepare_changegrade +Simply put, this runs the list of files passed to it. If the file ends in +C<.sql> it runs it as sql and if it ends in C<.pl> it runs it as a perl file. -=method _read_sql_file +Depending on L all of the files run will be wrapped in a single +transaction. -=method deploy +=method _prepare_install -=method install_resultsource + $dm->_prepare_install({ add_drop_table => 0 }, sub { 'file_to_create' }) -=method prepare_resultsouce_install +Generates the sql file for installing the database. First arg is simply +L args and the second is a coderef that returns the filename +to store the sql in. -=method prepare_install +=method _prepare_changegrade + + $dm->_prepare_changegrade('1.00', '1.01', [qw( 1.00 1.01)], 'up') -=method prepare_upgrade +Generates the sql file for migrating from one schema version to another. First +arg is the version to start from, second is the version to go to, third is the +L, and last is the +direction of the changegrade, be it 'up' or 'down'. -=method prepare_downgrade +=method _read_sql_file -=method upgrade_single_step + $dm->_read_sql_file('foo.sql') -=method downgrade_single_step +Reads a sql file and returns lines in an C. Strips out comments, +transactions, and blank lines. diff --git a/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator/Deprecated.pm b/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator/Deprecated.pm index 96fb073..db0a1a4 100644 --- a/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator/Deprecated.pm +++ b/lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator/Deprecated.pm @@ -47,6 +47,22 @@ __PACKAGE__->meta->make_immutable; __END__ +=head1 DESCRIPTION + +All this module does is override a few parts of +L so that the files generated with +L will work with this out of the box. + +=head1 DEPRECATED + +I begrudgingly made this module (and other related modules) to keep porting +from L relatively simple. I will make changes +to ensure that it works with output from L etc, +but I will not add any new features to it. + +Once I hit major version 1 usage of this module will emit a warning. +On version 2 it will be removed entirely. + =head1 THIS SUCKS Yeah, this old Deprecated thing is a drag. It can't do downgrades, it can only @@ -66,3 +82,25 @@ totally switch! Here's how: } } +=head1 OVERRIDDEN METHODS + +=over + +=item * + +L + +=item * + +L + +=item * + +L + +=item * + +L + +=back + diff --git a/lib/DBIx/Class/DeploymentHandler/Deprecated.pm b/lib/DBIx/Class/DeploymentHandler/Deprecated.pm index 3697761..57520cc 100644 --- a/lib/DBIx/Class/DeploymentHandler/Deprecated.pm +++ b/lib/DBIx/Class/DeploymentHandler/Deprecated.pm @@ -36,4 +36,61 @@ __PACKAGE__->meta->make_immutable; __END__ +=head1 DEPRECATED +I begrudgingly made this module (and other related modules) to make porting +from L relatively simple. I will make changes +to ensure that it works with output from L etc, +but I will not add any new features to it. It already lacks numerous features +that the full version provides in style: + +=over + +=item * + +Downgrades + +=item * + +Multiple files for migrations + +=item * + +Perl files in migrations + +=item * + +Shared Perl/SQL for different databases + +=back + +And there's probably more. + +At version 1.000000 usage of this module will emit a warning. At version +2.000000 it will be removed entirely. + +To migrate to the New Hotness take a look at: +L and +L. + +=head1 SYNOPSIS + +Look at L. I won't repeat +it here to emphasize, yet again, that this should not be used unless you really +want to live in the past. + +=head1 WHERE IS ALL THE DOC?! + +C extends +L, so that's probably the first place to +look when you are trying to figure out how everything works. + +Next would be to look at all the roles that fill in the blanks that +L expects to be filled. They would be +L, +L, and +L. Also, this class +is special in that it applies either +L or +L depending on +your schema. diff --git a/lib/DBIx/Class/DeploymentHandler/VersionStorage/Deprecated.pm b/lib/DBIx/Class/DeploymentHandler/VersionStorage/Deprecated.pm index 144cca7..6bce014 100644 --- a/lib/DBIx/Class/DeploymentHandler/VersionStorage/Deprecated.pm +++ b/lib/DBIx/Class/DeploymentHandler/VersionStorage/Deprecated.pm @@ -46,6 +46,16 @@ __PACKAGE__->meta->make_immutable; __END__ +=head1 DEPRECATED + +I begrudgingly made this module (and other related modules) to keep porting +from L relatively simple. I will make changes +to ensure that it works with output from L etc, +but I will not add any new features to it. + +Once I hit major version 1 usage of this module will emit a warning. +On version 2 it will be removed entirely. + =head1 THIS SUCKS Here's how to convert from that crufty old Deprecated VersionStorage to a shiny