]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-xcpdb.pod
eb675965cc27a189b72a8ca3afa40d1d92083300
[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 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)>