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($jsonl_file)

Get all the run_ids from a database or jsonl file.

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

Get lists of run_ids that exist in only one of the two provided databases.

    {
        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',
    );

$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/