Documentation/public-inbox-xcpdb.pod

   1 =head1 NAME
   2
   3 public-inbox-xcpdb - upgrade Xapian DB formats
   4
   5 =head1 SYNOPSIS
   6
   7         public-inbox-xcpdb [OPTIONS] INBOX_DIR
   8
   9 =head1 DESCRIPTION
  10
  11 public-inbox-xcpdb is similar to L<copydatabase(1)> for
  12 upgrading to the latest database format supported by Xapian
  13 (e.g. "glass" or "honey"), but is designed to tolerate and
  14 recover from Xapian database modifications from
  15 L<public-inbox-watch(1)> or L<public-inbox-mda(1)>.
  16
  17 =head1 OPTIONS
  18
  19 =over
  20
  21 =item --compact
  22
  23 In addition to performing the copy operation, run L<xapian-compact(1)>
  24 on each Xapian partition after copying but before finalizing it.
  25 Compared to the cost of copying a Xapian database, compacting a
  26 Xapian database takes only around 5% of the time required to copy.
  27
  28 Compared to L<public-inbox-compact(1)>, use of this option is
  29 preferable for gigantic inboxes where the coarse-grained lock
  30 currently required for L<public-inbox-compact(1)> can cause
  31 the compaction to take hours at-a-time.
  32
  33 =item --reshard=N / -R N
  34
  35 Repartition the Xapian database on a L<v2|public-inbox-v2-format(5)>
  36 inbox to C<N> partitions.  Since L<xapian-compact(1)> is not suitable
  37 for merging, users can rely on this switch to repartition the
  38 existing Xapian database(s) to any positive value of C<N>.
  39
  40 This is useful in case the Xapian DB was created with too few or
  41 too many partitions given the capabilities of the current
  42 hardware.
  43
  44 =item --blocksize / --no-full / --fuller
  45
  46 These options are passed directly to L<xapian-compact(1)> when
  47 used with C<--compact>.
  48
  49 =back
  50
  51 =head1 ENVIRONMENT
  52
  53 =over 8
  54
  55 =item PI_CONFIG
  56
  57 The default config file, normally "~/.public-inbox/config".
  58 See L<public-inbox-config(5)>
  59
  60 =item XAPIAN_FLUSH_THRESHOLD
  61
  62 The number of documents to update before committing changes to
  63 disk.  This environment is handled directly by Xapian, refer to
  64 Xapian API documentation for more details.
  65
  66 Default: 10000
  67
  68 =back
  69
  70 =head1 UPGRADING
  71
  72 This tool is intended for admins upgrading Xapian search databases
  73 used by public-inbox, NOT users upgrading public-inbox itself.
  74
  75 In particular, it DOES NOT upgrade the schema used by the
  76 PSGI search interface (see L<public-inbox-index(1)>).
  77
  78 =head1 CONTACT
  79
  80 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
  81
  82 The mail archives are hosted at L<https://public-inbox.org/meta/>
  83 and L<http://hjrcffqmbrq6wope.onion/meta/>
  84
  85 =head1 COPYRIGHT
  86
  87 Copyright 2019 all contributors L<mailto:meta@public-inbox.org>
  88
  89 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
  90
  91 =head1 SEE ALSO
  92
  93 L<copydatabase(1)|https://public-inbox.org/.copydatabase.1.html>,
  94 L<xapian-compact(1)|https://public-inbox.org/.xapian-compact.1.html>,
  95 L<public-inbox-index(1)|https://public-inbox.org/public-inbox-index.html>