package DBIx::Class::DeploymentHandler;
+# ABSTRACT: Extensible DBIx::Class deployment
+
use Moose;
-use Method::Signatures::Simple;
-require DBIx::Class::Schema; # loaded for type constraint
-require DBIx::Class::Storage; # loaded for type constraint
-use Carp 'carp';
-
-has schema => (
- isa => 'DBIx::Class::Schema',
- is => 'ro',
- required => 1,
- handles => [qw{schema_version}],
-);
-
-has upgrade_directory => (
- isa => 'Str',
- is => 'ro',
- required => 1,
- default => 'sql',
-);
-
-has backup_directory => (
- isa => 'Str',
- is => 'ro',
-);
-
-has storage => (
- isa => 'DBIx::Class::Storage',
- is => 'ro',
- lazy_build => 1,
-);
-
-has _filedata => (
- is => 'ro',
-);
-
-has do_backup => (
- isa => 'Bool',
- is => 'ro',
- default => undef,
-);
-
-has do_diff_on_init => (
- isa => 'Bool',
- is => 'ro',
- default => undef,
-);
-
-method _build_storage {
- return $self->schema->storage;
-}
-method install($new_version) {
- # must be called on a fresh database
- if ($self->get_db_version) {
- carp 'Install not possible as versions table already exists in database';
- }
+extends 'DBIx::Class::DeploymentHandler::Dad';
+# a single with would be better, but we can't do that
+# see: http://rt.cpan.org/Public/Bug/Display.html?id=46347
+with 'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
+ interface_role => 'DBIx::Class::DeploymentHandler::HandlesDeploy',
+ class_name => 'DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator',
+ delegate_name => 'deploy_method',
+ attributes_to_assume => [qw(schema schema_version)],
+ attributes_to_copy => [qw(
+ ignore_ddl databases script_directory sql_translator_args force_overwrite
+ )],
+ },
+ 'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
+ interface_role => 'DBIx::Class::DeploymentHandler::HandlesVersioning',
+ class_name => 'DBIx::Class::DeploymentHandler::VersionHandler::Monotonic',
+ delegate_name => 'version_handler',
+ attributes_to_assume => [qw( database_version schema_version to_version )],
+ },
+ 'DBIx::Class::DeploymentHandler::WithApplicatorDumple' => {
+ interface_role => 'DBIx::Class::DeploymentHandler::HandlesVersionStorage',
+ class_name => 'DBIx::Class::DeploymentHandler::VersionStorage::Standard',
+ delegate_name => 'version_storage',
+ attributes_to_assume => ['schema'],
+ };
+with 'DBIx::Class::DeploymentHandler::WithReasonableDefaults';
- # default to current version if none passed
- $new_version ||= $self->schema_version();
+sub prepare_version_storage_install {
+ my $self = shift;
- if ($new_version) {
- # create versions table and version row
- $self->{vschema}->deploy;
- $self->_set_db_version({ version => $new_version });
- }
+ $self->prepare_resultsource_install({
+ result_source => $self->version_storage->version_rs->result_source
+ });
}
-method deploy {
- $self->next::method(@_);
- $self->install();
-}
+sub install_version_storage {
+ my $self = shift;
-sub create_upgrade_path {
- ## override this method
-}
+ my $version = (shift||{})->{version} || $self->schema_version;
-sub ordered_schema_versions {
- ## override this method
+ $self->install_resultsource({
+ result_source => $self->version_storage->version_rs->result_source,
+ version => $version,
+ });
}
-method upgrade {
- my $db_version = $self->get_db_version();
-
- # db unversioned
- unless ($db_version) {
- carp 'Upgrade not possible as database is unversioned. Please call install first.';
- return;
- }
-
- # db and schema at same version. do nothing
- if ( $db_version eq $self->schema_version ) {
- carp "Upgrade not necessary\n";
- return;
- }
-
- my @version_list = $self->ordered_schema_versions;
-
- # if nothing returned then we preload with min/max
- @version_list = ( $db_version, $self->schema_version )
- unless ( scalar(@version_list) );
-
- # catch the case of someone returning an arrayref
- @version_list = @{ $version_list[0] }
- if ( ref( $version_list[0] ) eq 'ARRAY' );
-
- # remove all versions in list above the required version
- while ( scalar(@version_list)
- && ( $version_list[-1] ne $self->schema_version ) )
- {
- pop @version_list;
- }
-
- # remove all versions in list below the current version
- while ( scalar(@version_list) && ( $version_list[0] ne $db_version ) ) {
- shift @version_list;
- }
-
- # check we have an appropriate list of versions
- if ( scalar(@version_list) < 2 ) {
- die;
- }
-
- # do sets of upgrade
- while ( scalar(@version_list) >= 2 ) {
- $self->upgrade_single_step( $version_list[0], $version_list[1] );
- shift @version_list;
- }
+sub prepare_install {
+ $_[0]->prepare_deploy;
+ $_[0]->prepare_version_storage_install;
}
-method upgrade_single_step($db_version, $target_version) {
- # db and schema at same version. do nothing
- if ($db_version eq $target_version) {
- carp "Upgrade not necessary\n";
- return;
- }
-
- # strangely the first time this is called can
- # differ to subsequent times. so we call it
- # here to be sure.
- # XXX - just fix it
- $self->storage->sqlt_type;
-
- my $upgrade_file = $self->ddl_filename(
- $self->storage->sqlt_type,
- $target_version,
- $self->upgrade_directory,
- $db_version,
- );
-
- $self->create_upgrade_path({ upgrade_file => $upgrade_file });
-
- unless (-f $upgrade_file) {
- carp "Upgrade not possible, no upgrade file found ($upgrade_file), please create one\n";
- return;
- }
-
- carp "DB version ($db_version) is lower than the schema version (".$self->schema_version."). Attempting upgrade.\n";
-
- # backup if necessary then apply upgrade
- $self->_filedata($self->_read_sql_file($upgrade_file));
- $self->backup() if($self->do_backup);
- $self->txn_do(sub { $self->do_upgrade() });
-
- # set row in dbix_class_schema_versions table
- $self->_set_db_version({version => $target_version});
-}
+# the following is just a hack so that ->version_storage
+# won't be lazy
+sub BUILD { $_[0]->version_storage }
+__PACKAGE__->meta->make_immutable;
-method do_upgrade {
- # just run all the commands (including inserts) in order
- $self->run_upgrade(qr/.*?/);
-}
+1;
-method run_upgrade($stm) {
- return unless ($self->_filedata);
- my @statements = grep { $_ =~ $stm } @{$self->_filedata};
- $self->_filedata([ grep { $_ !~ /$stm/i } @{$self->_filedata} ]);
+#vim: ts=2 sw=2 expandtab
- for (@statements) {
- $self->storage->debugobj->query_start($_) if $self->storage->debug;
- $self->apply_statement($_);
- $self->storage->debugobj->query_end($_) if $self->storage->debug;
- }
+__END__
- return 1;
-}
+=head1 SYNOPSIS
-method apply_statement($statement) {
- $self->storage->dbh->do($_) or carp "SQL was: $_";
-}
+ use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
+ my $s = My::Schema->connect(...);
-method get_db_version {
- my $vtable = $self->schema->resultset('VersionResult');
- my $version = $vtable->search(undef, {
- order_by => { -desc => 'installed' },
- rows => 1
- })->get_column('version')->next || 0;
- return $version;
-}
+ my $dh = DH->new({
+ schema => $s,
+ databases => 'SQLite',
+ sql_translator_args => { add_drop_table => 0 },
+ });
-method backup {
- ## Make each ::DBI::Foo do this
- $self->storage->backup($self->backup_directory());
-}
+ $dh->prepare_install;
-method connection {
- $self->next::method(@_);
- $self->_on_connect($_[3]);
- return $self;
-}
+ $dh->install;
-method _on_connect($args) {
- $args ||= {};
-
- $self->{vschema} = DBIx::Class::Version->connect(@{$self->storage->connect_info()});
- my $vtable = $self->{vschema}->resultset('Table');
-
- # useful when connecting from scripts etc
- return if ($args->{ignore_version} || ($ENV{DBIC_NO_VERSION_CHECK} && !exists $args->{ignore_version}));
-
- # check for legacy versions table and move to new if exists
- my $vschema_compat = DBIx::Class::VersionCompat->connect(@{$self->storage->connect_info()});
- unless ($self->_source_exists($vtable)) {
- my $vtable_compat = $vschema_compat->resultset('TableCompat');
- if ($self->_source_exists($vtable_compat)) {
- $self->{vschema}->deploy;
- map { $vtable->create({ installed => $_->Installed, version => $_->Version }) } $vtable_compat->all;
- $self->storage->dbh->do("DROP TABLE " . $vtable_compat->result_source->from);
- }
- }
-
- my $pversion = $self->get_db_version();
-
- if($pversion eq $self->schema_version)
- {
-# carp "This version is already installed\n";
- return 1;
- }
-
- if(!$pversion)
- {
- carp "Your DB is currently unversioned. Please call upgrade on your schema to sync the DB.\n";
- return 1;
- }
-
- carp "Versions out of sync. This is " . $self->schema_version .
- ", your database contains version $pversion, please call upgrade on your Schema.\n";
-}
+or for upgrades:
-sub _create_db_to_schema_diff {
- my $self = shift;
+ use aliased 'DBIx::Class::DeploymentHandler' => 'DH';
+ my $s = My::Schema->connect(...);
- my %driver_to_db_map = (
- 'mysql' => 'MySQL'
- );
+ my $dh = DH->new({
+ schema => $s,
+ databases => 'SQLite',
+ sql_translator_args => { add_drop_table => 0 },
+ });
- my $db = $driver_to_db_map{$self->storage->dbh->{Driver}{Name}};
- unless ($db) {
- print "Sorry, this is an unsupported DB\n";
- return;
- }
+ $dh->prepare_upgrade(1, 2);
- $self->throw_exception($self->storage->_sqlt_version_error)
- unless $self->storage->_sqlt_version_ok;
+ $dh->upgrade;
- my $db_tr = SQL::Translator->new({
- add_drop_table => 1,
- parser => 'DBI',
- parser_args => { dbh => $self->storage->dbh },
- producer => $db,
- });
+=head1 DESCRIPTION
- my $dbic_tr = SQL::Translator->new({
- parser => 'SQL::Translator::Parser::DBIx::Class',
- data => $self,
- producer => $db,
- });
+C<DBIx::Class::DeploymentHandler> is, as it's name suggests, a tool for
+deploying and upgrading databases with L<DBIx::Class>. It is designed to be
+much more flexible than L<DBIx::Class::Schema::Versioned>, hence the use of
+L<Moose> and lots of roles.
- $db_tr->schema->name('db_schema');
- $dbic_tr->schema->name('dbic_schema');
-
- # is this really necessary?
- foreach my $tr ($db_tr, $dbic_tr) {
- my $data = $tr->data;
- $tr->parser->($tr, $$data);
- }
-
- my $diff = SQL::Translator::Diff::schema_diff(
- $db_tr->schema, $db,
- $dbic_tr->schema, $db, {
- ignore_constraint_names => 1,
- ignore_index_names => 1,
- caseopt => 1,
- }
- );
-
- my $filename = $self->ddl_filename(
- $db,
- $self->schema_version,
- $self->upgrade_directory,
- 'PRE',
- );
-
- open my $file, '>', $filename
- or $self->throw_exception("Can't open $filename for writing ($!)");
- print {$file} $diff;
- close $file;
-
- carp "WARNING: There may be differences between your DB and your DBIC schema.\n" .
- "Please review and if necessary run the SQL in $filename to sync your DB.\n";
-}
+C<DBIx::Class::DeploymentHandler> itself is just a recommended set of roles
+that we think will not only work well for everyone, but will also yeild the
+best overall mileage. Each role it uses has it's own nuances and
+documentation, so I won't describe all of them here, but here are a few of the
+major benefits over how L<DBIx::Class::Schema::Versioned> worked (and
+L<DBIx::Class::DeploymentHandler::Deprecated> tries to maintain compatibility
+with):
-method _read_sql_file($file) {
- return unless $file;
+=over
- open my $fh, '<', $file or carp("Can't open upgrade file, $file ($!)");
- my @data = split /\n/, join '', <$fh>;
- close $fh;
+=item *
- @data = grep {
- $_ &&
- !/^--/ &&
- !/^(BEGIN|BEGIN TRANSACTION|COMMIT)/m
- } split /;/,
- join '', @data;
+Downgrades in addition to upgrades.
- return \@data;
-}
+=item *
-method _source_exists($rs) {
- my $c = eval {
- $rs->search({ 1, 0 })->count;
- };
- return 0 if $@ || !defined $c;
+Multiple sql files files per upgrade/downgrade/install.
- return 1;
-}
+=item *
-1;
+Perl scripts allowed for upgrade/downgrade/install.
+
+=item *
+
+Just one set of files needed for upgrade, unlike before where one might need
+to generate C<factorial(scalar @versions)>, which is just silly.
+
+=item *
+
+And much, much more!
+
+=back
+
+That's really just a taste of some of the differences. Check out each role for
+all the details.
+
+=head1 WHERE IS ALL THE DOC?!
+
+C<DBIx::Class::DeploymentHandler> extends
+L<DBIx::Class::DeploymentHandler::Dad>, 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 pieces that fill in the blanks that
+L<DBIx::Class::DeploymentHandler::Dad> expects to be filled. They would be
+L<DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator>,
+L<DBIx::Class::DeploymentHandler::VersionHandler::Monotonic>,
+L<DBIx::Class::DeploymentHandler::VersionStorage::Standard>, and
+L<DBIx::Class::DeploymentHandler::WithReasonableDefaults>.
+
+=method prepare_version_storage_install
+
+ $dh->prepare_version_storage_install
+
+Creates the needed C<.sql> file to install the version storage and not the rest
+of the tables
+
+=method prepare_install
+
+ $dh->prepare_install
+
+First prepare all the tables to be installed and the prepare just the version
+storage
+
+=method install_version_storage
+
+ $dh->install_version_storage
+
+Install the version storage and not the rest of the tables
+
+=head1 THIS SUCKS
+
+You started your project and weren't using C<DBIx::Class::DeploymentHandler>?
+Lucky for you I had you in mind when I wrote this doc.
+
+First off, you'll want to just install the C<version_storage>:
+
+ my $s = My::Schema->connect(...);
+ my $dh = DBIx::Class::DeploymentHandler->({ schema => $s });
+
+ $dh->prepare_version_storage_install;
+ $dh->install_version_storage;
+
+Then set your database version:
+
+ $dh->add_database_version({ version => $s->version });
+
+Now you should be able to use C<DBIx::Class::DeploymentHandler> like normal!
+
+=head1 LOGGING
+
+This is a complex tool, and because of that sometimes you'll want to see
+what exactly is happening. The best way to do that is to use the built in
+logging functionality. It the standard six log levels; C<fatal>, C<error>,
+C<warn>, C<info>, C<debug>, and C<trace>. Most of those are pretty self
+explanatory. Generally a safe level to see what all is going on is debug,
+which will give you everything except for the exact SQL being run.
+
+To enable the various logging levels all you need to do is set an environment
+variables: C<DBICDH_FATAL>, C<DBICDH_ERROR>, C<DBICDH_WARN>, C<DBICDH_INFO>,
+C<DBICDH_DEBUG>, and C<DBICDH_TRACE>. Each level can be set on it's own,
+but the default is the first three on and the last three off, and the levels
+cascade, so if you turn on trace the rest will turn on automatically.
+
+=head1 DONATIONS
+
+If you'd like to thank me for the work I've done on this module, don't give me
+a donation. I spend a lot of free time creating free software, but I do it
+because I love it.
+
+Instead, consider donating to someone who might actually need it. Obviously
+you should do research when donating to a charity, so don't just take my word
+on this. I like Children's Survival Fund:
+L<http://www.childrenssurvivalfund.org>, but there are a host of other
+charities that can do much more good than I will with your money.
projects / dbsrgits/DBIx-Class-DeploymentHandler.git / blobdiff