GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DBIX::VERSIONEDDDL (3)

.ds Aq ’

NAME

DBIx::VersionedDDL - Upgrade and downgrade database schemas to a specified version.

CONTENTS

VERSION

Version 0.17

SYNOPSIS

This module is a utility that can upgrade or downgrade a schema.



    use DBIx::VersionedDDL;

    my $sv = DBIx::VersionedDDL->new(
        user => scott,
        pass => tiger,
        dsn  => DBI:Oracle:orcl,
        ddl_dir => /home/jdoe/ddl
    );
   
    # Migrate the schema to version 7.
    $sv->migrate(7);



or alternatively:



    use DBIx::VersionedDDL;

    my $dbh = DBI->connect(DBI:Oracle:orcl, scott, tiger);
   
    my $sv = DBIx::VersionedDDL->new(
        dbh     => $dbh,
        ddl_dir => /home/jdoe/ddl
    );
   
    # Migrate the schema to version 7.
    $sv->migrate(7);



DBIx::VersiondDDL installs a version table (schema_version) in the schema that stores the current version number of this schema. The developer or DBA who maintains the schema will place a series of upgrade and downgrade scripts in a ddl directory. The scripts will use the following naming convention:



    +-----------------+-------------------+
    | Upgrade Scripts | Downgrade Scripts |
    +-----------------+-------------------+
    | upgrade1.sql    | downgrade1.sql    |
    | upgrade2.sql    | downgrade2.sql    |
    | upgrade3.sql    | downgrade3.sql    |
    | upgrade4.sql    | downgrade4.sql    |
    | ....            | ....              |
    +-----------------+-------------------+



Each downgrade script reverses the changes of the upgrade script. The scripts to run are determined by the value in the version table If the current schema is at version 5 and the administrator wishes to upgrade to version 10, upgrade scripts 6-10 would be run by the utility, and the version table entry will be incremented at each step.

If the administrator wishes to downgrade to version 6, the utility will run downgrade scripts 10-7.

This utility expects SQL statements to be separated by semi-colons by default, but an explicit separator can be specified.

    Leaving the schema in an indeterminate state.

DDL statements are not transactionally aware, so you can not roll back if there is an error in your DDL. You will need to manually resolve such errors.

Any error will be saved to the schema_version table. The version number is set to the script that was running when the error was encountered.

    Supplying an active database handle

The database handle will autocommit any updates to the schema tables. If an active handle is supplied, it should not be shared with any external transactions. The best approach is to clone an active handle before passing it to the utility:



    my $dbh = DBI->connect(DBI:Oracle:orcl, scott, tiger);
   
    my $sv = DBIx::VersionedDDL->new(
        dbh     => $dbh->clone,
        ddl_dir => /home/jdoe/ddl
    );



The schema_version table has three columns:



    +---------+---------------------------------------------------+
    | Column  | Description                                       |
    +---------+---------------------------------------------------+
    | version | The current version of the schema                 |
    | status  | The status of the script that updated the version |
    |         | record. It will be either success or error    |
    | message | Any message generated when an error occurs        |
    +---------+---------------------------------------------------+



METHODS

    new

The following attributes can be supplied at creation time by passing values to the new method.
o <B>userB>. The database user account
o <B>passB>. The user password.
o <B>dsnB>. The database DSN
o <B>ddl_dirB>. The directory that hosts the migration scripts
o <B>debugB>. Whether debug messages are shown
o <B>dbhB>. An active database handle. This can be used as an alternative to the user, pass and dsn parameters
o <B>script_processorB>. Optional. A plugin that processes the migration scripts. See PROVIDING YOUR OWN PROCESSOR VIA A PLUGIN

    migrate

Migrate from the current schema version to the specified one:



    $sv->migrate(7);



If a version is not provided, the schema will be upgraded (or downgraded!) to the maximum version specified by upgrade(n).sql:



    $sv->migrate



    get_message

Returns the message value in the schema_version table

PROVIDING YOUR OWN PROCESSOR VIA A PLUGIN

You can supply your own functionality to parse migration scripts via a plugin. The plugin must contain a process_script method that takes a script name as an argument and returns an array of SQL statements. The name of your plugin can either be set in the environment variable SCRIPT_PROCESSOR or the script_processor attribute as part of the constructor. If your plugin is called DBIx::VersionedDDL::Plugin::MyProcessor, then SCRIPT_PROCESSOR should be set to MyProcessor.

For an example, refer to the source of DBIx::VersionedDDL::Plugin::DefaultScriptProcessor

    Populating plugin attributes

Any attributes should be populated once the Versioned object is created:



    my $sv = DBIx::VersionedDDL->new(
        user => scott,
        pass => tiger,
        dsn  => DBI:Oracle:orcl,
        ddl_dir => /home/jdoe/ddl
    );
   
    $sv->separator(/);



SCHEMA DEFINITION

The definition of a schema can differ between database products. For Oracle a schema is a:



    collection of database objects, including logical structures
    such as tables, views, sequences, stored procedures, synonyms,
    indexes, clusters, and database links. A schema has the name of
    the user who controls it.



In this context, the user parameter should be the owner of the schema. With other databases, such as MySQL, the schema is analogous to a database. The user parameter should be an account that has full privileges to the database so that it can apply the DDL and update the schema_version table.

SEE ALSO

migrate_schema is a script supplied with this distribution that supports the invocation of DBIx::VersionedDDL from the command line.



    migrate_schema -user=scott -pass=tiger -dsn=DBI:Oracle:orcl \
        -version=5 -ddl_dir=/my/ddl/dir



For more information:



    man migrate_schema



AUTHOR

Dan Horne, <dhorne at cpan.org>

ACKNOWLEDGEMENTS

Plugin functionality added by Jiri Pavlovsky.

BUGS

Please report any bugs or feature requests to bug-dbix-versionedddl at rt.cpan.org, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DBIx-VersionedDDL>. I will be notified, and then you’ll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.



    perldoc DBIx::VersionedDDL



You can also look for information at:
o RT: CPAN’s request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-VersionedDDL>

o AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/DBIx-VersionedDDL>

o CPAN Ratings

<http://cpanratings.perl.org/d/DBIx-VersionedDDL>

o Search CPAN

<http://search.cpan.org/dist/DBIx-VersionedDDL/>

COPYRIGHT & LICENSE

Copyright 2009-2010 Dan Horne.

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

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DBIX::VERSIONEDDDL (3) 2012-12-01

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.