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.
RaiseErroris on.
PUBLIC METHODS
- $db = Review::Helper::DB->create($path, %review)
-
Create a new review file with the full schema, its
metarows, and the singlereviewrow in stateopen.%reviewmay holdid(default: a new UUID v7),title,source(the URL of the pull or merge request under review) andcreated(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
$pathis an SQLite file whosemetanames it a review file, whatever its format version; false for a missing file, any other SQLite file, or a file that is not SQLite.openrefuses 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).
createruns 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
openorclosed. - $db->set_published($id)
-
Record feedback item
$idas 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
revisionadded. - $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
revisionandtopic(its entry's) added, or undef. - $marks = $db->flag_seen($iteration)
-
The
flag_seenrows of the iteration's flags, oldest mark first. - $db->set_flag_seen($flag_id, $reviewer, $seen)
-
Mark the flag seen by
$reviewernow when$seenis 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
bodyand/orstatusof a feedback row and bumpupdated. 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
AUTHORS
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.