migration¶

This contains an instance of DBIx::Class::Migration which is constructed from various attributes described futher in these docs.

This is basically a delegate for all the commands you perform with this interface.

includes¶

Accepts ArrayRef. Not required.

Similar to the commandline switch "I" for the "perl" interpreter. It adds to @INC for when we want to search for modules to load. This is primarily useful for specifying a path to find a "schema_class".

We make no attempt to check the validity of any paths specified. Buyer beware.

schema_class¶

Accepts Str. Required.

This is the schema we use as the basic for creating, managing and running your deployments. This should be the full package namespace defining your subclass of DBIx::Class::Schema. For example "MyApp::Schema".

Uses MooX::Attribute::ENV to let you populate values from %ENV. Uses key DBIC_MIGRATION_SCHEMA_CLASS

If the "schema_class" cannot be loaded, a hard exception will be thrown.

target_dir¶

Accepts Str. Required.

This is the directory we store our migration and fixture files. Inside this directory we will create a "fixtures" and "migrations" sub-directory.

Although you can specify the directory, if you leave it undefined, we will use File::ShareDir::ProjectDistDir to locate the "share" directory for your project and place the files there. This is the recommended approach, and is considered a community practice in regards to where to store your distribution non code files. Please see File::ShareDir::ProjectDistDir as well as File::ShareDir for more information.

Uses MooX::Attribute::ENV to let you populate values from %ENV. Uses key DBIC_MIGRATION_TARGET_DIR

sandbox_dir¶

Accepts Str. Optional

Used if you wish to build the sandbox (if you are building one) in a location that is not the 'target_dir'. For example you might do this to make it easier to not accidentally check the sandbox into the repository or if you are reusing it across several projects.

username¶

Accepts Str. Not Required

This should be the username for the database we connect to for deploying ddl, ddl changes and fixtures.

Uses MooX::Attribute::ENV to let you populate values from %ENV. Uses key DBIC_MIGRATION_USERNAME

password¶

Accepts Str. Not Required

This should be the password for the database we connect to for deploying ddl, ddl changes and fixtures.

Uses MooX::Attribute::ENV to let you populate values from %ENV. Uses key DBIC_MIGRATION_PASSWORD

dsn¶

Accepts Str. Not Required

This is the DSN for the database you are going to be targeting for deploying or altering ddl, and installing or generating fixtures.

This should be a DSN suitable for "connect" in DBIx::Class::Schema, something in the form of "DBI:SQLite:myapp-schema.db".

Please take care where you point this (like production :) )

If you don't provide a value, we will automatically create a SQLite based database connection with the following DSN:

    DBD:SQLite:[path to target_dir]/[db_file_name].db

Where c<[path to target_dir]> is "target_dir" and [db_file_name] is a converted version of "schema_class". For example if you set schema_class to:

    MyApp::Schema

Then [db_file_name] would be "myapp-schema".

Please remember that you can generate deployment files for database types other than the one you've defined in "dsn", however since different databases enforce constraints differently it would not be impossible to generate fixtures that can be loaded by one database but not another. Therefore I recommend always generated fixtures from a database that is consistent across enviroments.

Uses MooX::Attribute::ENV to let you populate values from %ENV. Uses key DBIC_MIGRATION_DSN

force_overwrite¶

Accepts Bool. Not Required. Defaults to False.

Used when building "migration" to en / disable the DBIx::Class::DeploymentHandler option "force_overwrite". This is used when generating DDL and related files for a given version of your "_schema" to decide if it is ok to overwrite deployment files. You might need this if you deploy a version of the database during development and then need to make more changes or fixes for that version.

to_version¶

Accepts Int. Not Required.

Used to establish a target version when running an install. You can use this to force install a version of the database other then your current "_schema" version. You might want this when you need to force install a lower version as part of your development process for changing the database.

If you leave this undefined, no default value is built, however DBIx::Class::DeploymentHandler will assume you want whatever is the value of your $schema->version.

databases¶

Accepts ArrayRef. Not Required.

Used when building "migration" to define the target databases we are building migration files for. You can name any of the databases currently supported by SQL::Translator. If you leave this undefined we will derive a value based on the value of "dsn". For example, if your "dsn" is "DBI:SQLite:test.db", we will set the value of "databases" to "['SQLite']".

sql_translator_args¶

Accepts HashRef. Not Required.

Used when building "migration" to set the DBIx::Class::DeploymentHandler option "sql_translator_args". This can be used to specify options for SQL::Translator, for example:

    producer_args => { postgres_version => '9.1' }

to define the database version for SQL producer. Defaults to setting "quote_identifiers" to a true value, which despite being documented as the default, is not the case in practice.

fixture_sets¶

Accepts ArrayRef. Not Required. Defaults to ['all_tables'].

This defines a list of fixture sets that we use for dumping or populating fixtures. Defaults to the "['all_tables']" set, which is the one set we build automatically for each version of the database we prepare deployments for.

sandbox_class¶

Accepts String. Not required. Defaults to 'SqliteSandbox'

If you don't have a database already running, we will automatically create a database 'sandbox' in your "target_dir" that is suitable for development and rapid prototyping. This is intended for developers and intended to make life more simple, particularly for beginners who might not have all the knowledged needed to setup a database for development purposes.

By default this sandbox is a file based DBD::Sqlite database, which is an easy option since changes are good this is already installed on your development computer (and if not it is trivial to install).

You can change this to either 'PostgresqlSandbox' or 'MySQLSandbox', which will create a sandbox using either DBIx::Class::Migration::MySQLSandbox or DBIx::Class::Migration::PostgresqlSandbox (which in term require the separate installation of either Test::mysqld or Test::Postgresql58). If you are using one of those open source databases in production, its probably a good idea to use them in development as well, since there are enough small differences between them that could make your code break if you used sqlite for development and postgresql in production. However this requires a bit more setup effort, so when you are starting off just sticking to the default sqlite is probably the easiest thing to do.

You should review the documenation at DBIx::Class::Migration::MySQLSandbox or DBIx::Class::Migration::PostgresqlSandbox because those delegates also build some helper scripts, intended to help you use a sandbox.

Uses MooX::Attribute::ENV to let you populate values from %ENV. Uses key DBIC_MIGRATION_SANDBOX_CLASS

If you need to create your own custom database sandboxes, please see: DBIx::Class::Migration::Sandbox which is the role your sandbox factory needs to complete. You can signify your custom sandbox by using the full package name with a '+' prepended. For example:

    sandbox_class => '+MyApp::Schema::CustomSandbox'

You should probably look at the existing sandbox code for thoughts on what a good sandbox would do.

migration_class¶

Accepts String. Not Required (Defaults: DBIx::Class::Migration)

Should point to the class that does what DBIx::Class::Migration does. This is exposed here for those who need to subclass DBIx::Class::Migration. We don't expose this attribute to the commandline, so if you are smart enough to do the subclassing (and sure you need to do that), I will assume you will also either subclass DBIx::Class::Migration:Script or override then default value using some standard technique.

dbic_fixture_class¶

Accepts: Str, Not Required.

You can use this if you need to make a custom subclass of DBIx::Class::Fixtures.

dbic_fixtures_extra_args¶

Accepts: HashRef, Not Required.

If provided will add some additional arguments when creating an instance of "dbic_fixture_class". You should take a look at the documentation for DBIx::Class::Fixtures to understand what additional arguments may be of use.

dbi_connect_attrs¶

Accepts: HashRef, Not Required.

If you are specifying a DSN, you might need to provide some additional args to DBI (see "connect_info" in DBIx::Class::Storage::DBI for more).

dbic_connect_attrs¶

Accepts: HashRef, Not Required.

If you are specifying a DSN, you might need to provide some additional args to DBIx::Class (see "connect_info" in DBIx::Class::Storage::DBI for more).

You can also see "DBIx::Class-specific-connection-attributes" in DBIx::Class::Storage::DBI for more information on what this can do for you. Chances are good if you need this you will also want to subclass DBIx::Class::Migration::Script as well.

Common uses for this is to run SQL on startup and set Postgresql search paths.

extra_schemaloader_args¶

Accepts: HashRef, Not Required.

Used to populate "extra_schemaloader_args" in DBIx::Class::Migration

migration_sandbox_builder_class¶

Accepts: String (Classname), Not Required.

Used to set "db_sandbox_builder_class" in DBIx::Class::Migration. You probably won't mess with this unless you are writing your own Sandbox builder class, or using the alternative builder DBIx::Class::Migration::TempDirSandboxBuilder for creating temporary sandboxes when you want to test your migrations.

help¶

See DBIx::Class::Migration::Script::Help::help.

version¶

See DBIx::Class::Migration::Script::Help::version.

status¶

See DBIx::Class::Migration::Script::Help::status.

prepare¶

See DBIx::Class::Migration::Script::Help::prepare.

install¶

See DBIx::Class::Migration::Script::Help::install.

upgrade¶

See DBIx::Class::Migration::Script::Help::upgrade.

downgrade¶

See DBIx::Class::Migration::Script::Help::downgrade.

dump_named_sets¶

See DBIx::Class::Migration::Script::Help::dump_named_sets.

dump_all_sets¶

See DBIx::Class::Migration::Script::Help::dump_all_sets.

populate¶

See DBIx::Class::Migration::Script::Help::populate.

drop_tables¶

See DBIx::Class::Migration::Script::Help::drop_tables.

delete_table_rows¶

See DBIx::Class::Migration::Script::Help::delete_table_rows.

make_schema¶

See DBIx::Class::Migration::Script::Help::make_schema.

install_if_needed¶

See DBIx::Class::Migration::Script::Help::install_if_needed.

install_version_storage¶

See DBIx::Class::Migration::Script::Help::install_version_storage.

diagram¶

See DBIx::Class::Migration::Script::Help::diagram.

delete_named_sets¶

See DBIx::Class::Migration::Script::Help::delete_named_sets.

Command Flags¶

The following flags are used to modify or inform commands.

includes

See DBIx::Class::Migration::Script::Help::includes.

schema_class

See DBIx::Class::Migration::Script::Help::schema_class.

target_dir

See DBIx::Class::Migration::Script::Help::target_dir.

username

Aliases: U Value: Str

password

Aliases: P Value: String

dsn

Value: String

These three commandline flags describe how to connect to a target, physical database, where we will deploy migrations and fixtures. If you don't provide them, we will automatically deploy to a DBD::SQLite managed database located at "target_dir".

    dbic-migration install --username myuser --password mypass --dsn DBI:SQLite:mydb.db

force_overwrite

See DBIx::Class::Migration::Script::Help::force_overwrite

to_version

See DBIx::Class::Migration::Script::Help::to_version

databases

See DBIx::Class::Migration::Script::Help::databases

fixture_sets

See DBIx::Class::Migration::Script::Help::fixture_sets

sandbox_class

See DBIx::Class::Migration::Script::Help::sandbox_class

The default sqlite sandbox is documented at DBIx::Class::Migration::SQLiteSandbox although this single file database is pretty straightforward to use.

If you are declaring the value in a subclass, you can use the pre-defined constants to avoid typos (see "CONSTANTS").

dbic_fixture_class

See DBIx::Class::Migration::Script::Help::dbic_fixture_class

dbic_fixtures_extra_args

See DBIx::Class::Migration::Script::Help::dbic_fixtures_extra_args

dbic_connect_attrs

See DBIx::Class::Migration::Script::Help::dbic_connect_attrs

dbi_connect_attrs

See DBIx::Class::Migration::Script::Help::dbi_connect_attrs

extra_schemaloader_args

See DBIx::Class::Migration::Script::Help::extra_schemaloader_args

default¶

Returns a Hash of instantiation values.

Merges some predefined values when instantiating. For example:

    package MusicBase::Schema::MigrationScript;
    use Moose;
    use MusicBase::Web;
    extends 'DBIx::Class::Migration::Script';
    sub defaults {
      schema => MusicBase::Web->model('Schema')->schema,
    }
    __PACKAGE__->meta->make_immutable;
    __PACKAGE__->run_if_script;

This would create a version of your script that already includes the target "schema". In this example we will let Catalyst configuration handle which database to run deployments against.

run_if_script¶

Class method that detects if your module is being called as a script. Place it at the end of your subclass:

    __PACKAGE__->run_if_script;

This returns true in the case you are using the class as a module, and calls "run_with_options" otherwise. Adding this lets you invoke your class module as a script from the commandline (saving you the trouble of writing a thin script wrapper).

    perl -Ilib lib/MyApp/Schema/MigrationScript.pm --status

run_with_options¶

Given a Hash of initial arguments, merges those with the results of values passed on the commandline (via MooX::Options) and run.

run¶

Actually runs commands.

SANDBOX_SQLITE¶

SqliteSandbox

SANDBOX_MYSQL¶

MySQLSandbox

SANDBOX_POSTGRESQL¶

PostgresqlSandbox

Prepare deployment files for a schema¶

    dbic-migration prepare --schema_class MyApp::Schema

This will prepare deployment files for just SQLite

    dbic-migration prepare --database SQLite --database MySQL \
      --schema_class MyApp::Schema

This will prepare deployment files for both SQLite and MySQL

Install database from deployments¶

    dbic-migration install --schema_class MyApp::Schema

Creates the default sqlite database in the "share" directory.

    dbic-migration install --schema_class MyApp::Schema --to_version 2

Same as the previous command, but installs version 2, instead of whatever is the most recent version

    dbic-migration populate --schema_class MyApp::Schema --fixture_set seed

Populates the "seed" fixture set to the current database (matches the database version to the seed version.)