diff --git a/docs/create-partial-backup.md b/docs/create-partial-backup.md index fd05146d..a4d73b37 100644 --- a/docs/create-partial-backup.md +++ b/docs/create-partial-backup.md @@ -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 +* 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. + + 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`. + +## 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) + +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 @@ -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" ``` @@ -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. + + * Do **not** use `.*`. 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`. @@ -92,8 +174,8 @@ 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 @@ -101,6 +183,10 @@ $ xtrabackup --backup --databases='mysql,sys,performance_schema,test' --target-d 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. + !!! note Tables processed during the –prepare step may also be added to the backup diff --git a/docs/xtrabackup-option-reference.md b/docs/xtrabackup-option-reference.md index 9bd5f7e1..0b5ecb87 100644 --- a/docs/xtrabackup-option-reference.md +++ b/docs/xtrabackup-option-reference.md @@ -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 @@ -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 @@ -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" -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 `*`. 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`. @@ -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. @@ -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 @@ -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: @@ -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`. @@ -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 @@ -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