db_sandbox_builder_class

The name of the helper class which builds the class that builds database sandboxs. By default we build database sandboxes in the "target_dir", which is what DBIx::Class::Migration::TargetDirSandboxBuilder does. We can also build database sandboxes in a temporary directory using DBIx::Class::Migration::TempDirSandboxBuilder. You might prefer that for running tests, for example.

db_sandbox_class

Unless you already have a database setup and running (as you probably do in production) we need to auto create a database 'sandbox' that is isolated to your development local. This class is a delegate that performs this job if you don't want to go to the trouble of installing and setting up a local database yourself.

This must point to a class that expects "target_dir" and "schema_class" for initialization arguments and must define a method "make_sandbox" that returns an array which can be sent to "connect" in DBIx::Class::Schema.

This defaults to DBIx::Class::Migration::SqliteSandbox. Currently we have support for MySQL and Postgresql via DBIx::Class::Migration::MySQLSandbox and DBIx::Class::Migration::PgSandbox, but you will need to side install Test::mysqld and Test::Postgresql58 (In other words you'd need to add these "Test::*" namespace modules to your "Makefile.PL" or "dist.ini").

db_sandbox

This is an instantiated object as defined by "db_sandbox_class". It is a delegate for the work of automatically creating a local database sandbox that is useful for developers and for quickly bootstrapping a project.

schema_class

This is the schema we use as the basis 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".

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

schema_args

Provides arguments passed to "connect" on your "schema_class". Should connect to a database.

This is an arrayref that would work the same as "connect" in DBIx::Class::Schema. If you choose to create an instance of DBIx::Class::Migration by providing a schema_class, you can use this to customize how we connect to a database.

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 "[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".

Basically, this means you can start testing your database designs right off without a lot of effort, just point at a schema_class and get deploying!

schema

If you already have a connected schema (subclass of DBIx::Class::Schema) you can simple point to it, skipping schema_class and schema_args. You might for example be using Catalyst and want to build deployments for a database that is listed in configuration:

    use MyCatalyst::App;
    use DBIx::Class::Migration;

    my $migration = DBIx::Class::Migration->new(
      schema => MyCatalyst::App->model('Schema')->schema,
      %{MyCatalyst::App->config->{extra_migration_init_args}};
    );

target_dir_builder_class

target_dir_builder

target_dir

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.

This uses whatever is in "schema_class" to determine your project (and look for a "share" directory, which you'll need to create in your project root). If you don't have a "schema_class" defined, you must have a "schema", and we'll infer the class via "ref($self->schema)".

NOTE: You'll need to make the "/share" directory if you are going to use the default option. We don't automatically create it for you.

schema_loader_class

Because your application subclass of DBIx::Class::Schema is going to change a lot, sometimes we need to generate our own schema and get one that is in a known, good state. Mostly this is used by the commands to drop tables and clear tables.

Defaults to DBIx::Class::Migration::SchemaLoader. You'll probably only need to change this if your database is crazy and you need to massage the init arguments to DBIx::Class::Schema::Loader.

schema_loader

This is a factory that provider autoloaded schema based on the current schema's database. It is automatically created and you are unlikely to need to set this manually.

dbic_fixture_class

This is the class we use when creating instances of DBIx::Class::Fixtures. You'll probably need to review the docs for that and understand how configuration rules work in order to best take advantage of the system.

Defaults to DBIx::Class::Fixtures. You'll probably not need to change this unless you have some unusual needs regarding fixtures.

dbic_fixtures_extra_args

Allows you to pass some additional arguments when creating instances of "dbic_fixture_class". These arguments can be used to override the default initial arguments.

deployment_handler_class

This is the class we use when creating instances of DBIx::Class::DeploymentHandler. It would be ideal that you review those docs in order to better understand the overall architecture of the system.

Defaults to DBIx::Class::DeploymentHandler. You'll probably not need to change this unless you need a custom deployment handler, and if you do, I can't be sure this framework will work correctly, particularly if you are not using monotonic versioning.

dbic_dh_args

Used to pass custom args when building a DBIx::Class::DeploymentHandler. Please see the docs for that class for more. Useful args might be "databases", "to_version" and "force_overwrite".

dbic_dh

You probably won't need to build your own deployment handler and pass it in (unlike schema, where it might actually be useful). Be careful it you do since this framework makes some assumptions about your deployment handler (for example we assume you are using the monotonic versioning).

When this attribute is lazily built, we merge "dbic_dh_args" with the following defaults:

      schema => Points to $self->schema
      script_directory => Points to catdir($self->target_dir, 'migrations')
      databases => Inferred from your connected schema, defaults to SQLite

"dbic_dh_args" will overwrite the defaults, if you pass them.

extra_schemaloader_args

Meaningful options are described at DBIx::Class::Schema::Loader::Base.

new

Specify a schema_class and optionally schema_args

    use DBIx::Class::Migration;
    my $migration = DBIx::Class::Migration->new(
      schema_class => 'MyApp::Schema',
      schema_args => [@connect_info],
    );

This is probably the most general approach, and is recommended unless you already have a connected instance of your DBIx::Class::Schema subclass.

"schema_args" would be anything you'd pass to "connect" in DBIx::Class::Schema. see "schema_args" for how we construct default connect information if you choose to leave this undefined.

Specify a schema

There may be some cases when you already have a schema object constructed and would prefer to just use that. For example, you may be using Catalyst and wish to build custom scripts using the built-in dependency and service lookup:

    use MyCatalyst::App;
    use DBIx::Class::Migration;

    my $migration = DBIx::Class::Migration->new(
      schema => MyCatalyst::App->model('Schema')->schema,
      %{MyCatalyst::App->config->{extra_migration_init_args}};
    );

Be careful of potential locking issues when using some databases like SQLite.

OPTIONAL: Specify a target_dir

Optionally, you can specify your migrations target directory (where your migrations get created), in your init arguments. This option can be combined with either approach listed above.

    use DBIx::Class::Migration;
    my $migration = DBIx::Class::Migration->new(
      schema_class => 'MyApp::Schema',
      schema_args => [@connect_info],
      target_dir => '/opt/database-migrations',
    );

If you leave this undefined we default to using the "share" directory in your distribution root. This is generally the community supported place for non code data, but if you have huge fixture sets you might wish to place them in an alternative location.

OPTIONAL: Specify a db_sandbox_dir

Be default if you allow for a local database sandbox (as you might during early development and you don't want to work to make a database) that sandbox gets built in the 'target_dir'. Since other bits in the target_dir are probably going to be in your project repository and the sandbox generally isnt, you might wish to build the sandbox in an alternative location. This setting allows that:

    use DBIx::Class::Migration;
    my $migration = DBIx::Class::Migration->new(
      schema_class => 'MyApp::Schema',
      schema_args => [@connect_info],
      db_sandbox_dir => '~/opt/database-sandbox',
    );

This then gives you a nice totally standalone database sandbox which you can reuse for other projects, etc.

OPTIONAL: Specify dbic_dh_args

Optionally, you can specify additional arguments to the constructor for the "dbic_dh" attribute. Useful arguments might include additional "databases" we should build fixtures for, "to_version" and "force_overwrite".

See "" in DBIx::Class::DeploymentHandler for more information on supported init arguments. See "dbic_dh" for how we merge default arguments with your custom arguments.

Other Initial Arguments

For normal usage the remaining init args are probably not particularly useful and reflect a desire for long term code flexibility and clean design.

version

status

prepare

The "migrations" directory reflects a directory structure as documented in DBIx::Class::DeploymentHandler.

If this is the first version, we create directories and initial DLL, etc. For versions greater than 1, we will also generate diffs and copy any fixture configs etc (as well as generating a fresh 'all_table.json' fixture config). For safety reasons, we never overwrite any fixture configs.

install

If you try to install to a database that has already been installed, you'll get an error. See "drop_tables".

upgrade

downgrade

drop_tables

delete_table_rows

dump_named_sets

dump_all_sets

make_schema

populate

Skips the table "dbix_class_deploymenthandler_versions", so you don't lose deployment info (this is different from "drop_tables" which does delete it.)

diagram

This is using the Graphviz producer (SQL::Translator::Producer::GraphViz) which in turn requires Graphviz. Since this is not always trivial to install, I do not require it. You will need to add it manually to your "Makefile.PL" or "dist.ini" and manage it yourself.

This feature is experimental and currently does not offer any options, as I am still determining the best way to meet the need without exceeding the scope of DBIx::Class::Migration. Consider this command a 'freebee' and please don't depend on it in your custom code.

install_if_needed

    $migration->install_if_needed(
      on_install => sub {
        my ($schema, $local_migration) = @_;
        DBIx::Class::Migration::Population->new(
          schema=>shift)->populate('all_tables');
      });

The following callbacks / instructions are permitted

on_install

Accepts: Coderef

Given a coderef, execute it after the database is installed. The coderef gets passed two arguments: $schema and $self (the current migration object).

default_fixture_sets

Accepts: Arrayref of fixture sets

    $migration->install_if_needed(
      default_fixture_sets => ['all_tables']);
    

After database installation, populate the fixtures in order.

install_version_storage

You will only need to use this command in the case where you have an existing database that you are reverse engineering and you need to setup versioning storage since you can't rebuild the database from scratch (such as if you have a huge production database that you now want to start versioning).

delete_named_sets

Yes, this really deletes, you've been warned (check in your code to a source control repository).