« back to all changes in this revision
Viewing changes to doc/xtrabackup.1
- browse files at revision 213.3.1
- compare with another revision
- download diff
- download tarball
- view history from revision 213.3.1
- Committer: Aleksandr Kuzminsky
- Date: 2011-01-10 12:01:38 UTC
- mto: (223.1.4 percona-xtrabackup)
- mto: This revision was merged to the branch mainline in revision 225.
- Revision ID: aleksandr.kuzminsky@percona.com-20110110120138-465clzvbzpo4di45
Added XtraBackup manual page
- files added:
- doc
added
removed
doc/xtrabackup.1
1
.TH "XtraBackup" 1 "January 2011" "" "Percona Inc"
2
.SH "NAME"
3
Percona XtraBackup
4
.SH "DESCRIPTION"
5
.P
6
Percona XtraBackup is an open-source hot backup utility for MySQL that doesn't lock your database during the backup. It can back up data from InnoDB, XtraDB, and MyISAM tables on MySQL 5.0 and 5.1 servers, and it has many advanced features. Commercial support is available(http://www.percona.com/support/mysql-support-maintenance/).
7
.P
8
Percona XtraBackup is a combination of the xtrabackup C program, and the innobackupex Perl script. The xtrabackup program copies and manipulates InnoDB and XtraDB data files, and the Perl script enables enhanced functionality, such as interacting with a running MySQL server and backing up MyISAM tables. XtraBackup works with unmodified MySQL servers, as well as Percona Server with XtraDB. It runs on Linux, Windows, and FreeBSD.
9
.P
10
Summary of features:
11
12
.P
13
.B
14
Hot backups.
15
Backups are online, and queries and transactions continue to run without interruption.
16
.P
17
.B
18
Backs up MyISAM.
19
MyISAM tables are read-only while they are being backed up.
20
.P
21
.B
22
Partial backups.
23
You can select which tables and databases to back up.
24
.P
25
.B
26
High performance.
27
XtraBackup is fast and low-impact. It takes special care not to disrupt your database server. It can copy files in parallel (in multiple threads) for even higher performance.
28
.P
29
.B
30
Remote backups.
31
You can make local backups, you can stream the backups to other programs, or you can securely copy your backups to a remote host after completion.
32
.P
33
.B
34
Compressed backups.
35
You can stream a backup into a compressed format. There is a companion program tar4ibd that understands how to work with InnoDB's data format.
36
.P
37
.B
38
Incremental (delta) backups.
39
You can back up only the data pages that have changed since the last backup.
40
.P
41
.B
42
Point-in-time recovery.
43
You can recover a backup, and then use binary logs to roll forward to a point in time.
44
45
.SH " Percona XtraBackup User Manual "
46
47
48
This page explains how to use Percona XtraBackup. XtraBackup is really a set of three tools:
49
50
.HP
51
*
52
.B "xtrabackup"
53
- a compiled C binary, which copies only InnoDB and XtraDB data
54
.HP
55
*
56
.B "innobackupex"
57
- a wrapper script that provides functionality to backup a whole MySQL database instance with MyISAM, InnoDB, and XtraDB tables.
58
.HP
59
*
60
.B "tar4ibd"
61
- tars InnoDB data safely.
62
63
It is possible to use the
64
.B "xtrabackup"
65
binary alone, or to use only the
66
.B "innobackupex"
67
wrapper script and let it execute
68
.B "xtrabackup"
69
for you. It might be helpful to first learn how to use
70
.B "xtrabackup"
71
, and then learn how to use
72
.B "innobackupex"
73
for convenience and added functionality.
74
75
.SS " How XtraBackup Works "
76
77
78
XtraBackup is based on InnoDB's crash-recovery functionality. It copies your InnoDB data files, which results in data that is internally inconsistent; but then it performs crash recovery on the files to make them a consistent, usable database again.
79
80
This works because InnoDB maintains a
81
.I "redo log"
82
, also called the transaction log. This contains a record of every change to InnoDB's data. When InnoDB starts, it inspects the data files and the transaction log, and performs two steps. It applies committed transaction log entries to the data files, and it performs an undo operation on any transactions that modified data but did not commit.
83
84
XtraBackup works by remembering the
85
.I "log sequence number"
86
(LSN) when it starts, and then copying away the data files. It takes some time to do this, so if the files are changing, then they reflect the state of the database at different points in time. At the same time, XtraBackup runs a background process that watches the transaction log files, and copies changes from it. XtraBackup needs to do this continually because the transaction logs are written in a round-robin fashion, and can be reused after a while. XtraBackup needs the transaction log records for every change to the data files since it began execution.
87
88
The above is the
89
.I "backup"
90
process. Next is the
91
.I "prepare"
92
process. During this step, XtraBackup performs crash recovery against the copied data files, using the copied transaction log file. After this is done, the database is ready to restore and use.
93
94
The above process is implemented in the
95
.B "xtrabackup"
96
compiled binary program. The
97
.B "innobackupex"
98
program adds more convenience and functionality by also permitting you to back up MyISAM tables and .frm files. It starts
99
.B "xtrabackup"
100
, waits until it finishes copying files, and then issues
101
.B "FLUSH TABLES WITH READ LOCK"
102
to prevent further changes to MySQL's data and flush all MyISAM tables to disk. It holds this lock, copies the MyISAM files, and then releases the lock.
103
104
The backed-up MyISAM and InnoDB tables will eventually be consistent with each other, because after the prepare (recovery) process, InnoDB's data is rolled forward to the point at which the backup completed, not rolled back to the point at which it started. This point in time matches where the
105
.B "FLUSH TABLES WITH READ LOCK"
106
was taken, so the MyISAM data and the prepared InnoDB data are in sync.
107
108
The
109
.B "xtrabackup"
110
and
111
.B "innobackupex"
112
tools both offer many features not mentioned in the preceding explanation. Each tool's functionality is explained in more detail on its manual page. In brief, though, the tools permit you to do operations such as streaming and incremental backups with various combinations of copying the data files, copying the log files, and applying the logs to the data.
113
114
.SH " The xtrabackup Binary "
115
116
117
The
118
.B "xtrabackup"
119
binary is a compiled C program that is linked with the InnoDB libraries and the standard MySQL client libraries. The InnoDB libraries provide functionality necessary to apply a log to data files, and the MySQL client libraries provide command-line option parsing, configuration file parsing, and so on to give the binary a familiar look and feel.
120
121
The next step is to
122
.B "--prepare"
123
your backup so it is ready to restore.
124
The
125
.B "xtrabackup"
126
tool runs in either
127
.B "--backup"
128
or
129
.B "--prepare"
130
mode, corresponding to the two main functions it performs. There are several variations on these functions to accomplish different tasks, and there are two less commonly used modes,
131
.B "--stats"
132
and
133
.B "--print-param"
134
. There is no need to use any wrapper script with
135
.B "xtrabackup"
136
if you don't want to. It is quite easy to use by itself for most purposes.
137
138
This manual section explains how to use xtrabackup in detail.
139
.SH " Creating a Backup "
140
141
142
To create a backup, run
143
.B "xtrabackup"
144
with the
145
.B "--backup"
146
option. You also need to specify a
147
.B "--target_dir"
148
option, which is where the backup will be stored, and a
149
.B "--datadir"
150
option, which is where the MySQL data is stored. If the InnoDB data or log files aren't stored in the same directory, you might need to specify the location of those, too. If the target directory does not exist,
151
.B "xtrabackup"
152
creates it. If the directory does exist and is empty,
153
.B "xtrabackup"
154
will succeed.
155
.B "xtrabackup"
156
will not overwrite existing files, however; it will fail with operating system error 17, 'file exists.'
157
158
The tool changes its working directory to the data directory and performs two primary tasks to complete the backup:
159
160
- It starts a log-copying thread in the background. This thread watches the InnoDB log files, and when they change, it copies the changed blocks to a file called
161
.B "xtrabackup_logfile"
162
in the backup target directory. This is necessary because the backup might take a long time, and the recovery process needs all of the log file entries from the beginning to the end of the backup.
163
- It copies the InnoDB data files to the target directory. This is not a simple file copy; it opens and reads the files similarly to the way InnoDB does, by reading the data dictionary and copying them a page at a time.
164
165
When the data files are finished copying, xtrabackup stops the log-copying thread, and creates a files in the target directory called
166
.B "xtrabackup_checkpoints"
167
, which contains the type of backup performed, the log sequence number at the beginning, and the log sequence number at the end.
168
169
An example command to perform a backup follows:
170
171
172
.nf
173
174
xtrabackup --backup --datadir=/var/lib/mysql/ --target-dir=/data/backups/mysql/
175
176
.fi
177
178
This takes a backup of
179
.B "/var/lib/mysql"
180
and stores it at
181
.B "/data/backups/mysql/"
182
. The
183
.B "--target-dir"
184
option deserves special explanation. Because the backup is performed from the data directory itself,
185
.B "the target directory is relative to the data directory"
186
unless you specify an absolute path. If you specify a relative path such as
187
.B "--target-dir=backups"
188
, for example, don't look for the backup in the directory from which you executed xtrabackup -- it will be a subdirectory of the
189
.B "--datadir"
190
directory instead!
191
192
During the backup process, you should see a lot of output showing the data files being copied, as well as the log file thread repeatedly scanning the log files and copying from it. The last thing you should see is something like the following, where the value of the <LSN> will be a number that depends on your system:
193
194
195
.nf
196
197
xtrabackup: Transaction log of lsn (<SLN>) to (<LSN>) was copied.
198
199
.fi
200
201
After the backup is finished, the target directory will contain files such as the following, assuming you have a single InnoDB table
202
.B "test.tbl1"
203
and you are using
204
.B "innodb_file_per_table"
205
:
206
207
208
.nf
209
210
/data/backups/mysql/ibdata1
211
/data/backups/mysql/test
212
/data/backups/mysql/test/tbl1.ibd
213
/data/backups/mysql/xtrabackup_checkpoints
214
/data/backups/mysql/xtrabackup_logfile
215
216
.fi
217
218
The backup can take a long time, depending on how large the database is. It is safe to cancel at any time, because it does not modify the database.
219
220
.SH " Preparing the Backup "
221
222
223
After you make a backup with
224
.B "--backup"
225
, the next step is to
226
.I "prepare"
227
it. The data files are not point-in-time consistent until they've been prepared, because they were copied at different times as the program ran, and they might have been changed while this was happening. If you try to start InnoDB with these data files, it will detect corruption and crash itself to prevent you from running on damaged data. The prepare step makes the files perfectly consistent at a single instant in time, so you can run InnoDB on them.
228
229
During the prepare operation, xtrabackup boots up a kind of modified InnoDB that's embedded inside it (the libraries it was linked against). The modifications are necessary to disable InnoDB's standard safety checks, such as complaining that the log file isn't the right size, which aren't appropriate for working with backups. These modifications are only for the xtrabackup binary; you don't need a modified InnoDB to use xtrabackup for your backups.
230
231
The prepare step uses this "embedded InnoDB" to perform crash recovery on the copied datafiles, using the copied log file. The prepare step is very simple to use: you simply run xtrabackup with the
232
.B "--prepare"
233
option and tell it which directory to prepare, for example, to prepare the backup previously taken,
234
235
236
.nf
237
238
xtrabackup --prepare --target-dir=/data/backups/mysql/
239
240
.fi
241
242
When this finishes, you should see an "InnoDB shutdown" with a message such as the following, where again the value of <LSN> will depend on your system:
243
244
245
.nf
246
247
101107 16:40:15 InnoDB: Shutdown completed; log sequence number <LSN>
248
249
.fi
250
251
Your backup is now clean and consistent, and ready to
252
.B "restore"
253
. However, you might want to take an extra step to make restores as quick as possible. This is to prepare the backup a second time. The first time makes the data files perfectly self-consistent, but it doesn't create fresh InnoDB log files. If you restore the backup at this point and start MySQL, it will have to create new log files, which could take a little while, and you might not want to wait for that. If you run
254
.B "--prepare"
255
a second time, xtrabackup will create the log files for you, and output status text such as the following, which is abbreviated for clarity. The value of <SIZE> will depend on your MySQL configuration.
256
257
258
.nf
259
260
$ xtrabackup --prepare --target-dir=/data/backups/mysql/
261
xtrabackup: This target seems to be already prepared.
262
xtrabackup: notice: xtrabackup_logfile was already used to '--prepare'.
263
101107 16:54:10 InnoDB: Log file ./ib_logfile0 did not exist: new to be created
264
InnoDB: Setting log file ./ib_logfile0 size to <SIZE> MB
265
InnoDB: Database physically writes the file full: wait...
266
101107 16:54:10 InnoDB: Log file ./ib_logfile1 did not exist: new to be created
267
InnoDB: Setting log file ./ib_logfile1 size to <SIZE> MB
268
InnoDB: Database physically writes the file full: wait...
269
101107 16:54:15 InnoDB: Shutdown completed; log sequence number 1284108
270
271
.fi
272
.SH " Restoring a Backup "
273
274
275
The xtrabackup binary does not have any functionality for restoring a backup. That is up to the user to do. You might use
276
.B "rsync"
277
or
278
.B "cp"
279
to restore the files. You should check that the restored files have the correct ownership and permissions.
280
281
Note that xtrabackup backs up only the InnoDB data. You must separately restore the MySQL system database, MyISAM data, table definition files (.frm files), and everything else necessary to make your database functional.
282
283
.SH " How-To and Recipes "
284
285
286
This page is a quick-reference list of recipes for the
287
.B "xtrabackup"
288
tool. It doesn't mention the
289
.B "innobackupex"
290
tool; that is documented separately.
291
292
In all of the below examples, we assume the following:
293
294
.HP
295
* You are backing up a server whose data is stored in
296
.B "/var/lib/mysql/"
297
, which is the standard location for most distributions
298
.HP
299
* You are storing the backups in
300
.B "/data/backups/mysql"
301
302
.HP
303
* You have a
304
.B "my.cnf"
305
file in a standard location, such as
306
.B "/etc/my.cnf"
307
, with at least the following contents:
308
.nf
309
[mysqld]
310
datadir=/var/lib/mysql/
311
[xtrabackup]
312
target_dir=/data/backups/mysql/
313
314
.fi
315
316
.SS " Making a Backup "
317
318
319
Making the backup copies the InnoDB data and log files to the destination. Preparing the backup makes the data files consistent and ready to use.
320
321
.HP
322
* Make a backup:
323
.nf
324
xtrabackup --backup
325
.fi
326
.HP
327
* Prepare the backup:
328
.nf
329
xtrabackup --prepare
330
.fi
331
.HP
332
* Prepare again, to create fresh InnoDB log files:
333
.nf
334
xtrabackup --prepare
335
.fi
336
337
338
.B "Success Criterion"
339
340
341
.HP
342
* The exit status of
343
.B "xtrabackup"
344
is 0.
345
.HP
346
* In the second
347
.B "--prepare"
348
step, you should see InnoDB print messages similar to "Log file ./ib_logfile0 did not exist: new to be created", followed by a line indicating the log file was created.
349
350
351
.B "Relevant Configuration"
352
353
354
.HP
355
* You might want to set the
356
.B "--use-memory"
357
option to something similar to the size of your buffer pool, if you are on a dedicated server that has enough free memory.
358
359
.SS " Making an Incremental Backup "
360
361
362
Making an incremental backup requires a full backup as a base.
363
364
.HP
365
* Create a full backup as above, but do not run the
366
.B "--prepare"
367
command yet
368
.HP
369
* Suppose the full backup is on Monday
370
.HP
371
* Create an incremental backup on Tuesday:
372
.nf
373
374
xtrabackup --backup --target-dir=/data/backups/inc/tue/ \
375
--incremental-basedir=/data/backups/mysql/
376
.fi
377
.HP
378
* Create an incremental backup on Wednesday:
379
.nf
380
381
xtrabackup --backup --target-dir=/data/backups/inc/wed/ \
382
--incremental-basedir=/data/backups/inc/tue/
383
.fi
384
.HP
385
* Prepare the base backup from Monday:
386
.nf
387
388
xtrabackup --prepare --apply-log-only --target-dir=/data/backups/mysql/
389
.fi
390
.HP
391
* Roll Monday's data forward to the state on Tuesday:
392
.nf
393
394
xtrabackup --prepare --apply-log-only --target-dir=/data/backups/mysql/ \
395
--incremental-dir=/data/backups/inc/tue/
396
.fi
397
.HP
398
* Roll forward again to the state on Wednesday:
399
.nf
400
401
xtrabackup --prepare --apply-log-only --target-dir=/data/backups/mysql/ \
402
--incremental-dir=/data/backups/inc/wed/
403
.fi
404
.HP
405
* Follow the steps for a normal backup to complete the preparation stage so the backup is ready to restore
406
407
.SS " Restoring the Backup "
408
409
410
Because
411
.B "xtrabackup"
412
doesn't copy MyISAM files, .frm files, and the rest of the database, you might need to back those up separately. To restore the InnoDB data, simply do something like the following after preparing:
413
414
415
.nf
416
417
cd /data/backups/mysql/
418
rsync -rvt --exclude 'xtrabackup_checkpoints' --exclude 'xtrabackup_logfile' \
419
./ /var/lib/mysql
420
chown -R mysql:mysql /var/lib/mysql/
421
422
.fi
423
.SH " Limitations of xtrabackup "
424
425
426
The xtrabackup binary has some limitations you should be aware of to ensure that your backups go smoothly and are recoverable.
427
428
.HP
429
* If the xtrabackup_logfile is larger than 4GB, the
430
.B "--prepare"
431
step will fail on 32-bit versions of xtrabackup. This limitation also applied to some older 64-bit versions of xtrabackup (
432
.B FIXME
433
what versions?).
434
.HP
435
* xtrabackup does not currently create new InnoDB log files (ib_logfile0, etc) during the initial
436
.B "--prepare"
437
step. You must prepare the backup a second time to do this, if you wish.
438
.HP
439
* xtrabackup copies only the InnoDB data and logs. It does not copy table definition files (.frm files), MyISAM data, users, privileges, or any other portions of the overall database that lie outside of the InnoDB data. To back up this data, you need a wrapper script such as
440
.B "innobackupex"
441
.
442
.HP
443
*
444
.B "xtrabackup"
445
doesn't understand the very old
446
.B "--set-variable"
447
448
.B "my.cnf"
449
syntax that MySQL uses. See
450
.B "configuration"
451
.
452
.SH " Configuring xtrabackup "
453
454
455
This page explains how to configure
456
.B "xtrabackup"
457
and how to configure your system to support
458
.B "xtrabackup"
459
correctly.
460
461
.SS " Configuring xtrabackup "
462
463
464
All of the
465
.B "xtrabackup"
466
configuration is through options, which behave exactly like standard MySQL program options: they can be specified either at the command-line, or through a file such as /etc/my.cnf.
467
468
The xtrabackup binary reads the [myslqd] and [xtrabackup] sections from any configuration files, in order. That is so that it can read its options from your existing MySQL installation, such as the
469
.B "datadir"
470
or some of the InnoDB options. If you want to override these, just specify them in the [xtrabackup] section, and because it is read later, it will take precedence.
471
472
You don't need to put any configuration in your my.cnf if you don't want to. You can simply specify the options on the command-line. Normally, the only thing you might find convenient to place in the [xtrabackup] section of your my.cnf file is the
473
.B "target_dir"
474
option, for example,
475
476
477
.nf
478
479
[xtrabackup]
480
target_dir = /data/backups/mysql/
481
482
.fi
483
484
This manual will assume that you
485
.B "do not"
486
have any file-based configuration for
487
.B "xtrabackup"
488
, so it will always show command-line options being used explicitly. Please see the
489
.B "option and variable reference"
490
for details on all of the configuration options.
491
492
The
493
.B "xtrabackup"
494
binary does not accept exactly the same syntax in the
495
.B "my.cnf"
496
file as the
497
.B "mysqld"
498
server binary does. For historical reasons, the
499
.B "mysqld"
500
server binary accepts parameters with a
501
.B "--set-variable=<variable>=<value>"
502
syntax, which
503
.B "xtrabackup"
504
does not understand. If your
505
.B "my.cnf"
506
file has such configuration directives, you should rewrite them in the
507
.B "--variable=value"
508
syntax.
509
510
.SS " System Configuration and NFS Volumes "
511
512
513
The
514
.B "xtrabackup"
515
tool requires no special configuration on most systems. However, the storage where the
516
.B "--target-dir"
517
is located must behave properly when
518
.B "fsync()"
519
is called. In particular, we have noticed that NFS volumes not mounted with the
520
.B "sync"
521
option might not really sync the data. As a result, if you back up to an NFS volume mounted with the
522
.B "async"
523
option, and then try to prepare the backup from a different server that also mounts that volume, the data might appear to be corrupt. You can use the
524
.B "noasync"
525
mount option to avoid this problem.
526
.SH " The xtrabackup Option Reference "
527
528
529
This page documents all of the command-line options for the
530
.B "xtrabackup"
531
binary.
532
533
.SS " --print-defaults "
534
535
536
Print the program argument list and exit. Must be given as the first option on the command-line.
537
538
.SS " --no-defaults "
539
540
541
Don't read default options from any option file. Must be given as the first option on the command-line.
542
543
.SS " --defaults-file "
544
545
546
Only read default options from the given file. Must be given as the first option on the command-line. Must be a real file; cannot be a symbolic link.
547
548
.SS " --defaults-extra-file "
549
550
551
Read this file after the global files are read. Must be given as the first option on the command-line.
552
553
.SS " --apply-log-only "
554
555
556
This option causes only the redo stage to be performed when
557
.B "incremental backups"
558
.
559
560
.SS " --backup "
561
562
563
Make a backup and place it in
564
.B "--target-dir"
565
. See
566
.B "creating a backup"
567
.
568
569
.SS " --create-ib-logfile "
570
571
572
This option is not currently implemented. To create the InnoDB log files, you must
573
.B "prepare the backup"
574
twice at present.
575
576
.SS " --datadir "
577
578
579
The source directory for the backup. This should be the same as the datadir for your MySQL server, so it should be read from
580
.B "my.cnf"
581
if that exists; otherwise you must specify it on the command line.
582
583
.SS " --export "
584
585
586
Create files necessary for exporting tables. See [[export and import]].
587
588
.SS " --incremental-basedir "
589
590
591
When creating an
592
.B "incremental backup"
593
, this is the directory containing the full backup that is the base dataset for the incremental backups.
594
595
.SS " --incremental-dir "
596
597
598
When preparing an
599
.B "incremental backup"
600
, this is the directory where the incremental backup is combined with the full backup to make a new full backup.
601
602
.SS " --incremental-lsn "
603
604
605
When creating an
606
.B "incremental backup"
607
, you can specify the log sequence number (LSN) in high:low format as two 32-bit integers instead of specifying
608
.B "--incremental-basedir"
609
.
610
611
.SS " --innodb-miscellaneous "
612
613
614
There is a large group of InnoDB options that are normally read from the
615
.B "my.cnf"
616
configuration file, so that
617
.B "xtrabackup"
618
boots up its embedded InnoDB in the same configuration as your current server. You normally do not need to specify these explicitly. These options have the same behavior that they have in InnoDB or XtraDB. They are as follows:
619
620
.HP
621
*
622
.B "--innodb-adaptive-hash-index"
623
624
.HP
625
*
626
.B "--innodb-additional-mem-pool-size"
627
628
.HP
629
*
630
.B "--innodb-autoextend-increment"
631
632
.HP
633
*
634
.B "--innodb-buffer-pool-size"
635
636
.HP
637
*
638
.B "--innodb-checksums"
639
640
.HP
641
*
642
.B "--innodb-data-file-path"
643
644
.HP
645
*
646
.B "--innodb-data-home-dir"
647
648
.HP
649
*
650
.B "--innodb-doublewrite-file"
651
652
.HP
653
*
654
.B "--innodb-doublewrite"
655
656
.HP
657
*
658
.B "--innodb-extra-undoslots"
659
660
.HP
661
*
662
.B "--innodb-fast-checksum"
663
664
.HP
665
*
666
.B "--innodb-file-io-threads"
667
668
.HP
669
*
670
.B "--innodb-file-per-table"
671
672
.HP
673
*
674
.B "--innodb-flush-log-at-trx-commit"
675
676
.HP
677
*
678
.B "--innodb-flush-method"
679
680
.HP
681
*
682
.B "--innodb-force-recovery"
683
684
.HP
685
*
686
.B "--innodb-io-capacity"
687
688
.HP
689
*
690
.B "--innodb-lock-wait-timeout"
691
692
.HP
693
*
694
.B "--innodb-log-buffer-size"
695
696
.HP
697
*
698
.B "--innodb-log-files-in-group"
699
700
.HP
701
*
702
.B "--innodb-log-file-size"
703
704
.HP
705
*
706
.B "--innodb-log-group-home-dir"
707
708
.HP
709
*
710
.B "--innodb-max-dirty-pages-pct"
711
712
.HP
713
*
714
.B "--innodb-open-files"
715
716
.HP
717
*
718
.B "--innodb-page-size"
719
720
.HP
721
*
722
.B "--innodb-read-io-threads"
723
724
.HP
725
*
726
.B "--innodb-write-io-threads"
727
728
729
.SS " --log-stream "
730
731
732
Makes
733
.B "xtrabackup"
734
not copy data files, and output the contents of the InnoDB log files to STDOUT until the
735
.B "--suspend-at-end"
736
automatically.
737
738
.SS " --prepare "
739
740
741
Makes
742
.B "xtrabackup"
743
perform recovery on a backup created with
744
.B "--backup"
745
, so that it is ready to use. See
746
.B "preparing a backup"
747
.
748
749
.SS " --print-param "
750
751
752
Makes
753
.B "xtrabackup"
754
print out parameters that can be used for copying the data files back to their original locations to restore them. See
755
.B "scripting with xtrabackup"
756
.
757
758
.SS " --stats "
759
760
761
Causes
762
.B "xtrabackup"
763
to scan the specified data files and print out
764
.B "index statistics"
765
.
766
767
.SS " --suspend-at-end "
768
769
770
Causes
771
.B "xtrabackup"
772
to create a file called
773
.B "xtrabackup_suspended"
774
in the
775
.B "scripting with xtrabackup"
776
.
777
778
.SS " --tables-file "
779
780
781
A file containing one table name per line, in
782
.B "databasename.tablename"
783
format. The backup will be limited to the specified tables. See
784
.B "partial backups"
785
.
786
787
.SS " --tables "
788
789
790
A regular expression against which the full tablename, in
791
.B "databasename.tablename"
792
format, is matched. If the name matches, the table is backed up. See
793
.B "partial backups"
794
.
795
796
.SS " --target-dir "
797
798
799
This option specifies the destination directory for the backup. If the directory does not exist,
800
.B "xtrabackup"
801
creates it. If the directory does exist and is empty,
802
.B "xtrabackup"
803
will succeed.
804
.B "xtrabackup"
805
will not overwrite existing files, however; it will fail with operating system error 17, 'file exists.'
806
807
Note that for
808
.B "--prepare"
809
, relative paths are interpreted as being relative to the current working directory.
810
811
.SS " --throttle "
812
813
814
This option limits
815
.B "throttling a backup"
816
.
817
818
.SS " --tmpdir "
819
820
821
This option is currently not used for anything except printing out the correct
822
.B "tmpdir"
823
parameter when
824
.B "--print-param"
825
is used.
826
827
.SS " --use-memory "
828
829
830
This option affects how much memory is allocated for
831
.B "--stats"
832
. Its purpose is similar to
833
.B "innodb_buffer_pool_size"
834
. It does not do the same thing as the similarly named option in Oracle's InnoDB Hot Backup tool. The default value is 100MB, and if you have enough available memory, 1GB to 2GB is a good recommended value.
835
836
.SS " --parallel "
837
838
839
This option specifies the number of threads to use to copy multiple data files concurrently when creating a backup. The default value is 1 (i.e., no concurrent transfer).
840
841
Currently, the option only works for local backups.
842
843
.SH " Exporting and Importing Tables "
844
845
846
In standard InnoDB, it is not normally possible to copy tables between servers by copying the files, even with
847
.B "innodb_file_per_table"
848
. However, with the xtrabackup binary, you can export individual tables from any InnoDB database, and import them into Percona Server with XtraDB. (The source doesn't have to be XtraDB, but the destination does.) This functionality requires
849
.B "innodb_file_per_table"
850
to be used on both servers, and requires
851
.B "innodb_expand_import"
852
to be enabled on the destination server. It only works on individual
853
.B ".ibd"
854
files, and cannot export a table that is not contained in its own
855
.B ".ibd"
856
file.
857
858
Let's see how to export and import the following table:
859
860
861
.nf
862
863
CREATE TABLE export_test (
864
a int(11) DEFAULT NULL
865
) ENGINE=InnoDB DEFAULT CHARSET=latin1;
866
867
.fi
868
869
.SS " Exporting the Table "
870
871
872
This table should have been created in innodb_file_per_table mode, so after taking a backup as usual with
873
.B "--backup"
874
, the
875
.B ".ibd"
876
file should exist in the target directory:
877
878
879
.nf
880
881
$ find /data/backups/mysql/ -name export_test.*
882
/data/backups/mysql/test/export_test.ibd
883
884
.fi
885
886
when you prepare the backup, add the extra parameter
887
.B "--export"
888
to the command. If you do not have
889
.B "innodb_file_per_table"
890
in your my.cnf, you must add that to the command-line options. Here is an example:
891
892
893
.nf
894
895
xtrabackup --prepare --export --innodb-file-per-table --target-dir=/data/backups/mysql/
896
897
.fi
898
899
Now you should see a
900
.B ".exp"
901
file in the target directory:
902
903
904
.nf
905
906
$ find /data/backups/mysql/ -name export_test.*
907
/data/backups/mysql/test/export_test.exp
908
/data/backups/mysql/test/export_test.ibd
909
910
.fi
911
912
These two files are all you need to import the table into a server running Percona Server with XtraDB.
913
914
.SS " Importing the Table "
915
916
917
On the destination server running Percona Server with XtraDB, with
918
.B "innodb_expand_import"
919
enabled, create a table with the same structure, and then perform the following steps:
920
921
- Execute
922
.B "ALTER TABLE test.export_test DISCARD TABLESPACE;"
923
924
- If you see the following message, then you must enable innodb_file_per_table and create the table again: "ERROR 1030 (HY000): Got error -1 from storage engine"
925
- Copy the exported files to the
926
.B "test/"
927
subdirectory of the destination server's data directory
928
- Execute
929
.B "ALTER TABLE test.export_test IMPORT TABLESPACE;"
930
931
932
The table should now be imported, and you should be able to SELECT from it and see the imported data.
933
934
.SH " Incremental Backups "
935
936
937
The
938
.B "xtrabackup"
939
tool supports incremental backups, which means that it can copy only the data that has changed since the last full backup. You can perform many incremental backups between each full backup, so you can set up a backup process such as a full backup once a week and an incremental backup every day, or full backups every day and incremental backups every hour.
940
941
Incremental backups work because each InnoDB page (usually 16kb in size) contains a
942
.I "log sequence number"
943
, or LSN. The LSN is the system version number for the entire database. Each page's LSN shows how recently it was changed. An incremental backup copies each page whose LSN is newer than the previous incremental or full backup's LSN.
944
945
Incremental backups do not actually compare the data files to the previous backup's data files. In fact, you can use
946
.B "--incremental-lsn"
947
to perform an incremental backup without even having the previous backup, if you know its LSN. Incremental backups simply read the pages and compare their LSN to the last backup's LSN. You still need a full backup to recover the incremental changes, however; without a full backup to act as a base, the incremental backups are useless.
948
949
.SS " Creating an Incremental Backup "
950
951
952
To make an incremental backup, begin with a full backup as usual. The xtrabackup binary writes a file called xtrabackup_checkpoints into the backup's target directory. This file contains a line showing the
953
.B "to_lsn"
954
, which is the database's LSN at the end of the backup. Create the full backup with a command such as the following:
955
956
957
.nf
958
959
xtrabackup --backup --target-dir=/data/backups/base --datadir=/var/lib/mysql/
960
961
.fi
962
963
964
.B "TIP:"
965
If you want a
966
.B "usable"
967
full backup, use innobackupex since xtrabackup itself won't copy table definitions, triggers, or anything else that's not .ibd.
968
969
970
If you look at the xtrabackup_checkpoints file, you should see some contents similar to the following:
971
972
973
.nf
974
975
backup_type = full-backuped
976
from_lsn = 0
977
to_lsn = 1291135
978
979
.fi
980
981
Now that you have a full backup, you can make an incremental backup based on it. Use a command such as the following:
982
983
984
.nf
985
986
xtrabackup --backup --target-dir=/data/backups/inc1 \
987
--incremental-basedir=/data/backups/base --datadir=/var/lib/mysql/
988
989
.fi
990
991
The
992
.B "/data/backups/inc1/"
993
directory should now contain delta files, such as
994
.B "ibdata1.delta"
995
and
996
.B "test/table1.ibd.delta"
997
. These represent the changes since the LSN 1291135. If you examine the
998
.B "xtrabackup_checkpoints"
999
file in this directory, you should see something similar to the following:
1000
1001
1002
.nf
1003
1004
backup_type = incremental
1005
from_lsn = 1291135
1006
to_lsn = 1291340
1007
1008
.fi
1009
1010
The meaning should be self-evident. It's now possible to use this directory as the base for yet another incremental backup:
1011
1012
1013
.nf
1014
1015
xtrabackup --backup --target-dir=/data/backups/inc2 \
1016
--incremental-basedir=/data/backups/inc1 --datadir=/var/lib/mysql/
1017
1018
.fi
1019
1020
.SS " Preparing the Backups "
1021
1022
1023
The
1024
.B "--prepare"
1025
step for incremental backups is not the same as for normal backups. In normal backups, two types of operations are performed to make the database consistent: committed transactions are replayed from the log file against the data files, and uncommitted transactions are rolled back. For technical reasons, you must skip the rollback of uncommitted transactions when preparing a backup that will be used as the base for an incremental backup. You should use the
1026
.B "--apply-log-only"
1027
option to prevent the rollback phase.
1028
1029
1030
.B "WARNING:"
1031
If you do not use the
1032
.B "--apply-log-only"
1033
option to prevent the rollback phase, then your incremental backups will be useless. After transactions have been rolled back, further incremental backups cannot be applied.
1034
1035
1036
Beginning with the full backup you created, you can prepare it, and then apply the incremental differences to it. Recall that you have the following backups:
1037
1038
1039
.nf
1040
1041
/data/backups/base
1042
/data/backups/inc1
1043
/data/backups/inc2
1044
1045
.fi
1046
1047
To prepare the base backup, you need to run
1048
.B "--prepare"
1049
as usual, but prevent the rollback phase:
1050
1051
1052
.nf
1053
1054
xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base
1055
1056
.fi
1057
1058
The output should end with some text such as the following:
1059
1060
101107 20:49:43 InnoDB: Shutdown completed; log sequence number 1291135
1061
1062
The log sequence number should match the to_lsn of the base backup, which you saw previously.
1063
1064
This backup is actually safe to restore as-is now, even though the rollback phase has been skipped. If you restore it and start MySQL, InnoDB will detect that the rollback phase was not performed, and it will do that in the background, as it usually does for a crash recovery upon start. It will notify you that the database was not shut down normally, but the recovery phase should be nearly instantaneous, because the redo log has already been applied to the data files.
1065
1066
To apply the first incremental backup to the full backup, you should use the following command:
1067
1068
1069
.nf
1070
1071
xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \
1072
--incremental-dir=/data/backups/inc1
1073
1074
.fi
1075
1076
This applies the delta files to the files in /data/backups/base, which rolls them forward in time to the time of the incremental backup. It then applies the redo log as usual to the result. The final data is in /data/backups/base,
1077
.B "not"
1078
in the incremental directory. You should see some output such as the following:
1079
1080
1081
.nf
1082
1083
incremental backup from 1291135 is enabled.
1084
xtrabackup: cd to /data/backups/base/
1085
xtrabackup: This target seems to be already prepared.
1086
xtrabackup: xtrabackup_logfile detected: size=2097152, start_lsn=(1291340)
1087
Applying /data/backups/inc1/ibdata1.delta ...
1088
Applying /data/backups/inc1/test/table1.ibd.delta ...
1089
.... snip
1090
101107 20:56:30 InnoDB: Shutdown completed; log sequence number 1291340
1091
1092
.fi
1093
1094
Again, the LSN should match what you saw from your earlier inspection of the first incremental backup. If you restore the files from /data/backups/base, you should see the state of the database as of the first incremental backup.
1095
1096
Preparing the second incremental backup is a similar process: apply the deltas to the (modified) base backup, and you will roll its data forward in time to the point of the second incremental backup:
1097
1098
1099
.nf
1100
1101
xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \
1102
--incremental-dir=/data/backups/inc2
1103
1104
.fi
1105
1106
If you wish to avoid the notice that InnoDB was not shut down normally, when you have applied the desired deltas to the base backup, you can run
1107
.B "--prepare"
1108
again without disabling the rollback phase.
1109
.SH " Partial Backups "
1110
1111
1112
xtrabackup supports taking partial backups when
1113
.B "innodb_file_per_table"
1114
is enabled. There are two ways to create partial backups.
1115
1116
For the purposes of this manual page, we will assume that there is a database named 'test' which contains tables named 't1' and 't2'.
1117
1118
.SS " Using the --tables Option "
1119
1120
1121
The first method is with the
1122
.B "--tables"
1123
option. The option's value is a regular expression that is matched against the fully qualified tablename, including the database name, in the form
1124
.B "databasename.tablename"
1125
.
1126
1127
To back up only tables in the 'test' database, you can use the following command:
1128
1129
xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/data/backups/ \
1130
--tables="^test[.].*"
1131
1132
To back up only the table 'test.t1', you can use the following command:
1133
1134
xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/data/backups/ \
1135
--tables="^test[.]t1"
1136
1137
.SS " Using the --tables-file Option "
1138
1139
1140
The
1141
.B "--tables-file"
1142
option specifies a file that can contain multiple table names, one table name per line in the file. Only the tables named in the file will be backed up. Names are matched exactly, case-sensitive, with no pattern or regular expression matching. The table names must be fully qualified, in
1143
.B "databasename.tablename"
1144
format.
1145
1146
.SS " Preparing the Backup "
1147
1148
1149
When you use the
1150
.B "--prepare"
1151
option on a partial backup, you will see warnings about tables that don't exist. That is because these tables exist in the data dictionary inside InnoDB, but the corresponding
1152
.B ".ibd"
1153
files don't exist. They were not copied into the backup directory. These tables will be removed from the data dictionary, and when you restore the backup and start InnoDB, they will no longer exist and will not cause any errors or warnings to be printed to the log file.
1154
1155
An example of the error message you will see during the prepare phase follows.
1156
1157
1158
.nf
1159
1160
InnoDB: Reading tablespace information from the .ibd files...
1161
101107 22:31:30 InnoDB: Error: table 'test1/t'
1162
InnoDB: in InnoDB data dictionary has tablespace id 6,
1163
InnoDB: but tablespace with that id or name does not exist. It will be removed from data dictionary.
1164
1165
.fi
1166
1167
.SH " Analyzing Table Statistics "
1168
1169
1170
The
1171
.B "xtrabackup"
1172
binary can analyze InnoDB data files in read-only mode to give statistics about them. To do this, you should use the
1173
.B "--stats"
1174
option. You can combine this with the
1175
.B "--tables"
1176
option to limit the files to examine. It also uses the
1177
.B "--use-memory="
1178
option.
1179
1180
You can perform the analysis on a running server, with some chance of errors due to the data being changed during analysis. Or, you can analyze a backup copy of the database. Either way, to use the statistics feature, you need a clean copy of the database including correctly sized log files, so you need to execute with
1181
.B "--prepare"
1182
twice to use this functionality on a backup.
1183
1184
The result of running on a backup might look like the following:
1185
1186
1187
.nf
1188
1189
<INDEX STATISTICS>
1190
table: test/table1, index: PRIMARY, space id: 12, root page 3
1191
estimated statistics in dictionary:
1192
key vals: 25265338, leaf pages 497839, size pages 498304
1193
real statistics:
1194
level 2 pages: pages=1, data=5395 bytes, data/pages=32%
1195
level 1 pages: pages=415, data=6471907 bytes, data/pages=95%
1196
leaf pages: recs=25958413, pages=497839, data=7492026403 bytes, data/pages=91%
1197
1198
.fi
1199
1200
This can be interpreted as follows:
1201
1202
.HP
1203
* The first line simply shows the table and index name and its internal identifiers. If you see an index named
1204
.B "GEN_CLUST_INDEX"
1205
, that is the table's clustered index, automatically created because you did not explicitly create a PRIMARY KEY.
1206
.HP
1207
* The
1208
.I "estimated statistics in dictionary"
1209
information is similar to the data that's gathered through
1210
.B "ANALYZE TABLE"
1211
inside of InnoDB to be stored as estimated cardinality statistics and passed to the query optimizer
1212
.HP
1213
* The
1214
.I "real statistics"
1215
information is the result of scanning the data pages and computing exact information about the index.
1216
.HP
1217
* The
1218
.B "level <X> pages:"
1219
output means that the line shows information about pages at that level in the index tree. The larger <X> is, the farther it is from the leaf pages, which are level 0. The first line is the root page.
1220
.HP
1221
* The
1222
.B "leaf pages"
1223
output shows the leaf pages, of course. This is where the table's data is stored.
1224
.HP
1225
* The
1226
.B "external pages:"
1227
output (not shown) shows large external pages that hold values too long to fit in the row itself, such as long BLOB and TEXT values.
1228
.HP
1229
* The
1230
.I "recs"
1231
is the real number of records (rows) in leaf pages.
1232
.HP
1233
* The
1234
.I "pages"
1235
is the page count.
1236
.HP
1237
* The
1238
.I "data"
1239
is the total size of the data in the pages, in bytes.
1240
.HP
1241
* The
1242
.I "data/pages"
1243
is calculated as (data / (pages * PAGE_SIZE)) * 100%. It will never reach 100% because of space reserved for page headers and footers.
1244
1245
1246
.SH " Throttling Backups "
1247
1248
1249
Although
1250
.B "xtrabackup"
1251
does not block your database's operation, any backup can add load to the system being backed up. On systems that do not have much spare I/O capacity, it might be helpful to throttle the rate at which
1252
.B "xtrabackup"
1253
reads and writes data. You can do this with the
1254
.B "--throttle"
1255
option.
1256
1257
In
1258
.B "--backup"
1259
mode, this option limits the number of pairs of read-and-write operations per second that
1260
.B "xtrabackup"
1261
will perform. If you are creating an
1262
.B "incremental backup"
1263
, then the limit is the number of read IO operations per second.
1264
1265
By default, there is no throttling, and
1266
.B "xtrabackup"
1267
reads and writes data as quickly as it can. If you set too strict of a limit on the I/O operations, the backup might be so slow that it will never catch up with the transaction logs that InnoDB is writing, so the backup might never complete.
1268
1269
.SH " Working with Binary Logs "
1270
1271
1272
The
1273
.B "xtrabackup"
1274
binary integrates with information that InnoDB stores in its transaction log about the corresponding binary log position for committed transactions. This enables it to print out the binary log position to which a backup corresponds, so you can use it to set up new replication slaves or perform point-in-time recovery.
1275
1276
.SS " Finding the Binary Log Position "
1277
1278
1279
You can find the binary log position corresponding to a backup performing the
1280
.B "--prepare"
1281
process. If your backup is from a server with binary logging enabled,
1282
.B "xtrabackup"
1283
will create a file named
1284
.B "xtrabackup_binlog_pos_innodb"
1285
in the target directory. This file contains the binary log file name and position of the exact point in the binary log to which the prepared backup corresponds.
1286
1287
You will also see output similar to the following during the prepare stage:
1288
1289
1290
.nf
1291
1292
InnoDB: Last MySQL binlog file position 0 3252710, file name ./mysql-bin.000001
1293
... snip ...
1294
[notice (again)]
1295
If you use binary log and don't use any hack of group commit,
1296
the binary log position seems to be:
1297
InnoDB: Last MySQL binlog file position 0 3252710, file name ./mysql-bin.000001
1298
1299
.fi
1300
1301
The output should contain the same file name and position as the
1302
.B "xtrabackup_binlog_pos_innodb"
1303
file. The message about hacking group commit refers to an early implementation of emulated group commit in Percona Server.
1304
.B FIXME
1305
is this still uncertain, or do we know that it works correctly now?
1306
1307
.SS " Point-In-Time Recovery "
1308
1309
1310
To perform a point-in-time recovery from an
1311
.B "xtrabackup"
1312
backup, you should prepare and restore the backup, and then replay binary logs from the point shown in the
1313
.B "xtrabackup_binlog_pos_innodb"
1314
file.
1315
1316
.SS " Setting Up a New Replication Slave "
1317
1318
1319
To set up a new replica, you should prepare the backup, and restore it to the data directory of your new replication slave. Then in your
1320
.B "CHANGE MASTER TO"
1321
command, use the binary log filename and position shown in the
1322
.B "xtrabackup_binlog_pos_innodb"
1323
file to start replication.
1324
1325
.SH " Scripting Backups With xtrabackup "
1326
1327
1328
The
1329
.B "xtrabackup"
1330
tool has several features to enable scripts to control it while they perform related tasks. The
1331
.B "innobackupex"
1332
script is one example, but xtrabackup is easy to control with your own command-line scripts too.
1333
1334
.SS " Suspending After Copying "
1335
1336
1337
In
1338
.B "backup"
1339
mode, xtrabackup normally copies the log files in a background thread, copies the data files in a foreground thread, and then stops the log copying thread and finishes. If you use the
1340
.B "--suspend-at-end"
1341
option, instead of stopping the log thread and finishing, xtrabackup continues to copy the log files, and creates a file in the target directory called
1342
.B "xtrabackup_suspended"
1343
. As long as that file exists,
1344
.B "xtrabackup"
1345
will continue to watch the log files and copy them into the
1346
.B "xtrabackup_logfile"
1347
in the target directory. When the file is removed,
1348
.B "xtrabackup"
1349
will finish copying the log file and exit.
1350
1351
This functionality is useful for coordinating the InnoDB data backups with other actions. Perhaps the most obvious is copying the table definitions (the .frm files) so that the backup can be restored. You can start
1352
.B "xtrabackup"
1353
in the background, wait for the
1354
.B "xtrabackup_suspended"
1355
file to be created, and then copy any other files you need to complete the backup. This is exactly what the
1356
.B "innobackupex"
1357
tool does (it also copies MyISAM data and other files).
1358
1359
.SS " Generating Meta-Data "
1360
1361
1362
It is a good idea for the backup to include all the information you need to restore the backup. The
1363
.B "xtrabackup"
1364
tool can print out the contents of a
1365
.B "my.cnf"
1366
file that are needed to restore the data and log files. If you add the
1367
.B "--print-param"
1368
option, it will print out something like the following:
1369
1370
1371
.nf
1372
1373
# This MySQL options file was generated by XtraBackup.
1374
[mysqld]
1375
datadir = /data/mysql/
1376
innodb_data_home_dir = /data/innodb/
1377
innodb_data_file_path = ibdata1:10M:autoextend
1378
innodb_log_group_home_dir = /data/innodb-logs/
1379
1380
.fi
1381
1382
You can redirect this output into a file in the target directory of the backup.
1383
1384
.SS " Agreeing on the Source Directory "
1385
1386
1387
It's possible that the presence of a defaults file or other factors could cause
1388
.B "xtrabackup"
1389
to back up data from a different location than you expected. To prevent this, you can use
1390
.B "--print-param"
1391
to ask it where it will be copying data from. You can use the output to ensure that
1392
.B "xtrabackup"
1393
and your script are working on the same dataset.
1394
1395
.SS " Log Streaming "
1396
1397
1398
You can instruct
1399
.B "xtrabackup"
1400
to omit copying data files, and simply stream the log file to its standard output instead with
1401
.B "--log-stream"
1402
. This automatically adds the
1403
.B "--suspend-at-end"
1404
option. Your script can then perform tasks such as streaming remote backups by piping the log files into an SSH connection and copying the data files to another server with a tool such as
1405
.B "rsync"
1406
or
1407
.B "tar4ibd"
1408
.
1409
1410
.SH " XtraBackup Exit Codes "
1411
1412
1413
The
1414
.B "xtrabackup"
1415
binary exits with the traditional success value of 0 after a backup when no error occurs. If an error occurs during the backup, the exit value is 1.
1416
1417
In certain cases, the exit value can be something other than 0 or 1, due to the command-line option code included from the MySQL libraries. An unknown command-line option, for example, will cause an exit code of 255.
1418
1419
When an error happens in the
1420
.B "main()"
1421
function of
1422
.B "xtrabackup.c"
1423
, when
1424
.B "xtrabackup"
1425
is preparing to perform the backup, the exit code is -1. This is usually because of a missing or wrong command-line option, failure to open a file or directory that the user specified as a command-line option, or similar. This behavior is changed in xtrabackup 1.4 and later, so it always returns 0 or 1. (However, the MySQL libraries might still exit with a code of 255.)
1426
1427
.SH " Implementation Details "
1428
1429
1430
This page contains notes on various internal aspects of the
1431
.B "xtrabackup"
1432
tool's operation.
1433
1434
.SS " File Permissions "
1435
1436
1437
1438
.B "xtrabackup"
1439
opens the source data files in read-write mode, although it does not modify the files. This means that you must run
1440
.B "xtrabackup"
1441
as a user who has permission to write the data files. The reason for opening the files in read-write mode is that
1442
.B "xtrabackup"
1443
uses the embedded InnoDB libraries to open and read the files, and InnoDB opens them in read-write mode because it normally assumes it is going to write to them.
1444
1445
.SS " Tuning the OS Buffers "
1446
1447
1448
Because
1449
.B "xtrabackup"
1450
reads large amounts of data from the filesystem, it uses
1451
.B "posix_fadvise()"
1452
where possible, to instruct the operating system not to try to cache the blocks it reads from disk. Without this hint, the operating system would prefer to cache the blocks, assuming that
1453
.B "xtrabackup"
1454
is likely to need them again, which is not the case. Caching such large files can place pressure on the operating system's virtual memory and cause other processes, such as the database server, to be swapped out. The
1455
.B "xtrabackup"
1456
tool avoids this with the following hint on both the source and destination files:
1457
1458
posix_fadvise(file, 0, 0, POSIX_FADV_DONTNEED)
1459
1460
In addition,
1461
.B "xtrabackup"
1462
asks the operating system to perform more aggressive read-ahead optimizations on the source files:
1463
1464
posix_fadvise(file, 0, 0, POSIX_FADV_SEQUENTIAL)
1465
1466
.SS " Copying Data Files "
1467
1468
1469
When copying the data files to the target directory,
1470
.B "xtrabackup"
1471
reads and writes 1MB of data at a time. This is not configurable. When copying the log file,
1472
.B "xtrabackup"
1473
reads and writes 512 bytes at a time. This is also not possible to configure, and matches InnoDB's behavior.
1474
1475
After reading from the files,
1476
.B "xtrabackup"
1477
iterates over the 1MB buffer a page at a time, and checks for page corruption on each page with InnoDB's
1478
.B "buf_page_is_corrupted()"
1479
function. If the page is corrupt, it re-reads and retries up to 10 times for each page. It skips this check on the doublewrite buffer.
1480
.SH "AUTHOR"
1481
Percona Inc. http://www.percona.com/
1482
.SH "REPORTING BUGS"
1483
Report bugs to https://bugs.launchpad.net/percona-xtrabackup/+filebug
1484
.SH "LICENCE"
1485
GPL version 2
1486
Loggerhead is a web-based interface for Breezy
Version: 2.0.1