.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OVSQLITE-UTIL 8"
.TH OVSQLITE-UTIL 8 "2024-05-19" "INN 2.7.2" "InterNetNews Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ovsqlite\-util \- Overview manipulation utility for ovsqlite
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBovsqlite-util\fR [\fB\-AFghioO\fR] [\fB\-a\fR \fIarticle\fR] [\fB\-n\fR \fInewsgroup\fR]
[\fB\-p\fR \fIpath\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBovsqlite-util\fR is an administrative interface to the ovsqlite overview
method for \s-1INN.\s0  It only works on ovsqlite overview databases, not on any
other type of \s-1INN\s0 overview.  (See dedicated \fBovdb_stat\fR\|(8) and \fBtdx\-util\fR\|(8)
programs for ovdb and tradindexed overview methods.)  It allows the
administrator to dump various information about the internal state of the
overview, audit it for errors, and fix these errors.
.PP
To audit the entire overview database for problems, use \fB\-A\fR.  The checks
can take an extended period of time, depending on the number of newsgroups
and articles present in the overview database.  Any problems found will be
reported to standard error.  Use \fB\-F\fR to correct the errors found.
.PP
It is safe to run this utility while the server is running.  In case fixes
should be made to the database (when using the \fB\-F\fR flag), \fBovsqlite-util\fR
will properly pause the server before performing its operations, and then
resume it.
.PP
The number of overview records stored in the database can be obtained with the
\&\f(CW\*(C`inndf \-n\*(C'\fR command.
.PP
As \fBovsqlite-util\fR directly opens the ovsqlite overview database,
it may take a longer time to complete when \s-1INN\s0 is running owing to
the fact that \fBovsqlite-server\fR may hold locks on certain tables,
in which case \fBovsqlite-util\fR just waits for the locks to be released.
(The \fItranstimelimit\fR parameter in \fIovsqlite.conf\fR controls the duration of
a transaction, so you may check you have not set a too high value.)
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
The \f(CW\*(C`DBI\*(C'\fR Perl module with the \f(CW\*(C`DBD::SQLite\*(C'\fR driver must be installed for
this program to work.  They are present in most distributions as a package
named like \f(CW\*(C`libdbd\-sqlite3\-perl\*(C'\fR, \f(CW\*(C`perl\-DBD\-SQLite\*(C'\fR or \f(CW\*(C`p5\-DBD\-SQLite\*(C'\fR.
They can also be directly installed from \s-1CPAN\s0 (\f(CW\*(C`DBI\*(C'\fR and \f(CW\*(C`DBD\-SQLite\*(C'\fR
distributions available at <https://metacpan.org/dist/DBI> and
<https://metacpan.org/dist/DBD\-SQLite>).
.PP
Naturally, an ovsqlite overview database also needs being in use, as detailed
in the \fBovsqlite\fR\|(5) manual page.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-a\fR \fIarticle\fR" 4
.IX Item "-a article"
The article number or numbers to act on.  \fIarticle\fR is a valid \s-1NNTP\s0 range,
meaning that it can be either a single article number or a range of article
numbers (like \f(CW\*(C`1\-5\*(C'\fR).  Either the start or the end (or both) of the range may
be omitted, in which case they will be set to the first or last article number
in the group.  Passing \f(CW\*(C`\-\*(C'\fR for \fIarticle\fR is therefore equivalent to not
using the \fB\-a\fR option at all.
.Sp
Only useful in combination with the \fB\-g\fR, \fB\-o\fR and \fB\-O\fR options to dump
overview information.
.IP "\fB\-A\fR" 4
.IX Item "-A"
Audit the entire overview database for problems.  Currently, only one
consistency check is performed: the verification that the low water mark, the
high water mark and the article count of each newsgroup match the reality of
articles present in overview.  No changes will be made to the database, but
problems will be reported to standard error.
.IP "\fB\-F\fR" 4
.IX Item "-F"
Audit the entire overview database for problems, fixing them as they're
detected where possible.  This runs the same checks as the \fB\-A\fR flag,
and fixes the problems found.  Using this option takes care of pausing and
resuming \s-1INN\s0 so that the overview data are not changed by another process
during the operations.
.Sp
To see what would be changed by \fB\-F\fR, run \fBovsqlite-util\fR with \fB\-A\fR first.
.IP "\fB\-g\fR" 4
.IX Item "-g"
Dump overall overview information for a particular group.  The fields are,
in order, the article number, the length of the overview data, the time
(in seconds since epoch) when the article arrived on the server, the time
(in seconds since epoch) when the article should expire based on its Expires
header field (or 0 if there is no Expires header field), and the storage \s-1API\s0
token of the article.
.Sp
If this option is given, the \fB\-n\fR option must also be given to specify
the newsgroup on which to act.
.IP "\fB\-i\fR" 4
.IX Item "-i"
Dump newsgroup-related overview information from the database.  This contains
similar information to the server \fIactive\fR file, such as high and low water
marks and moderation status, and is the information that \fBnnrpd\fR hands out
to clients.
.Sp
The fields are, in order, the newsgroup name, the high water mark, the
low water mark, the count of articles in the group, the group status, the
time (in seconds since epoch) when that newsgroup was last expired (or 0 if
\&\fBexpireover\fR hasn't run on it yet), and the deletion status of that newsgroup
(0 if not marked for removal during the next expiration, and a positive value
otherwise).
.Sp
A particular newsgroup can be specified with the \fB\-n\fR option.  If \fB\-n\fR is
not given, the entire master index will be dumped.
.IP "\fB\-n\fR \fInewsgroup\fR" 4
.IX Item "-n newsgroup"
Specify the newsgroup on which to act, required for the \fB\-g\fR, \fB\-o\fR, and
\&\fB\-O\fR options, and optional for the \fB\-i\fR option.
.IP "\fB\-o\fR" 4
.IX Item "-o"
Dump the overview information for a newsgroup, in the same format as it would
be returned to clients but with one modification.  Appended to the end of each
entry will be four additional pieces of data: the article number according
to overview information labelled with \f(CW\*(C`Article:\*(C'\fR, the storage \s-1API\s0 token
for that article labelled with \f(CW\*(C`Token:\*(C'\fR, the arrival date for that article
on the server in \s-1RFC\s0\ 5322 date format labelled with \f(CW\*(C`Arrived:\*(C'\fR, and the
expiration date for that article (from the Expires header field) in \s-1RFC\s0\ 5322
date format if there is any, labelled with \f(CW\*(C`Expires:\*(C'\fR.
.Sp
If this option is given, the \fB\-n\fR option must also be given to specify the
newsgroup on which to act.  By default, all of the overview information for
that newsgroup is dumped, but the \fB\-a\fR option may be given to restrict the
dump to the information for a single article or a range of article numbers.
.IP "\fB\-O\fR" 4
.IX Item "-O"
Dump the overview information for a newsgroup in the format used by
\&\fBoverchan\fR as input.  Each line will start with the storage \s-1API\s0 token, the
arrival timestamp in seconds since epoch, the expires timestamp in the same
format (or 0 if there is no Expires header field), and then the overview data.
.Sp
If this option is given, the \fB\-n\fR option must also be given to specify the
newsgroup on which to act.  By default, all of the overview information for
that newsgroup is dumped, but the \fB\-a\fR option may be given to restrict the
dump to the information for a single article or a range of article numbers.
.IP "\fB\-p\fR \fIpath\fR" 4
.IX Item "-p path"
Act on the overview database rooted in \fIpath\fR, overriding the overview
path specified in the \fIpathoverview\fR parameter in \fIinn.conf\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Dump newsgroup-related overview information for the overview database in
\&\fI/news/overview\fR, regardless of the overview path specified in \fIinn.conf\fR:
.PP
.Vb 1
\&    ovsqlite\-util \-i \-p /news/overview
.Ve
.PP
Dump overall overview information for example.test:
.PP
.Vb 1
\&    ovsqlite\-util \-g \-n example.test
.Ve
.PP
Dump the complete overview information for example.test:
.PP
.Vb 1
\&    ovsqlite\-util \-o \-n example.test
.Ve
.PP
Dump the overview information for articles 45 and higher in example.test:
.PP
.Vb 1
\&    ovsqlite\-util \-o \-n example.test \-a 45\-
.Ve
.PP
Audit the entire overview database for any problems:
.PP
.Vb 1
\&    ovsqlite\-util \-A
.Ve
.SH "HISTORY"
.IX Header "HISTORY"
Written by Julien E\*'\s-1LIE\s0 for InterNetNews.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBexpireover\fR\|(8), \fBinndf\fR\|(8), \fBmakehistory\fR\|(8), \fBnnrpd\fR\|(8), \fBovsqlite\fR\|(5).