X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits%2FDBIx-Class-DeploymentHandler.git;a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FDeploymentHandler%2FManual%2FIntro.pod;h=a214e731d88aeaf63bc7dd31c53466afd0412177;hp=376e33c15843a484bff323ff2930afa52c3fcf4c;hb=cc64124f3a8f27b0b39ba9449776056da254d8b2;hpb=f59dc4334c72da927ebd53d86e1d9c75865ebe91 diff --git a/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod b/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod index 376e33c..a214e73 100644 --- a/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod +++ b/lib/DBIx/Class/DeploymentHandler/Manual/Intro.pod @@ -1,116 +1,149 @@ -=head1 NAME +package DBIx::Class::DeploymentHandler::Manual::Intro -DBIx::Class::DeploymentHandler::Intro - Introduction to DBIx::Class::DeploymentHandler +# ABSTRACT: Introduction to DBIx::Class::DeploymentHandler -=head1 Why DBIx::Class::DeploymentHandler is worth using +=pod +=head1 Why is DBIx::Class::DeploymentHandler worth using? -=head1 Our Sample database +The most obvious reasons for using DBIx::Class::DeploymentHandler are +that it can run multiple SQL scripts as well as Perl scripts, unlike +DBIx::Class::Schema::Versioned, which only allows for a single SQL script. +It is also extremely extensible, and is an opportunity for a break from +backwards compatibility, so some regrettable decisions are avoided. -Follow L except for the parts setting up the database. -After you are done, You should have the following files. +=head1 Sample database - MyDatabase/ - |-- Main - | |-- Result - | | |-- Artist.pm - | | |-- Cd.pm - | | `-- Track.pm - | `-- ResultSet - `-- Main.pm +Follow L except for the parts setting up the +database. After you are done, You should have the following files. -=head1 preinstall.pl + MyDatabase/ + |-- Main + | |-- Result + | | |-- Artist.pm + | | |-- Cd.pm + | | `-- Track.pm + | `-- ResultSet + `-- Main.pm -Our first script, preinstall.pl reads our schema file and creates the tables in the database. +Add a line like the following in your MyDatabase::Main file: - use aliased 'DBIx::Class::DeploymentHandler' => 'DH'; - use FindBin; - use lib "$FindBin::Bin/../lib"; - use MyDatabase::Main; - my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb'); + our $VERSION = 1; - my $dh = DH->new( - { - schema => $schema, - script_directory => "$FindBin::Bin/dbicdh", - databases => 'SQLite', - sql_translator_args => { add_drop_table => 0 }, - schema_version => 1, - } - ); +or if you are using a newer Perl you can use the prettier syntax: - $dh->prepare_install; - $dh->install({version => 1}); + package MyDatabase::Main 1; -TODO TODO TODO TODO +By default DBIx::Class::DeploymentHandler only uses integers for versions, +this makes versioning much simpler for figuring out what version is next +(or previous.) -Someone really ought to fix the bug causing dbicdh/SQLite/deploy/1/001-auto.sql to have the dbix_class_deploymenthandler_versions +=head1 install.pl -Right now, you need to comment out the version table crap in the sql file , then run install, then uncomment it. +Our first script, C reads our schema file and creates the tables +in the database. -TODO TODO TODO TODO + #!/usr/bin/env perl + use strict; + use warnings; + use aliased 'DBIx::Class::DeploymentHandler' => 'DH'; + use FindBin; + use lib "$FindBin::Bin/../lib"; + use MyDatabase::Main; + my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb'); + + my $dh = DH->new({ + schema => $schema, + script_directory => "$FindBin::Bin/dbicdh", + databases => 'SQLite', + sql_translator_args => { add_drop_table => 0 }, + }); + + $dh->prepare_install; + $dh->install; =head2 dbicdh - Our migration scripts -Running preinstall.pl should create the following: +Running C should create the following: - dbicdh/ - |-- SQLite - | `-- deploy - | `-- 1 - | `-- 001-auto.sql - `-- _source - `-- deploy - `-- 1 - `-- 001-auto.yml + dbicdh/ + |-- SQLite + | `-- deploy + | `-- 1 + | `-- 001-auto.sql + `-- _source + `-- deploy + `-- 1 + `-- 001-auto.yml =head3 001-auto.sql -DBIx::Class::DeploymentHandler automatically generates SQL from our schema that is suitable for SQLite +DBIx::Class::DeploymentHandler automatically generates SQL from our schema +that is suitable for SQLite =head3 001-auto.yml -This contains all of the raw information about our schema that is then translated into the sql. +This contains all of the raw information about our schema that is then +translated into the sql. + +=head3 Population + +To truly take advantage of all DBIx::Class::DeploymentHandler offers, you +should probably be using it for population. To do that all you need to do +is create a file called C: + + sub { + my $schema = shift; + $schema->resultset('User')->populate([ + ['name'], + ['Marillion'], + ['The Moutain Goats'], + ['Ladyhawke'], + ]); + }; =head1 Upgrading Add a line to MyDatabase/Main/Result/Cd.pm below - __PACKAGE__->add_columns(qw/ cdid artist title /); + __PACKAGE__->add_columns(qw/ cdid artist title /); with - __PACKAGE__->add_column("isbn" => { is_nullable => 1 }); + __PACKAGE__->add_column(isbn => { is_nullable => 1 }); -(We need it to either be nullable, or have a default - merely adding it to the add_columns line will not work) +Aside: It must be nullable or have a default - otherwise the upgrade will +fail for logical reasons. To be clear, if you add a column to a database and +it is not nullable and has no default, what will the existing rows contain +for that column? -Then run the following script: +Now you need to modify the schema version in your MyDatabase::Main file to +tell DBIx::Class::DeploymentHandler the new schema version number. You will +want to remember the earlier advice about integer version numbers. - use strict; - use warnings; - use aliased 'DBIx::Class::DeploymentHandler' => 'DH'; - use FindBin; - use lib "$FindBin::Bin/../lib"; - use MyDatabase::Main; - my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb'); + our $VERSION = 2; - my $dh = DH->new( - { - schema => $schema, - script_directory => "$FindBin::Bin/dbicdh", - databases => 'SQLite', - sql_translator_args => { add_drop_table => 0 }, - schema_version => 2, - from_version => 1, - to_version => 2, - } - ); +So here is our next script, C: - $dh->prepare_deploy; - $dh->prepare_upgrade({ from_version => 1, to_version => 2}); - $dh->upgrade; + #!/usr/bin/env perl + use strict; + use warnings; + use aliased 'DBIx::Class::DeploymentHandler' => 'DH'; + use FindBin; + use lib "$FindBin::Bin/../lib"; + use MyDatabase::Main; + my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb'); + my $dh = DH->new({ + schema => $schema, + script_directory => "$FindBin::Bin/dbicdh", + databases => 'SQLite', + sql_translator_args => { add_drop_table => 0 }, + }); + $dh->prepare_deploy; + $dh->prepare_upgrade({ from_version => 1, to_version => 2}); + $dh->upgrade; Our script directory now looks like: @@ -131,17 +164,10 @@ Our script directory now looks like: `-- 2 `-- 001-auto.yml -The new deploy/001-auto.sql and deploy/001-auto.yml files are the state of the db as at that version. The upgrade/1-2/001-auto.sql file is the most interesting one - - -- Convert schema '/home/jdobbie/Projects/intro/dbicdh/_source/deploy/1/001-auto.yml' to '/home/jdobbie/Projects/intro/dbicdh/_source/deploy/2/001-auto.yml':; - - ; - BEGIN; - - ; - ALTER TABLE cd ADD COLUMN isbn; - - ; +The new C and C files are the +state of the db as at that version. The C file +is the most interesting one; it is what gets your database from version 1 to 2. - COMMIT; +And again, you can create a Perl file like we did previously with the +deploy stage.