]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-xcpdb.pod
89eed079ddc497bc43986efffd70e2739831704e
[public-inbox.git] / 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 shard 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 Reshard the Xapian database on a L<v2|public-inbox-v2-format(5)>
36 inbox to C<N> shards .  Since L<xapian-compact(1)> is not suitable
37 for merging, users can rely on this switch to reshard 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 shards given the capabilities of the current hardware.
42
43 =item --blocksize / --no-full / --fuller
44
45 These options are passed directly to L<xapian-compact(1)> when
46 used with C<--compact>.
47
48 =item --no-fsync
49
50 Disable L<fsync(2)> and L<fdatasync(2)>.
51
52 Available in public-inbox 1.6.0 (PENDING).
53
54 =back
55
56 =head1 ENVIRONMENT
57
58 =over 8
59
60 =item PI_CONFIG
61
62 The default config file, normally "~/.public-inbox/config".
63 See L<public-inbox-config(5)>
64
65 =item XAPIAN_FLUSH_THRESHOLD
66
67 The number of documents to update before committing changes to
68 disk.  This environment is handled directly by Xapian, refer to
69 Xapian API documentation for more details.
70
71 Default: 10000
72
73 =back
74
75 =head1 UPGRADING
76
77 This tool is intended for admins upgrading Xapian search databases
78 used by public-inbox, NOT users upgrading public-inbox itself.
79
80 In particular, it DOES NOT upgrade the schema used by the
81 PSGI search interface (see L<public-inbox-index(1)>).
82
83 =head1 CONTACT
84
85 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
86
87 The mail archives are hosted at L<https://public-inbox.org/meta/>
88 and L<http://hjrcffqmbrq6wope.onion/meta/>
89
90 =head1 COPYRIGHT
91
92 Copyright 2019-2020 all contributors L<mailto:meta@public-inbox.org>
93
94 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
95
96 =head1 SEE ALSO
97
98 L<copydatabase(1)>, L<xapian-compact(1)>, L<public-inbox-index(1)>