From 73f21dab8a7be1804d5b28b2fd7819b6289692cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aur=C3=A9lien=20Arena?= Date: Mon, 14 Oct 2024 14:23:29 +0100 Subject: [PATCH] Added a new page for the backup inspect command. (#1859) Co-authored-by: Reneta Popova --- modules/ROOT/content-nav.adoc | 1 + modules/ROOT/pages/backup-restore/index.adoc | 1 + .../ROOT/pages/backup-restore/inspect.adoc | 236 ++++++++++++++++++ 3 files changed, 238 insertions(+) create mode 100644 modules/ROOT/pages/backup-restore/inspect.adoc diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index ca8b850a0..d7c5a81fa 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -164,6 +164,7 @@ ** xref:backup-restore/modes.adoc[] ** xref:backup-restore/online-backup.adoc[] ** xref:backup-restore/aggregate.adoc[] +** xref:backup-restore/inspect.adoc[] ** xref:backup-restore/restore-backup.adoc[] ** xref:backup-restore/offline-backup.adoc[] ** xref:backup-restore/restore-dump.adoc[] diff --git a/modules/ROOT/pages/backup-restore/index.adoc b/modules/ROOT/pages/backup-restore/index.adoc index 9257361c8..9be0cbdd2 100644 --- a/modules/ROOT/pages/backup-restore/index.adoc +++ b/modules/ROOT/pages/backup-restore/index.adoc @@ -8,6 +8,7 @@ This chapter describes the following: * xref:backup-restore/modes.adoc[Backup modes] -- The supported backup modes. * xref:backup-restore/online-backup.adoc[Back up an online database] -- How to back up an online database. * xref:backup-restore/aggregate.adoc[Aggregate a database backup chain] - How to aggregate a backup chain into a single backup. +* xref:backup-restore/inspect.adoc[Inspect the metadata of a database backup file] -- How to inspect the metadata of a database backup file. * xref:backup-restore/restore-backup.adoc[Restore a database backup] -- How to restore a database backup in a live Neo4j deployment. * xref:backup-restore/offline-backup.adoc[Back up an offline database] -- How to back up an offline database. * xref:backup-restore/restore-dump.adoc[Restore a database dump] -- How to restore a database dump in a live Neo4j deployment. diff --git a/modules/ROOT/pages/backup-restore/inspect.adoc b/modules/ROOT/pages/backup-restore/inspect.adoc new file mode 100644 index 000000000..131e11785 --- /dev/null +++ b/modules/ROOT/pages/backup-restore/inspect.adoc @@ -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=] [--database=] + [--format=] +---- + +=== Description + +Command to read the backup metadata. + +[[inspect-backup-command-parameters]] +=== Parameters + +.`neo4j-admin backup inspect` parameters +[options="header", cols="1m,3a"] +|=== +| Parameter +| Description + +| +|Path denoting either a directory where backups are stored or a single backup to inspect. +|=== + +[NOTE] +==== +The `` 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= +|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= +| Name of the database to inspect. +| + +| --format= +| 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_. +==== + + + + + + + + + + + +