Skip to content

Commit 1b0be9c

Browse files
patrickbirchpatrickbirch
committed
PXB-3662 [DOCS] - Clarify --tables and --databases conflict in docs
 8.0 modified: docs/create-individual-partition-backup.md modified: docs/create-partial-backup.md modified: docs/xtrabackup-option-reference.md
1 parent 17ce1b9 commit 1b0be9c

3 files changed

Lines changed: 153 additions & 58 deletions

File tree

‎docs/create-individual-partition-backup.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,11 @@ tables.
1111
There are three ways of specifying which part of the whole data will be backed
1212
up: regular expressions (`--tables`), enumerating the
1313
tables in a file (`--tables-file`) or providing a list of
14-
databases (`--databases`).
14+
databases or specific tables (`--databases`).
1515

16-
!!! note "Mutual exclusion"
16+
!!! warning "Do not use `--tables` and `--databases` together"
1717

18-
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.
18+
Do not use both `--tables` and `--databases` in the same command. The resulting backup may not contain the data you intended to back up and risks data loss on restore. Use only one of these options per backup operation. See [Create a partial backup](create-partial-backup.md#filtering-behavior-with-examples) for details and alternatives such as `--tables-file` with `--databases`.
1919

2020
The regular expression provided to this option will be matched against the fully
2121
qualified database name and table name, in the form of

‎docs/create-partial-backup.md‎

Lines changed: 131 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,194 @@
11
# Create a partial backup
22

33
*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
55
partial backups:
66

7-
1. matching the tables names with a regular expression
7+
* matching the tables names with a regular expression
88

9-
2. providing a list of table names in a file
9+
* providing a list of table names in a file
1010

11-
3. providing a list of databases
11+
* providing a list of databases
1212

1313
!!! warning
1414

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.
1616

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.
2118

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
2820
named `test` which contains tables named `t1` and `t2`.
2921

3022
!!! warning
3123

3224
If any of the matched or listed tables is deleted during the backup,
33-
*xtrabackup* will fail.
25+
*xtrabackup* fails.
3426

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:
3628

3729
* Use the `--tables` option to list the table names
3830

3931
* Use the `--tables-file` option to list the tables in a file
4032

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"
4238

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.
4440

45-
!!! note "Mutual exclusion"
41+
The two options use different filtering mechanisms and conflict when used together:
4642

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)).
4847

4948
## The `–-tables` option
5049

5150
The first method involves the xtrabackup `--tables` option. This option accepts either:
5251
* 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
5453

5554
To back up only tables in the `test` database, use the following
5655
command:
5756

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[.].*'
6160
```
6261

6362
To back up only the `test.t1` table, use the following command:
6463

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'
6867
```
6968

7069
## The `-–tables-file` option
7170

7271
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
8178
```
8279

8380
## The `--databases` and `-–databases-file` options
8481

82+
Both options specify which databases or tables to back up and use the same filtering logic. The only difference is where you supply the list:
83+
84+
| | `--databases` | `--databases-file` |
85+
|---|---|---|
86+
| Where | Comma-separated list on the command line | Path to a file, one database or `database.table` per line |
87+
| Format | `mysql,mydb,mydb.t1,mydb.t2` | Same `databasename` or `databasename.tablename` format, one per line |
88+
| Use when | Short list, one-off command | Long list, or a list you reuse in a script |
89+
8590
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.
8691

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`.
92+
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`.
8893

8994
!!! note
9095

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.
96+
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.
9497

95-
```{.bash data-prompt="$"}
96-
$ xtrabackup --backup --databases='mysql,sys,performance_schema,test' --target-dir=/data/backups/
98+
```shell
99+
xtrabackup --backup --databases='mysql,sys,performance_schema,test' --target-dir=/data/backups/
97100
```
98101

102+
## Filtering behavior with examples
103+
104+
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.
105+
106+
### How filtering works
107+
108+
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.
109+
110+
#### Database check (`--databases`)
111+
112+
XtraBackup checks whether the database is included or excluded.
113+
114+
* If you use `--databases`, any database not in the list is skipped immediately.
115+
* If a database is in the `--databases` list, XtraBackup normally includes every table in that database. The only exception: when you also use `--tables-file`, XtraBackup includes only the tables named in that file for any database that appears in both the list and the file—not all tables in that database.
116+
117+
Example with `--tables-file` (full databases in `--databases`, specific tables in the file): To back up all of `mysql`, `performance_schema`, and `sys`, and only `testdb.table1` and `testdb.table2`, put the two table names in a file. List only the full databases in `--databases`; do not list `testdb` there.
118+
119+
```shell
120+
echo -e "testdb.table1\ntestdb.table2" > tables.txt
121+
xtrabackup --backup --databases="mysql,performance_schema,sys" --tables-file=tables.txt --target-dir=/data/backups/
122+
```
123+
124+
The database check includes `mysql`, `performance_schema`, and `sys` from `--databases`. The tables in the file (`testdb.table1`, `testdb.table2`) are included by the table check. Result: every table from the three system databases; from `testdb`, only `table1` and `table2`.
125+
126+
#### Table check (`--tables` / `--tables-file`)
127+
128+
For each database that passed the database check, XtraBackup decides which tables to copy:
129+
130+
* When `--tables-file` is used: XtraBackup copies only the tables named in the file (exact match, one `database.table` per line). Any database that has tables in the file is limited to those tables, even if that database is also in `--databases`.
131+
* When `--tables-file` is not used: If the database was included via `--databases`, all tables in that database are copied and any `--tables` regex is ignored. If the database was not in `--databases` (for example, you used only `--tables`), XtraBackup checks each table name against the `--tables` list or regex.
132+
133+
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`).
134+
135+
* Case 1: `xtrabackup --backup --tables="testdb.table1" --databases="mysql"`
136+
`testdb` is not in `--databases`, so the database is skipped. No tables from `testdb` are included.
137+
138+
* Case 2: `xtrabackup --backup --tables="testdb.table1" --databases="mysql,testdb"`
139+
`testdb` is in `--databases`. XtraBackup includes all tables in `testdb` (table1, table2, and table3), ignoring the `--tables` regex.
140+
141+
### Solution: combine specific tables and whole databases
142+
143+
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.
144+
145+
Method 1: Using `--tables-file` (recommended)
146+
147+
Create a file listing the specific tables, one per line:
148+
149+
```text
150+
testdb.table1
151+
testdb.table2
152+
```
153+
154+
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):
155+
156+
```shell
157+
xtrabackup --backup --tables-file=tables.txt --databases="mysql,performance_schema,sys" --target-dir=/data/backups/
158+
```
159+
160+
In this configuration, `--tables-file` backs up only the listed tables from `testdb`, and `--databases` backs up the system databases in full.
161+
162+
!!! note "Avoid duplication"
163+
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.
164+
165+
Method 2: Using `--databases` for everything
166+
167+
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`:
168+
169+
```shell
170+
xtrabackup --backup --databases="mysql,performance_schema,sys,testdb.table1,testdb.table2" --target-dir=/data/backups/
171+
```
172+
173+
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.
174+
175+
### Earlier example (sales and mysql)
176+
177+
You want only `sales.orders` and `sales.order_items`, and also the full `mysql` database. If you use both `--tables` and `--databases`:
178+
179+
```shell
180+
xtrabackup --backup --databases='mysql,sales' --tables='^sales\.(orders|order_items)$' --target-dir=/data/backups/
181+
```
182+
183+
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.
184+
99185
## The `--databases-file` option
100186

101187
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.
188+
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.
103189

104190
!!! note
105191

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.
192+
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.
109193

110-
The next step is to [prepare](prepare-partial-backup.md) the backup in order to restore it.
194+
Next, [prepare](prepare-partial-backup.md) the backup in order to restore the backup.

0 commit comments

Comments
 (0)