NAME

Test2::Harness::UI::Sync - Module for dumping, loading, and syncing yathui databases

DESCRIPTION

If you need to migrate data between databases, merge databases, or sync databases, this is the module for you.

This module will sync the essential data, while re-mapping items that may already be present in the destination database, such as usernames, test file names, etc, all of which may have different uuids in the new database.

Care is taken to preserve the uuids of runs, jobs, events, etc.

SYNOPSIS

use Test2::Harness::UI::Sync;

my $source_dbh = ...;
my $dest_dbh   = ...;

my $sync = Test2::Harness::UI::Sync->new();

my $delta = $sync->run_delta($source_dbh, $dest_dbh);

# Do the work
$sync->sync(
    from_dbh => $source_dbh,
    to_dbh   => $dest_dbh,
    run_ids  => $delta->{missing_in_b},

    debug => 1,    # Print a notice for each dumped run_id
);

METHODS

@list = $sync->table_list()

Get a list of tables that can be synced.

$run_ids = $sync->get_runs($dbh)

$run_ids = $sync->get_runs($dbh, all => 1)

$run_ids = $sync->get_runs($jsonl_file)

Get all the run_ids from a database or jsonl file. When reading from a database runs that are pending, running, or broken are omitted unless the all => 1 option is given.

$delta = $sync->run_delta($dbh_a, $dbh_b)

Get lists of run_ids that exist in only one of the two provided databases. Only runs that are not pending, running, or broken are listed, but a run that exists in the other database in any state is never listed. A warning is issued for runs that are finished on one side but not on the other.

{
    missing_in_a => \@run_ids_a,
    missing_in_b => \@run_ids_b,
}

$sync->sync(...)

Copy data from the source database to the destination database.

$sync->sync(
    from_dbh => $from_dbh,    # Source database
    to_dbh   => $to_dbh,      # Destination database
    run_ids  => \@run_ids,    # list of run_ids to sync

    name  => "",              # Optional name for this operation in debugging/errors
    skip  => {},              # Optional hashref of (TABLE => bool) for tables to skip
    cache => {},              # Optional uuid cache map.
    debug => 0,               # Optional, turn on for verbosity

    from_uuid_format => 'binary',    # Defaults to 'binary' may be 'string' for older databases
    to_uuid_format   => 'binary',    # Defaults to 'binary' may be 'string' for older databases
);

$sync->write_sync(...)

Output the data to jsonl format.

$sync->write_sync(
    dbh     => $dbh,        # Source database
    run_ids => $run_ids,    # list of run_ids to sync
    wh      => $wh,         # Where to print the jsonl data
    uuidf   => $uuidf,      # UUID format, defaults to 'binary', 'string' is also valid.
    skip    => $skip,       # Optional hashref of (TABLE => bool) for tables to skip
    debug   => 0,           # Optional, turn on for verbosity
);

$sync->read_sync(...)

Read the jsonl data and insert it into the database.

$sync->read_sync(
    dbh     => $dbh,        # Destination database
    run_ids => $run_ids,    # list of run_ids to sync
    rh      => $rh,         # Where to read the jsonl data
    uuidf   => $uuidf,      # UUID format, defaults to 'binary', 'string' is also valid.
    cache   => $cache,      # Optional uuid cache map.
    debug   => 0,           # Optional, turn on for verbosity
);

$uuid = $sync->get_or_create_id($cache, $dbh, $uuidf, $table, $uuid_field, $value_field, $value)

Create or find a common link in the database (think project, user, etc).

my $uuid = $sync->get_or_create_id(
    $cache, $dbh, 'binary',
    users    => 'user_id',
    username => 'bob',
);

$bool = $sync->run_exists($dbh, $uuidf, $run_id)

Check if the run_id is present in the database in any state.

$sync->insert($dbh, $uuidf, $table, $data)

Insert $data as a row into $table using the $uuidf uuid format.

$sync->stringify_uuids($thing)

Takes a string or nested data structure, will convert uuid's in id fields to the string form.

$sync->binarify_uuids($thing)

Takes a string or nested data structure, will convert uuid's in id fields to the binary form.

SOURCE

The source code repository for Test2-Harness-UI can be found at http://github.com/Test-More/Test2-Harness-UI/.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright 2023 Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/