X-Git-Url: http://www.git.stargrave.org/?p=public-inbox.git;a=blobdiff_plain;f=Documentation%2Fpublic-inbox-xcpdb.pod;h=eb675965cc27a189b72a8ca3afa40d1d92083300;hp=c47500b629a3516df5a790a4a677962b5e9fc20d;hb=0b15dfc58ceaecdcb1c9285c3ad55813006c8338;hpb=6d60c03c298526713eff379fc339ccb030e32630 diff --git a/Documentation/public-inbox-xcpdb.pod b/Documentation/public-inbox-xcpdb.pod index c47500b6..eb675965 100644 --- a/Documentation/public-inbox-xcpdb.pod +++ b/Documentation/public-inbox-xcpdb.pod @@ -1,22 +1,87 @@ =head1 NAME -public-inbox-xcpdb - copy Xapian DBs (for format upgrades) +public-inbox-xcpdb - upgrade Xapian DB formats =head1 SYNOPSIS - public-inbox-xcpdb INBOX_DIR +public-inbox-xcpdb [OPTIONS] INBOX_DIR + +public-inbox-xcpdb [OPTIONS] --all =head1 DESCRIPTION public-inbox-xcpdb is similar to L for upgrading to the latest database format supported by Xapian (e.g. "glass" or "honey"), but is designed to tolerate and -recover from Xapian database modifications from -L or L. +accept parallel Xapian database modifications from +L, L, +L, and L. + +This command is rarely used, as Xapian DB formats rarely +change. + +=head1 OPTIONS + +=over + +=item --all + +Copy all inboxes configured in ~/.public-inbox/config. +This is an alternative to specifying individual inboxes directories +on the command-line. + +=item -c, --compact + +In addition to performing the copy operation, run L +on each Xapian shard after copying but before finalizing it. +Compared to the cost of copying a Xapian database, compacting a +Xapian database takes only around 5% of the time required to copy. + +Compared to L, use of this option is +preferable for gigantic inboxes where the coarse-grained lock +currently required for L can cause +the compaction to take hours at-a-time. + +=item --reshard=N / -R N + +Reshard the Xapian database on a L +inbox to C shards . Since L is not suitable +for merging, users can rely on this switch to reshard the +existing Xapian database(s) to any positive value of C. + +This is useful in case the Xapian DB was created with too few or +too many shards given the capabilities of the current hardware. + +=item --blocksize / --no-full / --fuller + +These options are passed directly to L when +used with C<--compact>. + +=item --no-fsync -This is intended for upgrading the database format used by -Xapian. It DOES NOT upgrade the schema used by the -public-inbox search interface (see L). +Disable L and L. +See L for caveats. + +Available in public-inbox 1.6.0+. + +=item --sequential-shard + +Copy each shard sequentially, ignoring C<--jobs>. This also +affects indexing done at the end of a run. + +=item --batch-size=BYTES + +=item --max-size=BYTES + +See L for a description of these options. + +These indexing options indexing at the end of a run. +C may run in parallel with with +L, and C needs to +reindex changes made to the old Xapian DBs by +L while it was running. + +=back =head1 ENVIRONMENT @@ -39,19 +104,35 @@ Default: 10000 =head1 UPGRADING +This tool is intended for admins upgrading Xapian search databases +used by public-inbox, NOT users upgrading public-inbox itself. + +In particular, it DOES NOT upgrade the schema used by the +PSGI search interface (see L). + +=head1 LIMITATIONS + +Do not use L or L +while this is running; old (purged or edited data) may show up. + +Normal invocations L can safely run +while this is running, too. However, reindexing via the +L switch will be a waste of +computing resources. + =head1 CONTACT Feedback welcome via plain-text mail to L -The mail archives are hosted at L -and L +The mail archives are hosted at L and +L =head1 COPYRIGHT -Copyright 2019 all contributors L +Copyright 2019-2021 all contributors L License: AGPL-3.0+ L =head1 SEE ALSO -L, L +L, L, L