|
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 |
| 34 | + |
| 35 | +* Use the `--databases-file` option to list the databases or specific tables in a file |
| 36 | + |
| 37 | +!!! warning "Do not use `--tables` and `--databases` together" |
42 | 38 |
|
43 | | -* Use the `--databases-file` option to list the databases |
| 39 | + Do not use both `--tables` and `--databases` in the same command. The resulting backup does not reliably contain the data you intended to back up. When you restore, you risk data loss or discover that critical tables were never included. A backup that does not match your intent risks data loss. |
44 | 40 |
|
45 | | -!!! note "Mutual exclusion" |
| 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` is fully backed up even when you wanted only specific tables from that database via `--tables`; or tables you expected to be included are 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 | + A backup runs over a period of time. If a table is created while the backup is running, XtraBackup may copy that table into the backup even though you did not list that table in `--databases` or `--databases-file`, but only if (1) the table’s database is already in the scope of your filter (so the new table falls under a database you included), and (2) the table exists when the backup processes that database. |
94 | 89 |
|
95 | | -```{.bash data-prompt="$"} |
96 | | -$ xtrabackup --backup --databases='mysql,sys,performance_schema,test' --target-dir=/data/backups/ |
| 90 | +```shell |
| 91 | +xtrabackup --backup --databases='mysql,sys,performance_schema,test' --target-dir=/data/backups/ |
97 | 92 | ``` |
98 | 93 |
|
| 94 | +## Filtering behavior with examples |
| 95 | + |
| 96 | +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. |
| 97 | + |
| 98 | +### How filtering works |
| 99 | + |
| 100 | +To understand why using `--tables` and `--databases` in the same command fails, consider the order of checks. When determining whether to back up a table, XtraBackup runs a database check first, then a table check. Use the tabs below for each step. |
| 101 | + |
| 102 | +=== "Database check (`--databases`)" |
| 103 | + |
| 104 | + XtraBackup checks whether the database is included or excluded. |
| 105 | + |
| 106 | + * If you use `--databases`, any database not in the list is skipped immediately. |
| 107 | + * If a database is in the `--databases` list, that database is marked so that all tables in that database are included (unless `--tables-file` is also used). |
| 108 | + |
| 109 | +=== "Table check (`--tables` / `--tables-file`)" |
| 110 | + |
| 111 | + If the database was not skipped in the database check: |
| 112 | + |
| 113 | + * If the database was selected via `--databases` (and not via `--tables-file`), all tables in that database are copied and any `--tables` regex is ignored. |
| 114 | + * If the database was selected via `--tables-file` or was not in `--databases`, XtraBackup then checks the table name against the list or regex. |
| 115 | + |
| 116 | +Example environment: Database `testdb` contains tables `table1`, `table2`, and `table3`. Goal: back up `testdb.table1`, `testdb.table2`, and all system databases (`mysql`, `performance_schema`, `sys`). |
| 117 | + |
| 118 | +* Case 1: `xtrabackup --backup --tables="testdb.table1" --databases="mysql"` |
| 119 | + `testdb` is not in `--databases`, so the database is skipped. No tables from `testdb` are included. |
| 120 | + |
| 121 | +* Case 2: `xtrabackup --backup --tables="testdb.table1" --databases="mysql,testdb"` |
| 122 | + `testdb` is in `--databases`. XtraBackup includes all tables in `testdb` (table1, table2, and table3), ignoring the `--tables` regex. |
| 123 | + |
| 124 | +### Solution: combine specific tables and whole databases |
| 125 | + |
| 126 | +To back up specific tables from one database (for example, `testdb.table1`, `testdb.table2`) and full backups of other databases (for example, `mysql`, `performance_schema`, `sys`), use `--tables-file` with `--databases`, or list the specific tables in `--databases` using the `database.table` format. |
| 127 | + |
| 128 | +Method 1: Using `--tables-file` (recommended) |
| 129 | + |
| 130 | +Create a file listing the specific tables, one per line: |
| 131 | + |
| 132 | +```text |
| 133 | +testdb.table1 |
| 134 | +testdb.table2 |
| 135 | +``` |
| 136 | + |
| 137 | +Run XtraBackup with both `--tables-file` and `--databases`. Do not list the database of those specific tables in `--databases`; `--tables-file` supplies the table list for that database. List only the databases you want in full (for example, system databases): |
| 138 | + |
| 139 | +```shell |
| 140 | +xtrabackup --backup --tables-file=tables.txt --databases="mysql,performance_schema,sys" --target-dir=/data/backups/ |
| 141 | +``` |
| 142 | + |
| 143 | +In this configuration, `--tables-file` backs up only the listed tables from `testdb`, and `--databases` backs up the system databases in full. |
| 144 | + |
| 145 | +!!! note "Avoid duplication" |
| 146 | + If you use `--tables-file` to back up specific tables from a database (for example, `testdb`), do not list that database in `--databases`. Listing that database would override the partial selection and back up the entire database. |
| 147 | + |
| 148 | +Method 2: Using `--databases` for everything |
| 149 | + |
| 150 | +You can list specific tables in `--databases` using the `database.table` format. This backs up the system databases in full and only the listed tables from `testdb`: |
| 151 | + |
| 152 | +```shell |
| 153 | +xtrabackup --backup --databases="mysql,performance_schema,sys,testdb.table1,testdb.table2" --target-dir=/data/backups/ |
| 154 | +``` |
| 155 | + |
| 156 | +For a full backup of a single database, add `.*` after the database name (for example, `mydb.*`). See the [databases](xtrabackup-option-reference.md#databases) option reference. |
| 157 | + |
| 158 | +### Earlier example (sales and mysql) |
| 159 | + |
| 160 | +You want only `sales.orders` and `sales.order_items`, and also the full `mysql` database. If you use both `--tables` and `--databases`: |
| 161 | + |
| 162 | +```shell |
| 163 | +xtrabackup --backup --databases='mysql,sales' --tables='^sales\.(orders|order_items)$' --target-dir=/data/backups/ |
| 164 | +``` |
| 165 | + |
| 166 | +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. Do not use this combination; use `--tables-file` with `--databases` instead. |
| 167 | + |
99 | 168 | ## The `--databases-file` option |
100 | 169 |
|
101 | 170 | 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. |
| 171 | +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 | 172 |
|
104 | 173 | !!! note |
105 | 174 |
|
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. |
| 175 | + A backup runs over a period of time. If a table is created while the backup is running, XtraBackup may copy that table into the backup even though you did not list that table in `--databases-file`, but only if (1) the table’s database is already in the scope of your filter (so the new table falls under a database you included), and (2) the table exists when the backup processes that database. |
109 | 176 |
|
110 | | -The next step is to [prepare](prepare-partial-backup.md) the backup in order to restore it. |
| 177 | +Next, [prepare](prepare-partial-backup.md) the backup in order to restore the backup. |
0 commit comments