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

FreeBSD Manual Pages

  
 
  

home | help
DBIx::Class::DDBIx::ClUser:ContributedaPerlrDocumentationd::SQL::Translator(3)

NAME
       DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator - Manage
       your SQL	and Perl migrations in nicely laid out directories

DESCRIPTION
       This class is the meat of DBIx::Class::DeploymentHandler.  It takes
       care of generating serialized schemata  as well as sql files to move
       from one	version	of a schema to the rest.  One of the hallmark features
       of this class is	that it	allows for multiple sql	files for deploy and
       upgrade,	allowing developers to fine tune deployment.  In addition it
       also allows for perl files to be	run at any stage of the	process.

       For basic usage see DBIx::Class::DeploymentHandler::HandlesDeploy.
       What's documented here is extra fun stuff or private methods.

DIRECTORY LAYOUT
       Arguably	this is	the best feature of DBIx::Class::DeploymentHandler.
       It's spiritually	based upon DBIx::Migration::Directories, but has a lot
       of extensions and modifications,	so even	if you are familiar with it,
       please read this.  I feel like the best way to describe the layout is
       with the	following example:

	$sql_migration_dir
	|- _source
	|  |- deploy
	|     |- 1
	|     |	 `- 001-auto.yml
	|     |- 2
	|     |	 `- 001-auto.yml
	|     `- 3
	|	 `- 001-auto.yml
	|- SQLite
	|  |- downgrade
	|  |  `- 2-1
	|  |	 `- 001-auto.sql
	|  |- deploy
	|  |  `- 1
	|  |	 `- 001-auto.sql
	|  `- upgrade
	|     |- 1-2
	|     |	 `- 001-auto.sql
	|     `- 2-3
	|	 `- 001-auto.sql
	|- _common
	|  |- downgrade
	|  |  `- 2-1
	|  |	 `- 002-remove-customers.pl
	|  `- upgrade
	|     `- 1-2
	|     |	 `- 002-generate-customers.pl
	|     `- _any
	|	 `- 999-bump-action.pl
	`- MySQL
	   |- downgrade
	   |  `- 2-1
	   |	 `- 001-auto.sql
	   |- initialize
	   |  `- 1
	   |	 |- 001-create_database.pl
	   |	 `- 002-create_users_and_permissions.pl
	   |- deploy
	   |  `- 1
	   |	 `- 001-auto.sql
	   `- upgrade
	      `- 1-2
		 `- 001-auto.sql

       So basically, the code

	$dm->deploy(1)

       on an "SQLite" database that would simply run
       "$sql_migration_dir/SQLite/deploy/1/001-auto.sql".  Next,

	$dm->upgrade_single_step([1,2])

       would run "$sql_migration_dir/SQLite/upgrade/1-2/001-auto.sql" followed
       by "$sql_migration_dir/_common/upgrade/1-2/002-generate-customers.pl",
       and finally punctuated by
       "$sql_migration_dir/_common/upgrade/_any/999-bump-action.pl".

       ".pl" files don't have to be in the "_common" directory,	but most of
       the time	they should be,	because	perl scripts are generally database
       independent.

       Note that unlike	most steps in the process, "initialize"	will not run
       SQL, as there may not even be an	database at initialize time.  It will
       run perl	scripts	just like the other steps in the process, but nothing
       is passed to them.  Until people	have used this more it will remain
       freeform, but a recommended use of initialize is	to have	it prompt for
       username	and password, and then call the	appropriate "CREATE DATABASE"
       commands	etc.

   Directory Specification
       The following subdirectories are	recognized by this DeployMethod:

       "_source"
	 This directory	can contain the	following directories:

	 "deploy"
	   This	directory merely contains directories named after schema
	   versions, which in turn contain "yaml" files	that are serialized
	   versions of the schema at that version.  These files	are not	for
	   editing by hand.

       "_preprocess_schema"
	 This directory	can contain the	following directories:

	 "downgrade"
	   This	directory merely contains directories named after migrations,
	   which are of	the form "$from_version-$to_version".  Inside of these
	   directories you may put Perl	scripts	which are to return a subref
	   that	takes the arguments "$from_schema, $to_schema",	which are
	   SQL::Translator::Schema objects.

	 "upgrade"
	   This	directory merely contains directories named after migrations,
	   which are of	the form "$from_version-$to_version".  Inside of these
	   directories you may put Perl	scripts	which are to return a subref
	   that	takes the arguments "$from_schema, $to_schema",	which are
	   SQL::Translator::Schema objects.

	 A typical usage of "_preprocess_schema" is to define indices or other
	 non-DBIC type metadata.  Here is an example of	how one	might do that:

	 The following coderef could be	placed in a file called
	 _preprocess_schema/1-2/001-add-user-index.pl

	  sub {
	     my	($from,	$to) = @_;

	     $to->get_table('Users')->add_index(
		name =>	'idx_Users_name',
		fields => ['name'],
	     )
	  }

	 This would ensure that	in version 2 of	the schema the generated
	 migrations include an index on	"Users.name".  Frustratingly, due to
	 the nature of SQL::Translator,	you'll need to add this	to each
	 migration or it will detect that it was left out and kindly remove
	 the index for you.

	 An alternative	to the above, which is likely to be a lot less
	 annoying, is to define	such data in your schema directly, and only
	 change	it as you need to:

	  package MyApp::Schema::Result::User;

	  #[...]

	  sub sqlt_deploy_hook ( $self,	$sqlt_table ) {
	     $sqlt_table->add_index(name => 'idx_Users_name', fields =>	[ 'name' ]);
	  }

       $storage_type
	 This is a set of scripts that gets run	depending on what your storage
	 type is.  If you are not sure what your storage type is, take a look
	 at the	producers listed for SQL::Translator.  Also note, "_common" is
	 a special case.  "_common" will get merged into whatever other	files
	 you already have.  This directory can contain the following
	 directories itself:

	 "initialize"
	   If you are using the	"initialize" functionality, you	should call
	   initialize()	before calling "install". This has the same structure
	   as the "deploy" subdirectory	as well; that is, it has a directory
	   for each schema version.  Unlike "deploy", "upgrade", and
	   "downgrade" though, it can only run ".pl" files, and	the coderef in
	   the perl files get no arguments passed to them.

	 "deploy"
	   Gets	run when the schema is "deploy"ed.  Structure is a directory
	   per schema version, and then	files are merged with "_common"	and
	   run in filename order.  ".sql" files	are merely run,	as expected.
	   ".pl" files are run according to "PERL SCRIPTS".

	 "upgrade"
	   Gets	run when the schema is "upgrade"d.  Structure is a directory
	   per upgrade step, (for example, "1-2" for upgrading from version 1
	   to version 2,) and then files are merged with "_common" and run in
	   filename order.  ".sql" files are merely run, as expected.  ".pl"
	   files are run according to "PERL SCRIPTS".

	 "downgrade"
	   Gets	run when the schema is "downgrade"d.  Structure	is a directory
	   per downgrade step, (for example, "2-1" for downgrading from
	   version 2 to	version	1,) and	then files are merged with "_common"
	   and run in filename order.  ".sql" files are	merely run, as
	   expected.  ".pl" files are run according to "PERL SCRIPTS".

       Note that there can be an "_any"	in the place of	any of the versions
       (like "1-2" or 1), which	means those scripts will be run	every time.
       So if you have an "_any"	in "_common/upgrade", that script will get run
       for every upgrade.

PERL SCRIPTS
       A perl script for this tool is very simple.  It merely needs to contain
       an anonymous sub	that takes a DBIx::Class::Schema and the version set
       as it's arguments.

       A very basic perl script	might look like:

	#!perl

	use strict;
	use warnings;

	use DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator::ScriptHelpers
	   'schema_from_schema_loader';

	schema_from_schema_loader({ naming => 'v4' }, sub {
	  my $schema = shift;

	  # [1]	for deploy, [1,2] for upgrade or downgrade, probably used with _any
	  my $versions = shift;

	  $schema->resultset('Users')->create({
	    name => 'root',
	    password =>	'root',
	  })
	})

       Note that the above uses	"schema_from_schema_loader" in
       DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator::ScriptHelpers.
       Using a raw coderef is strongly discouraged as it is likely to break as
       you modify your schema.

SEE ALSO
       This class is an	implementation of
       DBIx::Class::DeploymentHandler::HandlesDeploy.  Pretty much all the
       documentation is	there.

ATTRIBUTES
   ignore_ddl
       This attribute will, when set to	true (default is false), cause the DM
       to use SQL::Translator to use the "_source"'s serialized
       SQL::Translator::Schema instead of any pregenerated SQL.	 If you	have a
       development server this is probably the best plan of action as you will
       not be putting as many generated	files in your version control.	Goes
       well with with "databases" of "[]".

   force_overwrite
       When this attribute is true generated files will	be overwritten when
       the methods which create	such files are run again.  The default is
       false, in which case the	program	will die with a	message	saying which
       file needs to be	deleted.

   schema
       The DBIx::Class::Schema (required) that is used to talk to the database
       and generate the	DDL.

   storage
       The DBIx::Class::Storage	that is	actually used to talk to the database
       and generate the	DDL.  This is automatically created with
       "_build_storage".

   sql_translator_args
       The arguments that get passed to	SQL::Translator	when it's used.

   script_directory
       The directory (default 'sql') that scripts are stored in

   databases
       The types of databases (default "[qw( MySQL SQLite PostgreSQL )]") to
       generate	files for

   txn_wrap
       Set to true (which is the default) to wrap all upgrades and deploys in
       a single	transaction.

   schema_version
       The version the schema on your harddrive	is at.	Defaults to
       "$self->schema->schema_version".

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.

perl v5.24.1  DBIx::Class::DeploymentHandler::DeployMethod::SQL::Translator(3)

NAME | DESCRIPTION | DIRECTORY LAYOUT | PERL SCRIPTS | SEE ALSO | ATTRIBUTES | AUTHOR | COPYRIGHT AND LICENSE

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

home | help