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