Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DBIx::VersionedDDL(3) User Contributed Perl DocumentationDBIx::VersionedDDL(3)

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

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   user. The database user account

       o   pass. The user password.

       o   dsn.	The database DSN

       o   ddl_dir. The	directory that hosts the migration scripts

       o   debug. Whether debug	messages are shown

       o   dbh.	An active database handle. This	can be used as an alternative
	   to the user,	pass and dsn parameters

       o   script_processor. 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.

perl v5.32.1			  2012-12-01		 DBIx::VersionedDDL(3)

NAME | VERSION | SYNOPSIS | METHODS | PROVIDING YOUR OWN PROCESSOR VIA A PLUGIN | SCHEMA DEFINITION | SEE ALSO | AUTHOR | ACKNOWLEDGEMENTS | BUGS | SUPPORT | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DBIx::VersionedDDL&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help