1 package DBIx::Class::DeploymentHandler::Manual::Intro
3 # ABSTRACT: Introduction to DBIx::Class::DeploymentHandler
7 =head1 Why is DBIx::Class::DeploymentHandler worth using?
9 The most obvious reasons for using DBIx::Class::DeploymentHandler are
10 that it can run multiple SQL scripts as well as Perl scripts, unlike
11 DBIx::Class::Schema::Versioned, which only allows for a single SQL script.
12 It is also extremely extensible, and is an opportunity for a break from
13 backwards compatibility, so some regrettable decisions are avoided.
15 =head1 Sample database
17 Follow L<DBIx::Class::Manual::Intro> except for the parts setting up the
18 database. After you are done, You should have the following files.
29 Add a line like the following in your MyDatabase::Main file:
33 or if you are using a newer Perl you can use the prettier syntax:
35 package MyDatabase::Main 1;
37 By default DBIx::Class::DeploymentHandler only uses integers for versions,
38 this makes versioning much simpler for figuring out what version is next
43 Our first script, C<install.pl> reads our schema file and creates the tables
50 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
53 use lib "$FindBin::Bin/../lib";
56 my $force_overwrite = 0;
58 unless ( GetOptions( 'force_overwrite!' => \$force_overwrite ) ) {
59 die "Invalid options";
62 my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb.db');
67 script_directory => "$FindBin::Bin/../dbicdh",
68 databases => 'SQLite',
69 sql_translator_args => { add_drop_table => 0 },
70 force_overwrite => $force_overwrite,
77 =head2 dbicdh - Our migration scripts
79 Running C<install.pl> should create the following:
91 You may wish to turn on L<debug logging|DBIx::Class::DeploymentHandler/"LOGGING">
92 before running this script by setting the environment variable C<DBICDH_TRACE> to
97 DBIx::Class::DeploymentHandler automatically generates SQL from our schema
98 that is suitable for SQLite
102 This contains all of the raw information about our schema that is then
103 translated into the sql.
107 To truly take advantage of all DBIx::Class::DeploymentHandler offers, you
108 should probably be using it for population. To do that all you need to do
109 is create a file called C<dbicdh/_common/deploy/1/create_artists.pl>:
113 $schema->resultset('Artist')->populate([
114 ['artistid', 'name'],
116 [2, 'The Moutain Goats'],
123 Add a line to MyDatabase/Main/Result/Cd.pm below
125 __PACKAGE__->add_columns(qw/ cdid artist title /);
129 __PACKAGE__->add_column(isbn => { is_nullable => 1 });
131 Aside: It must be nullable or have a default - otherwise the upgrade will
132 fail for logical reasons. To be clear, if you add a column to a database and
133 it is not nullable and has no default, what will the existing rows contain
136 Now you need to modify the schema version in your MyDatabase::Main file to
137 tell DBIx::Class::DeploymentHandler the new schema version number. You will
138 want to remember the earlier advice about integer version numbers.
142 So here is our next script, C<upgrade.pl>:
147 use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
149 use lib "$FindBin::Bin/../lib";
150 use MyDatabase::Main;
151 my $schema = MyDatabase::Main->connect('dbi:SQLite:mydb');
155 script_directory => "$FindBin::Bin/../dbicdh",
156 databases => 'SQLite',
157 sql_translator_args => { add_drop_table => 0 },
161 $dh->prepare_upgrade({ from_version => 1, to_version => 2});
164 Our script directory now looks like:
170 | | | `-- 001-auto.sql
183 The new C<deploy/001-auto.sql> and C<deploy/001-auto.yml> files are the
184 state of the db as at that version. The C<upgrade/1-2/001-auto.sql> file
185 is the most interesting one; it is what gets your database from version 1 to 2.
187 And again, you can create a Perl file like we did previously with the