NAME

FlatFile::DataStore::Utils - a collection of utility routines for FlatFile::DataStore datastores.

VERSION

VERSION: 1.03

EXPORTS

Nothing is exported by default. The following may be exported individually; all of them may be exported using the :all tag:

 - migrate
 - migrate_nohist
 - validate
 - compare

Examples:

 use FlatFile::DataStore::Utils qw( migrate migrate_nohist validate compare );
 use FlatFile::DataStore::Utils qw( :all );

SYNOPSIS

    use FlatFile::DataStore::Utils qw( migrate migrate_nohist validate compare );

    my $from_dir  = '/from/dir'; my $from_name = 'ds1';
    my $to_dir    = '/to/dir';   my $to_name   = 'ds2';

    validate( $from_dir, $from_name                    );
    migrate ( $from_dir, $from_name, $to_dir, $to_name );
    validate(                        $to_dir, $to_name );
    compare ( $from_dir, $from_name, $to_dir, $to_name );

    # optionally, migrate_nohist() will not copy any history
    # or deleted records:
    
    validate(        $from_dir, $from_name                    );
    migrate_nohist ( $from_dir, $from_name, $to_dir, $to_name );
    validate(                               $to_dir, $to_name );

    # can't compare anything (yet) after a nohist migrate

DESCRIPTION

This module provides

- validate(), to validate a datastore, checking that it can be traversed and that its past record data has not changed, and creating history and transaction files for comparison purposes.

- migrate(), to migrate a datastore to a new datastore. Use cases:

  - The data has outgrown the datastore as originally configured
  - You want a better configuration than originally conceived

- migrate_nohist(), to migrate a datastore to a new datastore without any update history and without any deleted records. This is normally discouraged (since the spirit of the module is to retain all history of activity), but it has its uses.

- compare(), to compare the files that validate() creates for one datastore to the files that validate() creates for a second datastore (following a migrate(), most likely). If these files (history, transaction, md5) are exactly equal, then the two data stores are equivalent, i.e., they both contain exactly the same records, even though their data files, etc., may be very differently configured.

SUBROUTINES

Descriptions and parameters for the exportable subroutines are detailed below.

validate( $dir, $name )

Parameters:

$dir

The directory of the datastore.

$name

The name of the datastore.

migrate( $from_dir, $from_name, $to_dir, $to_name, $to_uri )

Parameters:

$from_dir

The directory of the datastore we're migrating from.

$from_name

The name of the datastore we're migrating from.

$to_dir

The directory of the datastore we're migrating to.

$to_name

The name of the datastore we're migrating to.

$to_uri

The uri of the datastore we're migrating to. If given, a new data store will be initialized. If this parameter is not given, it is assumed that the new datastore has already been initialized.

migrate_nohist( $from_dir, $from_name, $to_dir, $to_name, $to_uri )

Parameters:

$from_dir

The directory of the datastore we're migrating from.

$from_name

The name of the datastore we're migrating from.

$to_dir

The directory of the datastore we're migrating to.

$to_name

The name of the datastore we're migrating to.

$to_uri

The uri of the datastore we're migrating to. If given, a new data store will be initialized. If this parameter is not given, it is assumed that the new datastore has already been initialized.

This routine will not keep any record history and will not migrate deleted records.

Intended for post-migration comparisons, this routine writes a "$dir/$name.nohist" data file where each line contains two integers. The first integer is the record sequence number from the from_ds, and the second is from the to_ds. Using these, it should be possible to compare the user data and record data md5 signature from both datastores to verify that the data was migrated completely.

compare( $from_dir, $from_name, $to_dir, $to_name )

This routine compares the files written by validate() for each of the datastores to verify that after migration, the second datastore contains exactly the same information as the first.

Parameters:

$from_dir

The directory of the datastore we migrated from.

$from_name

The name of the datastore we migrated from.

$to_dir

The directory of the datastore we migrated to.

$to_name

The name of the datastore we migrated to.

cpanm FlatFile::DataStore

perl -MCPAN -e shell
install FlatFile::DataStore