Skip to content

PXB-3662: Clarify --tables and --databases conflict in docs #452

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
satya-bodapati wants to merge 2 commits into
base: 8.0
Choose a base branch
from
Open

PXB-3662: Clarify --tables and --databases conflict in docs #452

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1fdbb27
PXB-3662: Clarify --tables and --databases conflict in docs
satya-bodapati Feb 3, 2026
59d8bce
Address review comments
satya-bodapati Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 100 additions & 14 deletions docs/create-partial-backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,83 @@ There are multiple ways of specifying which part of the whole data is backed up:

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

* Use the `--databases` option to list the databases
* Use the `--databases` option to list the databases or specific tables

* Use the `--databases-file` option to list the databases
Copy link
Collaborator

@patrickbirch patrickbirch Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add links to the options reference for these options.

* Use the `--databases-file` option to list the databases or specific tables in a file

!!! note "Mutual exclusion"
!!! note "Conflict between --tables and --databases"

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.
The `--tables` and `--databases` options use different filtering mechanisms and can conflict when used together.

* `--tables` uses regular expressions and implies a partial backup.
* `--databases` uses exact matching and implies a full backup of the listed databases.
Copy link
Collaborator

@patrickbirch patrickbirch Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what about --table-files? Does this option use exact matching?


If you use both, you may get unexpected results (for example, a database listed in `--databases` might be fully backed up even if you only wanted specific tables from it via `--tables`). To combine specific tables from one database with full backups of other databases, use `--tables-file` instead of `--tables`.
Copy link
Collaborator

@patrickbirch patrickbirch Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, you should add --tables-file in the comparisons.
There should also be a performance hit for using regex (--tables) instead of exact matching (--databases).


## Filtering Behavior with Examples

To understand how filtering works, consider the following environment:

* Database `testdb`: Contains tables `table1`, `table2`, and `table3`.
* System Databases: `mysql`, `performance_schema`, `sys`.

**Goal**: Back up `testdb.table1`, `testdb.table2`, and all system databases (`mysql`, `performance_schema`, `sys`).

### Why mixing --tables and --databases fails

When determining whether to back up a table, xtrabackup follows this logic:

1. **Database Check**: xtrabackup first checks if the database is included or excluded.
* If you use `--databases`, any database *not* in the list is skipped immediately.
* If a database is in the `--databases` list, it is marked to have **all its tables included** (unless `--tables-file` is also used).

2. **Table Check**: If the database is not skipped:
* If the database was selected via `--databases`, **all** tables in it are copied, ignoring any `--tables` regex.
* If the database was not explicitly selected via `--databases` (or selected via `--tables-file`), it then checks the table name against the list.

This behavior explains why mixing `--tables` (regex) and `--databases` (list) often fails in the scenario above:

* **Case 1**: `xtrabackup --backup --tables="testdb.table1" --databases="mysql"`
* `testdb` is NOT in `--databases`, so the database is skipped entirely. The result is that no tables from the `testdb` database are included.
* **Case 2**: `xtrabackup --backup --tables="testdb.table1" --databases="mysql,testdb"`
* `testdb` IS in `--databases`. XtraBackup includes **all** tables in `testdb` (`table1`, `table2`, AND `table3`), ignoring the `--tables` regex.

### Solution: Combining specific tables and whole databases

If you want to back up specific tables from one database (e.g., `testdb.table1`, `testdb.table2`) while also backing up other databases (e.g., `mysql`, `performance_schema`, `sys`), use `--tables-file` or simply list the tables in `--databases` (or `--databases-file`).

#### Method 1: Using `--tables-file` (Recommended)
Copy link
Collaborator

@patrickbirch patrickbirch Feb 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should include --tables-file in the earlier comparisons. So far, you've only mentioned --tables and --databases. It could be confusing to a user to suddenly have a third option without explanation.


1. Create a file listing the specific tables you want to back up. When using this method, you do **not** need to list the database of the specific tables in the `--databases` list; `--tables-file` automatically registers it.

```text
testdb.table1
testdb.table2
```

2. Run xtrabackup using both `--tables-file` and `--databases`.

```bash
xtrabackup --backup --tables-file=tables.txt --databases="mysql,performance_schema,sys" --target-dir=/data/backups/
```

In this configuration, `--tables-file` ensures the specific tables from `testdb` are backed up, while `--databases` ensures the system databases are backed up in full.

!!! note "Avoid Duplication"
If you use `--tables-file` to back up specific tables from a database (e.g., `testdb`), do **not** also list that database (`testdb`) in the `--databases` option. Doing so will override the partial selection and back up the **entire** database.

#### Method 2: Using `--databases` for everything

You can also list the specific tables directly in the `--databases` option. This works because `--databases` supports `database.table` format.

This correctly instructs XtraBackup to take full backups of `mysql`, `performance_schema`, and `sys`, but only partial backups of `testdb`.

```bash
xtrabackup --backup --databases="mysql,performance_schema,sys,testdb.table1,testdb.table2" --target-dir=/data/backups/
```

!!! warning "Do Not Use Wildcards"
Do not add `.*` to database names (e.g., `testdb.*`). This is not supported and will result in missing tables. Use the database name alone (`testdb`) for full backups.

## The `–-tables` option

Expand All @@ -55,15 +125,15 @@ The first method involves the xtrabackup `--tables` option. This option accepts
To back up only tables in the `test` database, use the following
command:

```{.bash data-prompt="$"}
$ xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/data/backups/ \
```bash
xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/data/backups/ \
--tables="^test[.].*"
```

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

```{.bash data-prompt="$"}
$ xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/data/backups/ \
```bash
xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/data/backups/ \
--tables="^test[.]t1"
```

Expand All @@ -75,14 +145,26 @@ 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
`databasename.tablename` format.

```{.bash data-prompt="$"}
$ echo "mydatabase.mytable" > /tmp/tables.txt
$ xtrabackup --backup --tables-file=/tmp/tables.txt
```bash
echo "mydatabase.mytable" > /tmp/tables.txt
xtrabackup --backup --tables-file=/tmp/tables.txt
```

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

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.
The `--databases` option accepts a comma-separated list of database names or table names.

* To back up an entire database, specify just the database name (e.g., `databasename`).
* To back up specific tables, specify them in `database.table` format (e.g., `databasename.mytable`).

!!! note "No Wildcards or Regex"

The `--databases` option does **not** support wildcards (like `*`) or regular expressions.
Copy link
Collaborator

@patrickbirch patrickbirch Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add a blank line between !!! warning (should be a note) and the body of the note.


* Do **not** use `<database>.*`. This will look for a literal table named `*`, which will fail to back up your tables.
* To include all tables, simply use the database name: `databasename`.

This option is robust because it correctly registers the specific tables for partial backups, avoiding the conflicts that happen when mixing `--databases` (for full DBs) and `--tables` (for partials).

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

Expand All @@ -92,15 +174,19 @@ In addition to your selected databases, make sure to specify the `mysql`, `sys`,
even if they are not explicitly listed by the parameter if they were created
after the backup started.

```{.bash data-prompt="$"}
$ xtrabackup --backup --databases='mysql,sys,performance_schema,test' --target-dir=/data/backups/
```bash
xtrabackup --backup --databases='mysql,sys,performance_schema,test' --target-dir=/data/backups/
```

## The `--databases-file` option

The –databases-file option specifies a file that can contain multiple
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.

* To back up an entire database, specify just the database name (e.g., `databasename`).
* To back up a specific table, specify `databasename.mytable`.
* **Do not use** `.*` or regex (e.g., `databasename.*`). These are treated as literal names.

Copy link
Collaborator

@patrickbirch patrickbirch Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You might consider adding a summary table at the end to make it easier for users.

!!! note

Tables processed during the –prepare step may also be added to the backup
Expand Down
68 changes: 36 additions & 32 deletions docs/xtrabackup-option-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,14 @@ You invoke xtrabackup in one of the following modes:

When you intend to run xtrabackup in any of these modes, use the following syntax:

```{.bash data-prompt="$"} data-prompt="$"}
$ xtrabackup [--defaults-file=#] --backup|--prepare|--copy-back|--stats [OPTIONS]
```bash
xtrabackup [--defaults-file=#] --backup|--prepare|--copy-back|--stats [OPTIONS]
```

For example, the `--prepare` mode is applied as follows:

```{.bash data-prompt="$"} data-prompt="$"}
$ xtrabackup --prepare --target-dir=/data/backup/mysql/
```bash
xtrabackup --prepare --target-dir=/data/backup/mysql/
```

For all modes, the default options are read from the xtrabackup and
Expand Down Expand Up @@ -111,10 +111,10 @@ the operation is not aborted, and prints a warning.

??? example "Example output"

```{.text .no-copy}
xtrabackup: Error: missing required privilege LOCK TABLES on *.*
xtrabackup: Warning: missing required privilege REPLICATION CLIENT on *.*
```
```text
xtrabackup: Error: missing required privilege LOCK TABLES on *.*
xtrabackup: Warning: missing required privilege REPLICATION CLIENT on *.*
```

### close-files

Expand Down Expand Up @@ -190,25 +190,29 @@ This option specifies which databases to back up.

!!! note "Mutual exclusion"

`--tables` and `--databases` 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.
`--tables` and `--databases` are mutually exclusive. If you use both options in the same command, XtraBackup may produce unexpected results. `--databases` acts as a high-level filter: databases not listed are skipped entirely. However, databases that *are* listed are treated as having all their tables included, causing the `--tables` regex to be ignored for those databases. Use only one of these options per backup operation, or use `--tables-file` instead of `--tables` to mix partial and whole database backups.

Accepted syntax:

This option accepts a comma-separated list of database names. To include all tables in a database, add `.*` after the database name (for example, `mydb.*`).
This option accepts a comma-separated list of database names or table names. To include all tables in a database, simply specify the database name (for example, `mydb`).

!!! warning "No Wildcards or Regex"
Copy link
Collaborator

@patrickbirch patrickbirch Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add a blank line


Regular expressions are not supported.
The `--databases` option does **not** support wildcards (like `*`) or regular expressions. Do not use `mydb.*` as it will search for a literal table named `*`.
Copy link
Collaborator

@patrickbirch patrickbirch Feb 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does --databases support? You should provide the positive (what it does) before the negative (what it doesn't).

Copy link
Collaborator Author

@satya-bodapati satya-bodapati Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just dbnames "mysql,sys,test" or dbname.tablename but you cannot use regex here
like "mysql,sys,test,test2.sbtest*"


Examples:

* `--databases=mysql,performance_schema,sys` - Backs up the entire mysql, performance_schema, and sys databases

* `--databases=mydb.*` - Backs up every table in the mydb database
* `--databases=mydb` - Backs up every table in the mydb database

* `--databases=mydb.table1` - Backs up only table1 in the mydb database

### databases-exclude

Usage: `--databases-exclude=name`

Databases are excluded based on name. This option operates the same way as `--databases`, but excludes the matched names from the backup.
Databases are excluded based on name. This option operates the same way as `--databases`, but excludes the matched names from the backup.

This option has a higher priority than
`--databases`.
Expand Down Expand Up @@ -321,8 +325,8 @@ beginning of a backup provided the status variable
`innodb_buffer_pool_dump_status` reports that the dump has been
completed.

```{.bash data-prompt="$"} data-prompt="$"}
$ xtrabackup --backup --dump-innodb-buffer-pool --target-dir=/home/user/backup
```bash
xtrabackup --backup --dump-innodb-buffer-pool --target-dir=/home/user/backup
```

By default, this option is set to OFF.
Expand Down Expand Up @@ -414,12 +418,12 @@ Implemented in Percona XtraBackup 8.0.32-26, the option lets you enable or disab

An example of how to enable the Smart memory estimation feature:

```{.bash data-prompt="$"} data-prompt="$"}
$ xtrabackup --backup --estimate-memory=ON --target-dir=/data/backups/
```bash
xtrabackup --backup --estimate-memory=ON --target-dir=/data/backups/
```

```{.bash data-prompt="$"} data-prompt="$"}
$ xtrabackup --prepare --use-free-memory-pct=50 --target-dir=/data/backups/
```bash
xtrabackup --prepare --use-free-memory-pct=50 --target-dir=/data/backups/
```

### export
Expand Down Expand Up @@ -1102,7 +1106,7 @@ This option filters tables to be backed up based on their fully qualified names.

!!! note "Mutual exclusion"

`--tables` and `--databases` are mutually exclusive. Supplying both in the same command line causes XtraBackup to ignore one of them (currently `--databases`). Use only one of the options per backup operation.
`--tables` and `--databases` are mutually exclusive. Supplying both in the same command line causes XtraBackup to behave unexpectedly. `--databases` acts as a high-level filter: databases not listed are skipped entirely. However, databases that *are* listed are treated as having all their tables included, causing the `--tables` regex to be ignored for those databases. Use only one of the options per backup operation.

Accepted syntax:

Expand Down Expand Up @@ -1143,24 +1147,24 @@ When you need to back up specific tables from user databases along with entire s

Example 1: Back up specific tables plus entire mysql database

```{.bash data-prompt="$"}
$ xtrabackup --backup --tables='^(mydb\.(t1|t2)|mysql\.)' --target-dir=/data/backup/
```bash
xtrabackup --backup --tables='^(mydb\.(t1|t2)|mysql\.)' --target-dir=/data/backup/
```

This command backs up tables `t1` and `t2` from `mydb`, plus all tables in the `mysql` database.

Example 2: Back up tables from multiple databases plus system databases

```{.bash data-prompt="$"}
$ xtrabackup --backup --tables='^(db1\.t1|db2\.t.*|mysql\.|performance_schema\.|sys\.)' --target-dir=/data/backup/
```bash
xtrabackup --backup --tables='^(db1\.t1|db2\.t.*|mysql\.|performance_schema\.|sys\.)' --target-dir=/data/backup/
```

This command backs up `t1` from `db1`, all tables starting with `t` from `db2`, plus the entire `mysql`, `performance_schema`, and `sys` databases.

Example 3: Back up all tables from a database plus specific tables from another

```{.bash data-prompt="$"}
$ xtrabackup --backup --tables='^(mydb\.|otherdb\.(important_table|critical_table))' --target-dir=/data/backup/
```bash
xtrabackup --backup --tables='^(mydb\.|otherdb\.(important_table|critical_table))' --target-dir=/data/backup/
```

This command backs up all tables from `mydb` plus specific tables from `otherdb`.
Expand All @@ -1171,10 +1175,10 @@ The following table lists common mistakes when using `--tables` and `--databases

| Incorrect usage | What happens |
|---|---|
| Using both `--tables` and `--databases` together | XtraBackup ignores `--databases` and only processes `--tables`. Your backup may not include the databases you expected. |
| Using both `--tables` and `--databases` together | XtraBackup does not ignore `--databases`; it uses it as an allow-list. Databases not in the list are skipped. Databases in the list have all their tables included, ignoring the `--tables` regex. |
| Using `--databases` with regular expressions | Regular expressions are not supported by `--databases`. XtraBackup treats the regular expression as a literal database name. If that database name does not exist, the backup will be empty or fail. |
| Using `--tables` without quotes for regex patterns | Without quotes, the shell may interpret special regex characters. This causes incorrect pattern matching or syntax errors. |
| Using `--databases=mydb` expecting to include all tables | Without the `.*` wildcard, `--databases=mydb` may not include all tables. Use `--databases=mydb.*` to include all tables in the database. |
| Using `--databases=mydb.*` expecting to include all tables | XtraBackup treats `.*` as a literal table name (looking for a table named `*`). Use `--databases=mydb` to include all tables in the database. |
| Mixing comma-separated lists with regex in `--tables` | The `--tables` option accepts either a comma-separated list OR a quoted regular expression, but not both at the same time. Mixing both syntaxes will not work as expected. |

### tables-file
Expand Down Expand Up @@ -1261,12 +1265,12 @@ This option works, only if `--estimate-memory` option is enabled. If the `--esti

An example of how to enable the Smart memory estimation feature:

```{.bash data-prompt="$"}
$ xtrabackup --backup --estimate-memory=ON --target-dir=/data/backups/
```bash
xtrabackup --backup --estimate-memory=ON --target-dir=/data/backups/
```

```{.bash data-prompt="$"}
$ xtrabackup --prepare --use-free-memory-pct=50 --target-dir=/data/backups/
```bash
xtrabackup --prepare --use-free-memory-pct=50 --target-dir=/data/backups/
```

### use-memory
Expand Down