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 public-inbox-xcpdb [OPTIONS] --all
  10
  11 =head1 DESCRIPTION
  12
  13 public-inbox-xcpdb is similar to L<copydatabase(1)> for
  14 upgrading to the latest database format supported by Xapian
  15 (e.g. "glass" or "honey"), but is designed to tolerate and
  16 accept parallel Xapian database modifications from
  17 L<public-inbox-watch(1)>, L<public-inbox-mda(1)>,
  18 L<public-inbox-learn(1)>, and L<public-inbox-index(1)>.
  19
  20 This command is rarely used, as Xapian DB formats rarely
  21 change.
  22
  23 =head1 OPTIONS
  24
  25 =over
  26
  27 =item --all
  28
  29 Copy all inboxes configured in ~/.public-inbox/config.
  30 This is an alternative to specifying individual inboxes directories
  31 on the command-line.
  32
  33 =item -c, --compact
  34
  35 In addition to performing the copy operation, run L<xapian-compact(1)>
  36 on each Xapian shard after copying but before finalizing it.
  37 Compared to the cost of copying a Xapian database, compacting a
  38 Xapian database takes only around 5% of the time required to copy.
  39
  40 Compared to L<public-inbox-compact(1)>, use of this option is
  41 preferable for gigantic inboxes where the coarse-grained lock
  42 currently required for L<public-inbox-compact(1)> can cause
  43 the compaction to take hours at-a-time.
  44
  45 =item --reshard=N / -R N
  46
  47 Reshard the Xapian database on a L<v2|public-inbox-v2-format(5)>
  48 inbox to C<N> shards .  Since L<xapian-compact(1)> is not suitable
  49 for merging, users can rely on this switch to reshard the
  50 existing Xapian database(s) to any positive value of C<N>.
  51
  52 This is useful in case the Xapian DB was created with too few or
  53 too many shards given the capabilities of the current hardware.
  54
  55 =item --blocksize / --no-full / --fuller
  56
  57 These options are passed directly to L<xapian-compact(1)> when
  58 used with C<--compact>.
  59
  60 =item --no-fsync
  61
  62 Disable L<fsync(2)> and L<fdatasync(2)>.
  63 See L<public-inbox-index(1)/--no-fsync> for caveats.
  64
  65 Available in public-inbox 1.6.0+.
  66
  67 =item --sequential-shard
  68
  69 Copy each shard sequentially, ignoring C<--jobs>.  This also
  70 affects indexing done at the end of a run.
  71
  72 =item --batch-size=BYTES
  73
  74 =item --max-size=BYTES
  75
  76 See L<public-inbox-index(1)> for a description of these options.
  77
  78 These indexing options indexing at the end of a run.
  79 C<public-inbox-xcpdb> may run in parallel with with
  80 L<public-inbox-index(1)>, and C<public-inbox-xcpdb> needs to
  81 reindex changes made to the old Xapian DBs by
  82 L<public-inbox-index(1)> while it was running.
  83
  84 =back
  85
  86 =head1 ENVIRONMENT
  87
  88 =over 8
  89
  90 =item PI_CONFIG
  91
  92 The default config file, normally "~/.public-inbox/config".
  93 See L<public-inbox-config(5)>
  94
  95 =item XAPIAN_FLUSH_THRESHOLD
  96
  97 The number of documents to update before committing changes to
  98 disk.  This environment is handled directly by Xapian, refer to
  99 Xapian API documentation for more details.
 100
 101 Default: 10000
 102
 103 =back
 104
 105 =head1 UPGRADING
 106
 107 This tool is intended for admins upgrading Xapian search databases
 108 used by public-inbox, NOT users upgrading public-inbox itself.
 109
 110 In particular, it DOES NOT upgrade the schema used by the
 111 PSGI search interface (see L<public-inbox-index(1)>).
 112
 113 =head1 LIMITATIONS
 114
 115 Do not use L<public-inbox-purge(1)> or L<public-inbox-edit(1)>
 116 while this is running; old (purged or edited data) may show up.
 117
 118 Normal invocations L<public-inbox-index(1)> can safely run
 119 while this is running, too.  However, reindexing via the
 120 L<public-inbox-index(1)/--reindex> switch will be a waste of
 121 computing resources.
 122
 123 =head1 CONTACT
 124
 125 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 126
 127 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 128 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 129
 130 =head1 COPYRIGHT
 131
 132 Copyright 2019-2021 all contributors L<mailto:meta@public-inbox.org>
 133
 134 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 135
 136 =head1 SEE ALSO
 137
 138 L<copydatabase(1)>, L<xapian-compact(1)>, L<public-inbox-index(1)>