SYNOPSIS

        use DBIx::Deployer;
        my $d = DBIx::Deployer->new(
          target_dsn => 'dbi:Sybase:server=foo;database=bar;',
          target_username => 'sa',
          target_password => '1234',
          patch_path => '../patches/',
          deployer_db_file => 'deployer.db',
        );
    
        # Run all patches (skipping over those already deployed)
        $d->deploy_all;
    
        # Run one patch (and its dependencies)
        my $patches = $d->patches;
        $d->deploy( $patches->{'the patch name'} );

DESCRIPTION

    Stop here. Go read about App::Sqitch instead.

    Still here? That's probably because your database isn't supported by
    Sqitch :(. This module is a super-lightweight patch management tool
    that uses SQLite (see DBD::SQLite) to store whether a patch has been
    deployed and verified.

    If you're wondering why I authored this and did not contribute to
    Sqitch, the answer is that I needed a quick and dirty solution to hold
    me over until I can use Sqitch after a database migration.

VERSIONING

    Semantic versioning is adopted by this module. See http://semver.org/.

ATTRIBUTES

 target_db (DBI::db)

    This is the database handle where patches will be deployed. You may
    optionally pass target_dsn, target_username, and target_password as an
    alternative to target_db.

 target_dsn (Str)

    This is the dsn for your database that you will be performing patch
    deployments upon. See DBI for more information on dsn strings.

 target_username (Str)

    The username for your database.

 target_password (Str)

    The password for your database.

 patch_path (Str REQUIRED)

    The directory path where you will store your patch files. PLEASE NOTE:
    DBIx::Deployer will attempt to process *all* files in this directory as
    patches regardless of extension or naming convention.

 deployer_db_file (Str)

    This is the file path where you would like your DBIx::Deployer SQLite
    database to be stored. This is required if using SQLite to manage your
    patch information.

 deployer_db (DBI::db)

    If you want your patch status information to live in a database other
    than SQLite, pass a DBI::db object during instantiation. Your database
    storing the patches must have a table conforming to the following
    structure:

      * Table name: patches (you may specify a different table name by
      using the deployer_patch_table attribute)

      * Column: name VARCHAR (of acceptable length for patch names,
      recommended to be UNIQUE)

      * Column: deployed BOOL/INT

      * Column: verified BOOL/INT

 deployer_patch_table (Str OPTIONAL defaults to 'patches')

    Set this attribute if you want patch data to be recorded in a table
    other than 'patches'. See deployer_db.

 supports_transactions (Bool OPTIONAL defaults to true)

    If your database supports transactions, deploy_sql will be rolled back
    if verification fails, or if other errors occur during deployment of
    individual patches. If your database does not support transactions, you
    will need to set this attribute to false. Please be aware that without
    transactions, patches may find themselves in a state of being deployed
    but not verified... however, if that happens you'll likely have bigger
    fish to fry like figuring out how to repair your database. :)

 keep_newlines (Bool OPTIONAL defaults to false)

    For convenience and SQL readability, newlines are allowed in the SQL
    string values in the JSON patch files contrary to the JSON
    specification. By default, these newlines will be converted to spaces
    before being passed to the parser. If for some reason these
    transformations must not be done, set this attribute to true.

METHODS

 deploy_all

    This will process all patches in the patch_path. Some things to note:

      * deploy is idempotent. It will not run patch files that have already
      been deployed.

      * If your database supports transactions, failed patches will be
      rolled back. Please be aware that an entire patch file (think
      multiple SQL statements) will not be rolled back if a patch (think
      single SQL statement) within the file fails.

 patches

    This returns an array of DBIx::Deployer::Patch objects. This is only
    useful if your intent is to use these objects in conjunction with
    deploy.

 deploy (DBIx::Deployer::Patch REQUIRED)

    This method deploys the patch passed as an argument AND its
    corresponding dependencies.

PATCH FILES

    Patches are written as JSON arrays, and stored in the patch_path
    directory. These files must be able to be parsed by JSON::XS.

        # Patch Example
        [
          {
            "name":"insert into foo",
            "deploy_sql":"INSERT INTO foo VALUES (1, 2)",
            "verify_sql":"SELECT COUNT(*) FROM foo",
            "verify_expects":[ [1] ],
            "dependencies": [ "create table foo" ]
          },
          {
            "name":"create table foo",
            "deploy_sql":"CREATE TABLE foo(a,b)",
            "verify_sql":"PRAGMA table_info(foo)",
            "verify_expects":[ [ 0, "a", "", 0, null, 0 ], [ 1, "b", "", 0, null, 0 ] ]
          }
        ]

 Patch Attributes

  name (Str REQUIRED)

    The name of the patch must be unique. It will be used as the primary
    key for the patch, and is how you will declare it as a dependency for
    other patches.

  dependencies (ArrayRef)

    Dependencies are listed by name. Take care not to create circular
    dependencies as I have no intentions of protecting against them.

  deploy_sql (Str)

    Patch files may contain multiple patches, but a single patch within a
    patch file may not contain more than one SQL statement to deploy.

  deploy_sql_args (ArrayRef)

    If using bind parameters in your deploy_sql statement, the values in
    deploy_sql_args will be used for those parameters. See DBI and
    http://www.bobby-tables.com for more information about bind parameters.

  deploy_script (Str)

    The deploy_script will be passed as an argument to the system command.
    Scripts are expected to handle transactions on their own. A non-zero
    exit status is reported as a failure.

  deploy_script_args (ArrayRef)

    The deploy_script_args are passed to the system command with the
    deploy_script in PROGRAM LIST syntax. It may be useful to manipulate
    this attribute at runtime to pass environment-specific arguments.

  verify_sql (Str)

    This is a single query used to sanity check that your deploy_sql was
    successful. By default, this parameter is required. See no_verify if
    your use case requires deployment without verification.

  verify_sql_args (ArrayRef)

    If using bind parameters in your verify_sql statement, the values in
    verify_sql_args will be used for those parameters. See DBI and
    http://www.bobby-tables.com for more information about bind parameters.

  verify_expects (ArrayRef)

    The verify_sql is selected using selectall_arrayref (see DBI). The
    verify_expects attribute is a representation of the query result you
    would anticipate from the selectall_arrayref method.

  no_verify (Bool)

    If set to true, patches will be marked verified WITHOUT having any
    tests run.

REPOSITORY

    https://github.com/Camspi/DBIx-Deployer

SEE ALSO

      * App::Sqitch - seriously, use this module instead

      * DBD::SQLite

      * DBI

CREDITS

      * eMortgage Logic, LLC., for allowing me to publish this module to
      CPAN