|
1 | 1 | # Create a partial backup |
2 | 2 |
|
3 | 3 | *xtrabackup* supports taking partial backups when the |
4 | | -`innodb_file_per_table` option is enabled. There are three ways to create |
| 4 | +`innodb_file_per_table` option is enabled. There are multiple ways to create |
5 | 5 | partial backups: |
6 | 6 |
|
7 | | -1. matching the tables names with a regular expression |
| 7 | +* matching the tables names with a regular expression |
8 | 8 |
|
9 | | -2. providing a list of table names in a file |
| 9 | +* providing a list of table names in a file |
10 | 10 |
|
11 | | -3. providing a list of databases |
| 11 | +* providing a list of databases |
12 | 12 |
|
13 | 13 | !!! warning |
14 | 14 |
|
15 | | - Do not copy back the prepared backup. |
| 15 | + * Restore: Do not copy back the prepared backup. Restore partial backups by importing the tables (see [Restore a partial backup](restore-partial-backup.md) and [Restore single tables](restore-individual-tables.md) for the procedure), not by using the –copy-back option. Copying back the files is possible in some scenarios but can lead to database inconsistencies and is not recommended. |
16 | 16 |
|
17 | | - Restoring partial backups should be done by importing the tables, |
18 | | - not by using the –copy-back option. It is not |
19 | | - recommended to run incremental backups after running a partial |
20 | | - backup. |
| 17 | + * Incremental backups: Do not run incremental backups after a partial backup. |
21 | 18 |
|
22 | | - Although there are some scenarios where restoring can be done by |
23 | | - copying back the files, this may lead to database |
24 | | - inconsistencies in many cases and it is not a recommended way to |
25 | | - do it. |
26 | | - |
27 | | -For the purposes of this manual page, we will assume that there is a database |
| 19 | +For the purposes of this manual page, we assume that there is a database |
28 | 20 | named `test` which contains tables named `t1` and `t2`. |
29 | 21 |
|
30 | 22 | !!! warning |
31 | 23 |
|
32 | 24 | If any of the matched or listed tables is deleted during the backup, |
33 | | - *xtrabackup* will fail. |
| 25 | + *xtrabackup* fails. |
34 | 26 |
|
35 | | -There are multiple ways of specifying which part of the whole data is backed up: |
| 27 | +There are multiple ways to specify which part of the whole data to back up: |
36 | 28 |
|
37 | 29 | * Use the `--tables` option to list the table names |
38 | 30 |
|
39 | 31 | * Use the `--tables-file` option to list the tables in a file |
40 | 32 |
|
41 | | -* Use the `--databases` option to list the databases |
| 33 | +* Use the `--databases` option to list the databases or specific tables |
42 | 34 |
|
43 | 35 | * Use the `--databases-file` option to list the databases |
44 | 36 |
|
45 | | -!!! note "Mutual exclusion" |
| 37 | +!!! warning "Do not use `--tables` and `--databases` together" |
| 38 | + |
| 39 | + Do not use both `--tables` and `--databases` in the same command. The resulting backup may not contain the data you intended to back up. When you restore, you can lose data or assume you have a complete backup when critical tables were never included. In database administration, a backup that does not match your intent is a risk of data loss. |
| 40 | + |
| 41 | + The two options use different filtering mechanisms and conflict when used together: |
46 | 42 |
|
47 | | - The `--tables` and `--databases` options are mutually exclusive. If you use both options in the same command, XtraBackup ignores `--databases` and only uses `--tables`. Use only one of these options per backup operation. |
| 43 | + * `--tables` uses regular expressions and implies a partial backup. |
| 44 | + * `--databases` uses exact matching and implies a full backup of the listed databases. |
| 45 | + |
| 46 | + For example, a database listed in `--databases` might be fully backed up even though you wanted only specific tables from it via `--tables`; or tables you expected to be included might be omitted. To combine specific tables from one database with full backups of other databases, use `--tables-file` with `--databases` instead of `--tables` (see [Filtering behavior with examples](#filtering-behavior-with-examples)). |
48 | 47 |
|
49 | 48 | ## The `–-tables` option |
50 | 49 |
|
51 | 50 | The first method involves the xtrabackup `--tables` option. This option accepts either: |
52 | 51 | * A comma-separated list of fully qualified table names in the format `database.table` (for example, `db1.t1,db1.t2,db2.t3`) |
53 | | -* A POSIX regular expression surrounded by single quotes that is matched against the fully-qualified database name and table name using the `databasename.tablename` format |
| 52 | +* A POSIX regular expression surrounded by single quotes that XtraBackup matches against the fully-qualified database name and table name in `databasename.tablename` format |
54 | 53 |
|
55 | 54 | To back up only tables in the `test` database, use the following |
56 | 55 | command: |
57 | 56 |
|
58 | | -```{.bash data-prompt="$"} |
59 | | -$ xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/data/backups/ \ |
60 | | ---tables="^test[.].*" |
| 57 | +```shell |
| 58 | +xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/data/backups/ \ |
| 59 | +--tables='^test[.].*' |
61 | 60 | ``` |
62 | 61 |
|
63 | 62 | To back up only the `test.t1` table, use the following command: |
64 | 63 |
|
65 | | -```{.bash data-prompt="$"} |
66 | | -$ xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/data/backups/ \ |
67 | | ---tables="^test[.]t1" |
| 64 | +```shell |
| 65 | +xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/data/backups/ \ |
| 66 | +--tables='^test[.]t1' |
68 | 67 | ``` |
69 | 68 |
|
70 | 69 | ## The `-–tables-file` option |
71 | 70 |
|
72 | 71 | The `--tables-file` option specifies a file that can contain multiple table |
73 | | -names, one table name per line in the file. Only the tables named in the file |
74 | | -will be backed up. Names are matched exactly, case-sensitive, with no pattern or |
75 | | -regular expression matching. The table names must be fully-qualified in |
76 | | -`databasename.tablename` format. |
77 | | - |
78 | | -```{.bash data-prompt="$"} |
79 | | -$ echo "mydatabase.mytable" > /tmp/tables.txt |
80 | | -$ xtrabackup --backup --tables-file=/tmp/tables.txt |
| 72 | +names, one table name per line in the file. XtraBackup backs up only the tables named in the file and matches names exactly, case-sensitive, with no pattern or |
| 73 | +regular expression matching. Use the `databasename.tablename` format and fully-qualified table names. |
| 74 | + |
| 75 | +```shell |
| 76 | +echo "mydatabase.mytable" > /tmp/tables.txt |
| 77 | +xtrabackup --backup --tables-file=/tmp/tables.txt |
81 | 78 | ``` |
82 | 79 |
|
83 | 80 | ## The `--databases` and `-–databases-file` options |
84 | 81 |
|
85 | 82 | The `--databases` option accepts a comma-separated list of database names. To include all tables in a database, add `.*` after the database name (for example, `mydb.*`). Regular expressions are not supported. |
86 | 83 |
|
87 | | -In addition to your selected databases, make sure to specify the `mysql`, `sys`, and `performance_schema` databases. These databases are required when restoring the databases using xtrabackup `--copy-back`. |
| 84 | +In addition to your selected databases, make sure to specify the `mysql`, `sys`, and `performance_schema` databases. You need these databases when restoring with xtrabackup `--copy-back`. |
88 | 85 |
|
89 | 86 | !!! note |
90 | 87 |
|
91 | | - Tables processed during the –prepare step may also be added to the backup |
92 | | - even if they are not explicitly listed by the parameter if they were created |
93 | | - after the backup started. |
| 88 | + The –prepare step can also add to the backup tables that were created |
| 89 | + after the backup started, even if you did not list them in the parameter. |
| 90 | + |
| 91 | +```shell |
| 92 | +xtrabackup --backup --databases='mysql,sys,performance_schema,test' --target-dir=/data/backups/ |
| 93 | +``` |
| 94 | + |
| 95 | +## Filtering behavior with examples |
| 96 | + |
| 97 | +Do not use `--tables` and `--databases` in the same command. The backup may not contain the data you intended: XtraBackup applies `--databases` first as a high-level filter, and that filter can override your `--tables` regex. You can end up with a backup that omits tables you needed or includes tables you did not intend to back up, which risks data loss when you restore. |
| 98 | + |
| 99 | +Why mixing is dangerous: |
94 | 100 |
|
95 | | -```{.bash data-prompt="$"} |
96 | | -$ xtrabackup --backup --databases='mysql,sys,performance_schema,test' --target-dir=/data/backups/ |
| 101 | +* Databases skipped: If `--databases` limits the backup to certain databases, XtraBackup excludes any table that matches your `--tables` regex but belongs to a database not listed in `--databases`. The database-level filter takes precedence, so you can get fewer tables than your regex suggests. |
| 102 | + |
| 103 | +* All tables included despite regex: Depending on implementation order, the database filter can include whole databases (for example, `mydb.*`), and XtraBackup does not always apply table-level filtering as you expect, so you can end up backing up all tables in a database instead of only those matching `--tables`. |
| 104 | + |
| 105 | +Example: You want only `sales.orders` and `sales.order_items`, and also the full `mysql` database. If you use both options: |
| 106 | + |
| 107 | +```shell |
| 108 | +xtrabackup --backup --databases='mysql,sales' --tables='^sales\.(orders|order_items)$' --target-dir=/data/backups/ |
| 109 | +``` |
| 110 | + |
| 111 | +the backup may contain only the two `sales` tables, or all tables in `sales` and `mysql`, or something in between. The result is implementation-dependent and cannot be trusted. You may believe you have a valid backup when you do not. Do not use this combination; use `--tables-file` with `--databases` instead. |
| 112 | + |
| 113 | +Solution: combine specific tables with full databases using `--tables-file` and `--databases` |
| 114 | + |
| 115 | +When you need both whole databases (for example, `mysql`, `sys`, `performance_schema`) and a fixed list of tables from other databases, use `--tables-file` together with `--databases`. List the fully qualified table names in a file, and list the database names (or `db.*`) in `--databases`. XtraBackup includes the tables from the file and all tables from the databases you specify. |
| 116 | + |
| 117 | +Example: back up the entire `mysql` database plus only `mydb.t1` and `mydb.t2`: |
| 118 | + |
| 119 | +```shell |
| 120 | +echo -e "mydb.t1\nmydb.t2" > /tmp/tables.txt |
| 121 | +xtrabackup --backup --databases='mysql,mydb' --tables-file=/tmp/tables.txt --target-dir=/data/backups/ |
97 | 122 | ``` |
98 | 123 |
|
| 124 | +With this approach, the backup includes only `mydb.t1` and `mydb.t2` from `mydb`, and every table in `mysql`. For more combinations (for example, multiple system databases), add them to `--databases` and list the desired user tables in the file. |
| 125 | + |
99 | 126 | ## The `--databases-file` option |
100 | 127 |
|
101 | 128 | The –databases-file option specifies a file that can contain multiple |
102 | | -databases and tables in the `databasename[.tablename]` format, one element name per line in the file. Names are matched exactly, case-sensitive, with no pattern or regular expression matching. |
| 129 | +databases and tables in the `databasename[.tablename]` format, one element name per line in the file. XtraBackup matches names exactly, case-sensitive, with no pattern or regular expression matching. |
103 | 130 |
|
104 | 131 | !!! note |
105 | 132 |
|
106 | | - Tables processed during the –prepare step may also be added to the backup |
107 | | - even if they are not explicitly listed by the parameter if they were created |
108 | | - after the backup started. |
| 133 | + The –prepare step can also add to the backup tables that were created |
| 134 | + after the backup started, even if you did not list them in the parameter. |
109 | 135 |
|
110 | | -The next step is to [prepare](prepare-partial-backup.md) the backup in order to restore it. |
| 136 | +Next, [prepare](prepare-partial-backup.md) the backup in order to restore the backup. |
0 commit comments