PXB-3662: Clarify --tables and --databases conflict in docs by satya-bodapati · Pull Request #452 · percona/pxb-docs

satya-bodapati · 2026-02-03T07:12:08Z

https://perconadev.atlassian.net/browse/PXB-3662

The --tables and --databases options in XtraBackup have complex interactions when used together, often leading to unexpected results such as skipping databases entirely or including all tables despite a regex filter.

This commit updates the documentation to:

Clarify that --databases acts as a high-level filter that precedes table-level checks, which can override --tables regex patterns.
Add a new "Filtering Behavior with Examples" section in docs/create-partial-backup.md to demonstrate why mixing these options fails.
Provide a solution for combining specific tables with full databases using --tables-file alongside --databases.
Update the "Mutual exclusion" warnings in docs/xtrabackup-option-reference.md to accurately describe the conflict and interaction between these parameters.

https://perconadev.atlassian.net/browse/PXB-3662 The --tables and --databases options in XtraBackup have complex interactions when used together, often leading to unexpected results such as skipping databases entirely or including all tables despite a regex filter. This commit updates the documentation to: - Clarify that `--databases` acts as a high-level filter that precedes table-level checks, which can override `--tables` regex patterns. - Add a new "Filtering Behavior with Examples" section in `docs/create-partial-backup.md` to demonstrate why mixing these options fails. - Provide a solution for combining specific tables with full databases using `--tables-file` alongside `--databases`. - Update the "Mutual exclusion" warnings in `docs/xtrabackup-option-reference.md` to accurately describe the conflict and interaction between these parameters.

patrickbirch

COmments in slack

patrickbirch · 2026-02-03T09:58:12Z

docs/create-partial-backup.md

Do not use Latin (e.g.). Use “For example,”

patrickbirch · 2026-02-03T09:58:36Z

docs/create-partial-backup.md

Don’t use bold formatting.

patrickbirch · 2026-02-03T09:59:03Z

docs/create-partial-backup.md

Do not use “it”.

patrickbirch · 2026-02-03T09:59:54Z

docs/create-partial-backup.md

You used a warning - would there be data loss or something critical if they used --tables and --databases?

patrickbirch · 2026-02-03T10:00:23Z

docs/create-partial-backup.md

This explains
Always add the referenced object - this what?

patrickbirch · 2026-02-03T10:00:45Z

docs/create-partial-backup.md

Result: No test1 tables.
Not a sentence

patrickbirch · 2026-02-03T10:01:13Z

docs/create-partial-backup.md

In line 52, you tell them to use tables-files, but in line 84 you give them other options.

Line 84 - entirely is redundant.

patrickbirch · 2026-02-03T10:02:11Z

docs/create-partial-backup.md

Line 95 - you explain that they don’t need to list the database name for the specific databases - that information should be in line 88.

patrickbirch · 2026-02-03T10:02:26Z

docs/create-partial-backup.md

Line 103 - warning again - this information is a note unless the users will lose data or corrupt their database.

patrickbirch · 2026-02-03T10:02:46Z

docs/create-partial-backup.md

Line 114 should be in line 108.

patrickbirch · 2026-02-03T10:03:13Z

docs/create-partial-backup.md

Remove all command prompts (something Alina and I are doing now).
Change {.bash data-prompt=“$”} to shell or bash

patrickbirch · 2026-02-03T11:08:47Z

docs/create-partial-backup.md

mydb table again?

patrickbirch · 2026-02-03T11:11:34Z

docs/create-partial-backup.md

+*   To back up specific tables, specify them in `database.table` format (e.g., `mydb.mytable`).
+
+!!! warning "No Wildcards or Regex"
+    The `--databases` option does **not** support wildcards (like `*`) or regular expressions.


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

patrickbirch · 2026-02-03T11:14:15Z

docs/create-partial-backup.md

What about using a generic .* instead of mydb? Users may not realize that mydb.* is an example.

patrickbirch · 2026-02-03T11:15:50Z

docs/xtrabackup-option-reference.md

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

-Regular expressions are not supported.
+!!! warning "No Wildcards or Regex"


add a blank line

patrickbirch · 2026-02-03T11:46:14Z

docs/create-partial-backup.md

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


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

patrickbirch · 2026-02-03T11:49:26Z

docs/xtrabackup-option-reference.md


-Regular expressions are not supported.
+!!! warning "No Wildcards or Regex"
+    The `--databases` option does **not** support wildcards (like `*`) or regular expressions. Do not use `mydb.*` as it will search for a literal table named `*`.


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

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

patrickbirch · 2026-02-03T12:22:06Z

docs/create-partial-backup.md

+
+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)


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.

patrickbirch · 2026-02-03T12:22:54Z

docs/create-partial-backup.md

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


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

patrickbirch · 2026-02-03T12:35:33Z

docs/create-partial-backup.md

+    * `--tables` uses regular expressions and implies a partial backup.
+    * `--databases` uses exact matching and implies a full backup of the listed databases.
+
+    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`.


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

patrickbirch · 2026-02-03T12:37:56Z

docs/create-partial-backup.md

-* 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


add links to the options reference for these options.

patrickbirch self-requested a review February 3, 2026 09:35