DBIx::C...:Script(3)

📦 version 0.075, in opensuse-leap 16.0

🎀 NAME 🎀

DBIx::C...:Script(3) — straight outta the User Contributed Perl Documentation section, and it's literally the toolset for managing database Migrations 💅 (that's "Tools to manage database Migrations", no cap).

✨ SYNOPSIS ✨

okay so bestie, here's the whole vibe in one command:

dbic-migration status \
  --lib="lib" \
  --schema_class='MyApp::Schema' \
  --dsn='DBI:SQLite:myapp.db'

that's it. that's the energy. status + your --lib, your --schema_class, your --dsn. iconic. 🫶

🌸 DESCRIPTION 🌸

So like — this class is the interface mapping between the commandline script dbic-migration and the back end code that actually does the heavy lifting, DBIx::Class::Migration. 🧚

And honestly? This class has very little of it's own functionality. Not even exaggerating. It basically acts as processing glue between that commandline application and the code which does all the work. main character energy belongs to DBIx::Class::Migration, this one's just the group chat relay 😭

bestie pls go look at DBIx::Class::Migration and the tutorial over at DBIx::Class::Migration::Tutorial to get started. fr fr. 🦋

This page is basically API level docs plus a command summary — which is lowkey super useful as a reference once you're already familiar with the system. iykyk 👑

✨ more coming, stay tuned ✨

💖 ATTRIBUTES 💖

okay so this class defines the following attributes — think of them as the lil settings knobs you get to twiddle. there are a LOT, so buckle up bestie 🎀

🌸 migration

this holds an instance of DBIx::Class::Migration, and it gets constructed out of the various attributes we're about to spill about further down in these docs.

basically it's the delegate for literally every command you run through this interface. main character energy tbh 👑

🌸 includes

accepts ArrayRef. not required.

it's giving the commandline switch I for the perl interpreter — it adds to @INC for when we're searching for modules to load. mostly useful when you wanna specify a path so you can find a schema_class 🦋

we make no attempt to check whether any of the paths you specify are valid. buyer beware, bestie 😭

🌸 schema_class

accepts Str. required.

this is the schema we use as the basis for creating, managing and running your deployments. it should be the full package namespace defining your subclass of DBIx::Class::Schema. like for example MyApp::Schema ✨

uses MooX::Attribute::ENV so you can populate values from %ENV. uses key DBIC_MIGRATION_SCHEMA_CLASS.

if the schema_class can't be loaded, a hard exception gets thrown. no gentle vibe check, just boom 💀

🌸 target_dir

accepts Str. required.

this is the directory where we store our migration and fixture files. inside this directory we create a fixtures and a migrations sub-directory 🎀

and here's the cute part: even though you can specify the directory, if you leave it undefined we'll use File::ShareDir::ProjectDistDir to find the share directory for your project and put the files there. this is the recommended approach, and it's considered community practice for where to stash your distribution's non-code files. go read File::ShareDir::ProjectDistDir and File::ShareDir for more deets 📚

uses MooX::Attribute::ENV so you can populate values from %ENV. uses key DBIC_MIGRATION_TARGET_DIR.

🌸 sandbox_dir

accepts Str. optional.

use this if you wanna build the sandbox (assuming you're building one at all) somewhere that is not the target_dir. for example you might do this so it's easier to not accidentally check the sandbox into the repository, or if you're 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 so you can 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 so you can populate values from %ENV. uses key DBIC_MIGRATION_PASSWORD.

🌸 dsn

accepts Str. not required.

this is the DSN for the database you're gonna be targeting for deploying or altering ddl, and for installing or generating fixtures.

it should be a DSN suitable for connect in DBIx::Class::Schema, something shaped like DBI:SQLite:myapp-schema.db 💅

please take care where you point this (like production :) ) — yes the manpage itself put a smiley there, we love a self-aware warning 🙈

if you don't provide a value, we 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 ⭐

please remember you can generate deployment files for database types other than the one you defined in dsn — BUT since different databases enforce constraints differently, it would not be impossible to generate fixtures that can be loaded by one database but not another. so I recommend always generating fixtures from a database that's consistent across environments 🌈

uses MooX::Attribute::ENV so you can 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's okay 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 than 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're building migration files for. you can name any of the databases currently supported by SQL::Translator. if you leave this undefined we'll derive a value based on the value of dsn. for example, if your dsn is DBI:SQLite:test.db, we'll 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 the SQL producer. defaults to setting quote_identifiers to a true value — which, despite being documented as the default, is not the case in practice 😭 (classic)

🌸 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'll automatically create a database 'sandbox' in your target_dir that's suitable for development and rapid prototyping. this is intended for developers and meant to make life more simple — particularly for beginners who might not have all the knowledge needed to set up a database for development purposes 🌱

by default this sandbox is a file based DBD::Sqlite database, which is an easy option since chances are good it's already installed on your development computer (and if not, it's 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 turn require the separate installation of either Test::mysqld or Test::Postgresql58). if you're using one of those open source databases in production, it's 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're starting off, just sticking to the default sqlite is probably the easiest thing to do 💜

you should review the documentation 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 so you can 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 — that's 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're smart enough to do the subclassing (and sure you need to do that), I'll assume you'll also either subclass DBIx::Class::Migration:Script or override the 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're 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're 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 check out DBIx::Class-specific-connection-attributes in DBIx::Class::Storage::DBI for more info on what this can do for you. chances are good that if you need this, you'll also want to subclass DBIx::Class::Migration::Script as well 👑

common uses for this are running SQL on startup and setting 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're 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 🧚

💅 COMMANDS 💅

okay so bestie, the whole point of this class is that it’s built to run straight from your shell. It uses MooX::Options, so it can be run directly as a commandline application. The example at the top of this section is literally:

dbic-migration -Ilib install

Below is every command we support, plus the options/flags that go with each command.

  • 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 🎀

These flags are used to modify or inform commands. Little sidekicks, basically.

  • 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. So yes, it’s got a default and it’s lowkey convenient.

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

🌸 OPTIONAL METHODS FOR SUBCLASSES 🌸

If you decide to make a custom subclass of DBIx::Class::Migration::Script (you might do this, for example, to better integrate your migrations with an existing framework like Catalyst), you can define the following option methods. Very main character of you, honestly.

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.

🦋 ADDITIONAL INFORMATION FOR SUBCLASSERS 🦋

The following methods are documented of interest to subclassers.

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.

🌈 CONSTANTS 🌈

The following constants are defined but not exported. These are used to give a canonical value for the sandbox_class attribute.

  • SANDBOX_SQLITE — SqliteSandbox
  • SANDBOX_MYSQL — MySQLSandbox
  • SANDBOX_POSTGRESQL — PostgresqlSandbox

✨ EXAMPLES ✨

Please see DBIx::Class::Migration::Tutorial for more. Here’s some basic use cases.

🌱 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.)

👀 SEE ALSO 👀

DBIx::Class::Migration

👑 AUTHOR 👑

See DBIx::Class::Migration for author information.

See DBIx::Class::Migration for copyright and license information.

✨ source/version: perl v5.42.0 · date: 2020-06-03 · that’s the whole page, bestie — go be iconic and run your migrations 💅

📦 where this page comes from