X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Fpublic-inbox-xcpdb.pod;h=e7c07ed38d4085c9c5b6bbdc7954f50aa8b2a68a;hb=4eee5af6011cc8cdefb66c9729952c7eff5c0b0b;hp=5697dcddb67d31ef96acc9266e52c8539a51ae0a;hpb=666f1b8f5c7c76333df4e1296c1668abf04f210f;p=public-inbox.git diff --git a/Documentation/public-inbox-xcpdb.pod b/Documentation/public-inbox-xcpdb.pod index 5697dcdd..e7c07ed3 100644 --- a/Documentation/public-inbox-xcpdb.pod +++ b/Documentation/public-inbox-xcpdb.pod @@ -4,20 +4,92 @@ 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 + +=item --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 -R N + +=item --reshard=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 + +=item --no-full + +=item --fuller -This is intended for upgrading the database format used by -Xapian. It DOES NOT upgrade the schema used by the -public-inbox PSGI search interface (see -L). +These options are passed directly to L when +used with C<--compact>. + +=item --no-fsync + +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 @@ -40,19 +112,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