NAME
DBIx::Deployer - Light-weight database patch utility
VERSION
version v1.0.7
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 .
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 REQUIRED)
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
for more information about bind
parameters.
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
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
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
AUTHOR
Chris Tijerina
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by eMortgage Logic LLC.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.