NAME
    DBIx::Migration - Seamless database schema up- and downgrades

SYNOPSIS
      use DBIx::Migration ();

      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' );

      # Migrate database to version 1
      $m->migrate( 1 );

      # Migrate database to the latest 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.

    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->dir( $dir )
        Get/set-once directory that contains migrations.

    $self->dsn
        Get data source name.

    $self->dbh
        Get database handle.

    $self->password
        Get database password.

    $self->tracking_table
        Get tracking table.

    $self->username
        Get database username.

METHODS
    $self->apply_managed_schema
        Drivers that support schemas like PostgreSQL should override this
        method to set a managed schema before processing migrations.

    $self->driver, $class->driver( $dsn )
        Extracts and returns the driver name from the data source name.

    $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
        Quotes and returns the tracking table using "quote_identifier" in
        DBI. This method is overrideable in subclasses.

    $self->version
        Get 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>

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.