-
Notifications
You must be signed in to change notification settings - Fork 73
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added a new page for the backup inspect command. (#1859)
Co-authored-by: Reneta Popova <[email protected]>
- Loading branch information
1 parent
9ad1096
commit 73f21da
Showing
3 changed files
with
238 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,236 @@ | ||
| [role=enterprise-edition] | ||
| [[inspect-backup]] | ||
| = Inspect the metadata of a backup file | ||
| :description: This section describes how to inspect the metadata of backup files. Metadata are information like the database name, the backup compression, the transaction range that the backup contains etc.. | ||
|
|
||
| You can inspect the metadata of a database backup file using the `neo4j-admin backup inspect` command. | ||
|
|
||
| [[inspect-backup-command]] | ||
| == Command | ||
|
|
||
| The inspect command lists the metadata stored in the header of backup files. | ||
| This metadata primarily defines how backups are connected to form xref:backup-restore/online-backup.adoc#backup-chain[backup chains]. | ||
| A backup chain is a sequence of one or more backup(s) logically connected. | ||
| The order of the sequence guarantees that when replayed (see xref:backup-restore/restore-backup.adoc[restore] or xref:backup-restore/aggregate.adoc[aggregate]), the store and the transaction data are consumed in a consistent manner. | ||
|
|
||
| The metadata contains the following information: | ||
|
|
||
| * *Database*: database name of the database fragment that the backup includes. | ||
| * *Database ID*: a unique identifier that distinguishes databases (even with the same name). | ||
| * *Time*: time the backup was taken. | ||
| * *Full*: indicates whether it is a full backup (i.e. initial backup containing the store files) or a differential backup (i.e. subsequent backup containing only the transactions to be applied to the store files). | ||
| * *Compressed*: indicates whether the backup data inside the backup file is compressed. | ||
| * *Lowest transaction ID*: when the backup is full, this value is always 1, and when it is a differential backup, the value corresponds to the first transaction ID the backup starts with. | ||
| * *Highest transaction ID*: similarly, this value indicates the last transaction ID stored in the backup file. | ||
|
|
||
| [[inspect-backup-syntax]] | ||
| === Syntax | ||
|
|
||
| [source,role=noheader] | ||
| ---- | ||
| neo4j-admin backup inspect [-h] [--empty] [--expand-commands] [--latest-backup] | ||
| [--latest-chain] [--show-metadata] [--verbose] | ||
| [--additional-config=<file>] [--database=<database>] | ||
| [--format=<value>] <backup-path> | ||
| ---- | ||
|
|
||
| === Description | ||
|
|
||
| Command to read the backup metadata. | ||
|
|
||
| [[inspect-backup-command-parameters]] | ||
| === Parameters | ||
|
|
||
| .`neo4j-admin backup inspect` parameters | ||
| [options="header", cols="1m,3a"] | ||
| |=== | ||
| | Parameter | ||
| | Description | ||
|
|
||
| |<backup-path> | ||
| |Path denoting either a directory where backups are stored or a single backup to inspect. | ||
| |=== | ||
|
|
||
| [NOTE] | ||
| ==== | ||
| The `<backup-path>` parameter can also inspect backups stored in AWS S3 buckets (from Neo4j 5.19), Google Cloud storage buckets (from Neo4j 5.21), and Azure buckets (from Neo4j 5.24). | ||
| ==== | ||
|
|
||
| [[inspect-backup-command-options]] | ||
| === Options | ||
|
|
||
| .`neo4j-admin backup inspect` options | ||
| [options="header", cols="5m,6a,4m"] | ||
| |=== | ||
| | Option | ||
| | Description | ||
| | Default | ||
|
|
||
| |--additional-config=<file> | ||
| |Configuration file with additional configuration. | ||
| | | ||
|
|
||
| | --expand-commands | ||
| | Allow command expansion in config value evaluation. | ||
| | | ||
|
|
||
| |-h, --help | ||
| |Show this help message and exit. | ||
| | | ||
|
|
||
| | --latest-backup | ||
| | Show only the latest backup. | ||
| | false | ||
|
|
||
| | --latest-chain | ||
| | List the full backup chain ending with the latest downloaded backup. | ||
| | false | ||
|
|
||
| | --show-metadata | ||
| | Show the backup metadata. | ||
| | false | ||
|
|
||
| | --database=<database> | ||
| | Name of the database to inspect. | ||
| | | ||
|
|
||
| | --format=<value> | ||
| | Format of the output of the command. Possible values are: 'JSON, TABULAR'. | ||
| | TABULAR | ||
|
|
||
| | --empty | ||
| | Include empty backups. | ||
| | false | ||
|
|
||
| |--verbose | ||
| |Enable verbose output. | ||
| | | ||
| |=== | ||
|
|
||
|
|
||
| [[aggregate-backup-example]] | ||
| == Examples | ||
|
|
||
| Given the folder _/backups_ containing a set of database backups: | ||
|
|
||
| [source,shell] | ||
| ---- | ||
| /backups | ||
| ├── london-2024-10-07T16-03-51.backup | ||
| ├── london-2024-10-07T16-04-05.backup | ||
| ├── malmo-2024-10-07T16-00-07.backup | ||
| ├── malmo-2024-10-07T16-00-19.backup | ||
| ├── malmo-2024-10-07T16-00-34.backup | ||
| ├── malmo-2024-10-07T16-00-44.backup | ||
| ├── malmo-2024-10-07T16-00-50.backup | ||
| ├── malmo-2024-10-07T16-01-08.backup | ||
| ├── malmo-2024-10-07T16-01-24.backup | ||
| └── neo4j-2024-10-07T16-05-37.backup | ||
| ---- | ||
|
|
||
| === Listing the metadata of the backup files | ||
|
|
||
| The following command lists the backup files' names along with their respective metadata: | ||
|
|
||
| [source,shell] | ||
| ---- | ||
| bin/neo4j-admin backup inspect /backups --show-metadata --empty | ||
| ---- | ||
|
|
||
| The `--empty` option is used to include the empty backups. | ||
| An empty backup is created when a database is backed up but no new data exists. | ||
| Empty backups are used to record the backup history. | ||
|
|
||
| .Example output | ||
| [result] | ||
| ---- | ||
| | FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | | ||
| | file:///backups/neo4j-2024-10-07T16-05-37.backup | neo4j | 7dcb1d0c-4374-4476-b8ae-d3c3f124683f | 2024-10-07T16:05:37 | true | true | 1 | 3 | | ||
| | file:///backups/malmo-2024-10-07T16-01-24.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:24 | true | true | 1 | 8 | | ||
| | file:///backups/malmo-2024-10-07T16-01-08.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:08 | true | true | 1 | 7 | | ||
| | file:///backups/malmo-2024-10-07T16-00-50.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:50 | false | true | 0 | 0 | | ||
| | file:///backups/malmo-2024-10-07T16-00-44.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:44 | false | true | 7 | 7 | | ||
| | file:///backups/malmo-2024-10-07T16-00-34.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:34 | false | true | 6 | 6 | | ||
| | file:///backups/malmo-2024-10-07T16-00-19.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:19 | false | true | 0 | 0 | | ||
| | file:///backups/malmo-2024-10-07T16-00-07.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:07 | true | true | 1 | 5 | | ||
| | file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | | ||
| | file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 | | ||
| ---- | ||
|
|
||
| === Listing the latest backups | ||
|
|
||
| To list only the most recent backups performed for each database, use the `--latest-backup` option. | ||
|
|
||
| [source,shell] | ||
| ---- | ||
| bin/neo4j-admin backup inspect /backups --show-metadata --latest-backup | ||
| ---- | ||
|
|
||
| .Example output | ||
| [result] | ||
| ---- | ||
| | FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | | ||
| | file:///backups/neo4j-2024-10-07T16-05-37.backup | neo4j | 7dcb1d0c-4374-4476-b8ae-d3c3f124683f | 2024-10-07T16:05:37 | true | true | 1 | 3 | | ||
| | file:///backups/malmo-2024-10-07T16-01-24.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:24 | true | true | 1 | 8 | | ||
| | file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | | ||
| ---- | ||
|
|
||
| === Inspecting backup chains | ||
|
|
||
| A backup chain corresponds to a sequence of one or more backup(s) logically connected by their transaction IDs. | ||
| To inspect the backup chains of a given database, use the `--latest-chain` option and the `--database` option with the database whose backup chain you want to inspect: | ||
|
|
||
| [source,shell] | ||
| ---- | ||
| bin/neo4j-admin backup inspect /backups --show-metadata --latest-chain --database=london | ||
| ---- | ||
|
|
||
| .Example output | ||
| [result] | ||
| ---- | ||
| | FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | | ||
| | file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | | ||
| | file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 | | ||
| ---- | ||
|
|
||
| The result returns a chain of size two: | ||
|
|
||
| * The first backup is a full backup containing the store files within the transaction range [1,5]. | ||
| * The second backup is a differential backup containing only the subsequent modifications to the store files. | ||
| Those modifications are materialised by a sequence of transactions to apply. | ||
| Its range is [6,6]. | ||
|
|
||
|
|
||
| === Inspecting a backup chain ending with a specific backup | ||
|
|
||
| To inspect a backup chain ending with a specific backup, use the `--latest-chain` option as follows: | ||
|
|
||
| [source,shell] | ||
| ---- | ||
| bin/neo4j-admin backup inspect /backups/london-2024-10-07T16-04-05.backup --show-metadata --latest-chain | ||
| ---- | ||
|
|
||
| .Example output | ||
| [result] | ||
| ---- | ||
| | FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | | ||
| | file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | | ||
| | file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 | | ||
| ---- | ||
|
|
||
| [NOTE] | ||
| ==== | ||
| In this case, the `--database` option is unnecessary because the database identifier is part of the metadata stored in the header of the backup file _london-2024-10-07T16-04-05.backup_. | ||
| ==== | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|