NAME

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

VERSION

VERSION: 0.12

EXPORTS

Nothing is exported by default. The following may be exported individually; all three 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 data store, 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 data store to a new data store. Use cases:

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

- migrate_nohist(), to migrate a data store to a new data store 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 data store to the files that validate() creates for a second data store (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 data store.

$name

The name of the data store.

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

Parameters:

$from_dir

The directory of the data store we're migrating from.

$from_name

The name of the data store we're migrating from.

$to_dir

The directory of the data store we're migrating to.

$to_name

The name of the data store we're migrating to.

$to_uri

The uri of the data store 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 data store has already been initialized.

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

Parameters:

$from_dir

The directory of the data store we're migrating from.

$from_name

The name of the data store we're migrating from.

$to_dir

The directory of the data store we're migrating to.

$to_name

The name of the data store we're migrating to.

$to_uri

The uri of the data store 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 data store 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 data stores 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 data stores to verify that after migration, the second data store contains exactly the same information as the first.

Parameters:

$from_dir

The directory of the data store we migrated from.

$from_name

The name of the data store we migrated from.

$to_dir

The directory of the data store we migrated to.

$to_name

The name of the data store we migrated to.

cpanm FlatFile::DataStore

perl -MCPAN -e shell
install FlatFile::DataStore