NAME
    DBIx::Migration - Seamless database schema up- and downgrades
SYNOPSIS
      use DBIx::Migration ();
      # Create migration object overwriting default tracking table
      my $m = DBIx::Migration->new(
        dsn            => 'dbi:SQLite:~/Projects/myapp/db/myapp.db',
        tracking_table => 'myapp_migration'
      );
      # Get current migration version from database
      my $version = $m->version;
      # Set directory before applying migrations
      $m->dir( '~/Projects/myapp/db/migrations' );
      # Get latest migration version from the migrations directory
      my $latest_version = $m->latest;
      # Migrate database to version 1
      $m->migrate( 1 );
      # Migrate database to the latest migration version
      $m->migrate;
      -- ~/Projects/myapp/db/migrations/schema_1_up.sql
      CREATE TABLE foo (
        id INTEGER PRIMARY KEY,
        bar TEXT
      );
      -- ~/Projects/myapp/db/migrations/schema_1_down.sql
      DROP TABLE foo;
      -- ~/Projects/myapp/db/migrations/schema_2_up.sql
      CREATE TABLE bar (
        id INTEGER PRIMARY KEY,
        baz TEXT
      );
      -- ~/Projects/myapp/db/migrations/schema_2_down.sql
      DROP TABLE bar;
DESCRIPTION
    This class provides the basis for seamless database schema up- and
    downgrades. It isn't abstract that means it can be used by its own.
    Subclasses like for example DBIx::Migration::Pg offer driver specific
    improvements.
  Migrations
    The implementation of this class is based on migrations. A migration is
    a ".sql" script. Although not mandatory the script name begins with a
    prefix like for example "schema_". It follows a version number that is a
    positive integer. After an "_" (underscore) character the script name
    ends with the migration type that is either "up" or "down". Migrations
    are stored in a directory and are applied in order to a database.
    Usually the version number of the first migration is 1. The version
    numbers of the other migrations have to be ascending without gaps.
    "migrations" is a common name for the directory that hosts the
    migrations.
    The migration object stores the current migration version in a tracking
    table. Its default unqualified name is "dbix_migration".
  Processing
    During processing the content of each migration is read with the
    "binmode" of ":raw" into a scalar. The content is split into sections
    using the default SQL delimiter ";" (semicolon). Each section is
    executed independently. All related sections are encapsulated in a
    database transaction. If a migration embeds stored logic containing one
    or more semicolons (a PostgreSQL trigger function for example), the
    "migrate()" method incorrectly splits the migration into sections,
    causing an error. You can set a different delimiter to overcome this
    problem. Add the "dbix_migration_delimiter" annotation as an SQL comment
    to the migration
      -- dbix_migration_delimiter: /
      ...
    The annotation has to be specified in the first line. The delimiter has
    to be a single printable ASCII character, excluding the space character.
    In the previous example it is the "/" (slash) character.
LIFECYCLE METHODS
    $self->BUILD( $args )
        Validate object.
ACCESSORS
    $self->dsn
        Get data source name.
    $self->username
        Get database username.
    $self->password
        Get database password.
    $self->dbh
        Get database handle.
    $self->dir( $dir )
        Get/set-once directory that contains migrations.
    $self->do_before
        Get list of SQL statements that are executed before the migration
        transaction begins. The list is empty by default.
    $self->do_while
        Get list of SQL statements that are executed immediately after the
        migration transaction was enabled. The list is empty by default.
    $self->tracking_table
        Get tracking table.
METHODS
    $self->create_tracking_table
        Create the tracking table if it does not exist yet. This method is
        overrideable in subclasses.
    $self->driver, $class->driver( $dsn )
        Extract and return the driver name from the data source name.
    $self->latest
        Get latest migration version comparing the migrations in the
        migrations directory.
    $self->migrate( $version )
        Migrate database to version. Returns true in case of success;
        otherwise false. If called without the version argument the latest
        migration version will be used.
    $self->quoted_tracking_table
        Quote and return the tracking table using "quote_identifier" in DBI.
        This method is overrideable in subclasses.
    $self->version
        Get current migration version from database. Will be "undef" if no
        migration has taken place yet. The version is stored in the tracking
        table.
LOGGING
    The logging of this class is based on a static Log::Any logger. Its
    category is the class name itself. The easiest way to enable logging is
    to set the "LOG_ANY_DEFAULT_ADAPTER" environment variable:
      LOG_ANY_DEFAULT_ADAPTER=Stderr
SEE ALSO
    *   Liquibase end delimiter
        <https://docs.liquibase.com/change-types/enddelimiter-sql.html>
    *   atlas <https://atlasgo.io>
    *   SQITCH <https://sqitch.org/>
AUTHOR
    Sebastian Riedel, <kraihx@gmail.com>
CONTRIBUTORS
    Dan Sully, <dan+github@sully.org>
    Marcus Ramberg, <marcus@nordaaker.com>
    Steven Jenkin, <sjenkin@venda.com>
    Sven Willenbuecher, <sven.willenbuecher@gmx.de>
COPYRIGHT
    Copyright 2004-2005 Sebastian Riedel. All rights reserved.
    This program is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.