NAME

Review::Helper::DB - The SQLite review file.

DESCRIPTION

Creates and opens review files: one SQLite database per review, holding only review data. Content such as diffs and file text comes from the repository (Review::Helper::VCS), never from here.

Text goes in and comes out as Perl character strings; the file stores UTF-8. Foreign keys are enforced.

SYNOPSIS

use Review::Helper::DB;

my $db = Review::Helper::DB->create($path, title => 'Add caching');
my $db = Review::Helper::DB->open($path);

$db->txn(sub {
    $db->dbh->do('UPDATE iteration SET note = ? WHERE number = ?', undef, $note, 2);
});

my $review = $db->review;
my $latest = $db->latest_iteration;

ATTRIBUTES

$path = $db->path()

The review file. Required. It may not contain ;, which the SQLite driver would read as the end of the file name.

$dbh = $db->dbh()

The DBI handle. RaiseError is on.

PUBLIC METHODS

$db = Review::Helper::DB->create($path, %review)

Create a new review file with the full schema, its meta rows, and the single review row in state open. %review may hold id (default: a new UUID v7), title, source (the URL of the pull or merge request under review) and created (default: now). Creates missing parent directories. Croaks when the file already exists; on failure the partial file is removed.

$db = Review::Helper::DB->open($path)

Open an existing review file. Croaks when the file is missing, is not a review file, or has a format version this code does not support. The schema is not checked: a file an earlier build of the same format version wrote may fail later with SQLite errors, and is rebuilt. Files are never upgraded. A file that cannot be written opens for reading.

$bool = Review::Helper::DB->is_review_file($path)

True when $path is an SQLite file whose meta names it a review file, whatever its format version; false for a missing file, any other SQLite file, or a file that is not SQLite. open refuses such a file as "Not a review file"; Review::Helper::Export asks it before opening a file it would merge into.

$sql = Review::Helper::DB->schema()

The schema's DDL, read once from standards/review.sql in the share directory ("share_dir" in Review::Helper::Util). create runs it as is.

@names = Review::Helper::DB->schema_tables()

The names of the tables the schema defines, in schema order (a table before the tables that refer to it). A file may hold other tables too.

@result = $db->txn(sub { ... })

Run the code in a transaction and return its result. Commits when it returns, rolls back and rethrows when it dies. Transactions do not nest.

$review = $db->review()

Hashref of the review row.

$db->set_state($state)

Set the review's state to open or closed.

$db->set_published($id)

Record feedback item $id as posted to the pull or merge request, now. Croaks when there is no such item.

$iterations = $db->iterations()

Arrayref of iteration rows as hashrefs, oldest first.

$iteration = $db->latest_iteration()

Hashref of the newest iteration row, or undef when there is none.

Queries for the web server

Rows come back as hashrefs of their columns; lists are arrayrefs. Range columns stay JSON text.

$iteration = $db->iteration($number)

The iteration row, or undef.

$commits = $db->commits($iteration)

The iteration's commit rows, first commit first.

$commits = $db->commits_by_revision($iteration, $revision)

The iteration's commit rows for $revision, first first: one, or none; in a squashed iteration split into topics, one per topic, all with the head's revision.

$commit = $db->commit_entry($id)

The commit row with that id, or undef.

$files = $db->files($commit_id)

The commit's file change rows, in insertion order.

$file = $db->file_change($id)

The file change row with that id, or undef.

$file = $db->file_by_path($commit_id, $path)

The commit's file change row for $path, or undef.

$sections = $db->sections($file_id)

The file change's section rows, in file order.

$bool = $db->section_touched($section)

True for a section row the commit changed: deleted, or with a line added, removed or changed. Only those are explained in the fill sheet and shown in the page; a split stores the untouched sections too.

$entries = $db->journal_entries($iteration)

The iteration's journal entries, oldest first.

$flags = $db->flags($iteration)

The flag rows of the iteration's commits, each with revision added.

$flag = $db->flag($id)

The flag row with that id, or undef.

$flag = $db->flag_by_note($iteration, $note_id)

The iteration's flag row with that note id, with revision and topic (its entry's) added, or undef.

$marks = $db->flag_seen($iteration)

The flag_seen rows of the iteration's flags, oldest mark first.

$db->set_flag_seen($flag_id, $reviewer, $seen)

Mark the flag seen by $reviewer now when $seen is true, keeping the time of an earlier mark; remove that reviewer's mark when it is false.

$steps = $db->guide_steps($iteration)

The iteration's guide steps, in order.

$id = $db->add_feedback(%fields)

Insert open feedback and return its id. %fields: iteration, target, revision, path, section_name, section_package, topic, flag, flag_sentence, line, side, body, reviewer. The caller validates them.

$row = $db->feedback($id)

The feedback row with that id, or undef.

$bool = $db->update_feedback($id, %fields)

Set body and/or status of a feedback row and bump updated. Returns false when there is no such row. Croaks when neither field is given.

$id = $db->add_request(%fields)

Insert an open request and return its id. %fields: iteration, kind, target, revision, path, section_name, section_package, topic, note, reviewer.

SOURCE

The source code repository for Review-Helper can be found at https://github.com/exodist/Review-Helper.

MAINTAINERS

Chad Granum <exodist7@gmail.com>

AUTHORS

Chad Granum <exodist7@gmail.com>

COPYRIGHT

Copyright 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 https://dev.perl.org/licenses/