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