NAME

Why is DBIx::Class::DeploymentHandler worth using?

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.

Sample database

Follow DBIx::Class::Manual::Intro except for the parts setting up the database. After you are done, You should have the following files.

By default DBIx::Class::DeploymentHandler only uses integers for versions, this makes versioning much simpler for figuring out what version is next (or previous.) However, if you are using decimal numbers for versioning, you will need to create a separate DeploymentHandler class, as per DBIx::Class::DeploymentHandler::Cookbook::CustomResultSource, and set the VersionHandler class_name from Monotonic to ExplicitVersions or DatabaseToSchemaVersions, as these handle version numbers as strings instead of integers.

install.pl

Our first script, install.pl reads our schema file and creates the tables in the database.

dbicdh - Our migration scripts

You may wish to turn on debug logging before running this script by setting the environment variable DBICDH_TRACE to 1.

001-auto.sql

DBIx::Class::DeploymentHandler automatically generates SQL from our schema that is suitable for SQLite

001-auto.yml

This contains all of the raw information about our schema that is then translated into the sql.

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 dbicdh/_common/deploy/1/create_artists.pl:

Upgrading

Add a line to MyDatabase/Main/Result/Cd.pm below

__PACKAGE__->add_columns(qw/ cdid artist title /);

with

__PACKAGE__->add_column(isbn => { is_nullable => 1 });

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?

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.

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; it is what gets your database from version 1 to 2.

And again, you can create a Perl file like we did previously with the deploy stage.

AUTHOR

Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Arthur Axel "fREW" Schmidt.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Module Install Instructions

To install DBIx::Class::DeploymentHandler::Manual::Intro, simply copy and paste either of the commands in to your terminal