-=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<DBIx::Class::Manual::Intro> 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<DBIx::Class::Manual::Intro> 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<install.pl> 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<install.pl> 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<dbicdh/_common/deploy/1/create_artists.pl>:
+
+ 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<upgrade.pl>:
- $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:
`-- 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<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the
+state of the db as at that version. The C<upgrade/1-2/001-auto.sql> 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.
projects / dbsrgits/DBIx-Class-DeploymentHandler.git / blobdiff