Skip to content

Commit 73f21da

Browse files
au-arenarenetapopova
au-arena
and
renetapopova
authored
Added a new page for the backup inspect command. (#1859)
Co-authored-by: Reneta Popova <[email protected]>
1 parent 9ad1096 commit 73f21da

File tree

3 files changed

+238
-0
lines changed

3 files changed

+238
-0
lines changed

‎modules/ROOT/content-nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,7 @@
164164
** xref:backup-restore/modes.adoc[]
165165
** xref:backup-restore/online-backup.adoc[]
166166
** xref:backup-restore/aggregate.adoc[]
167+
** xref:backup-restore/inspect.adoc[]
167168
** xref:backup-restore/restore-backup.adoc[]
168169
** xref:backup-restore/offline-backup.adoc[]
169170
** xref:backup-restore/restore-dump.adoc[]

‎modules/ROOT/pages/backup-restore/index.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This chapter describes the following:
88
* xref:backup-restore/modes.adoc[Backup modes] -- The supported backup modes.
99
* xref:backup-restore/online-backup.adoc[Back up an online database] -- How to back up an online database.
1010
* xref:backup-restore/aggregate.adoc[Aggregate a database backup chain] - How to aggregate a backup chain into a single backup.
11+
* xref:backup-restore/inspect.adoc[Inspect the metadata of a database backup file] -- How to inspect the metadata of a database backup file.
1112
* xref:backup-restore/restore-backup.adoc[Restore a database backup] -- How to restore a database backup in a live Neo4j deployment.
1213
* xref:backup-restore/offline-backup.adoc[Back up an offline database] -- How to back up an offline database.
1314
* xref:backup-restore/restore-dump.adoc[Restore a database dump] -- How to restore a database dump in a live Neo4j deployment.

‎modules/ROOT/pages/backup-restore/inspect.adoc‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
[role=enterprise-edition]
2+
[[inspect-backup]]
3+
= Inspect the metadata of a backup file
4+
: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..
5+
6+
You can inspect the metadata of a database backup file using the `neo4j-admin backup inspect` command.
7+
8+
[[inspect-backup-command]]
9+
== Command
10+
11+
The inspect command lists the metadata stored in the header of backup files.
12+
This metadata primarily defines how backups are connected to form xref:backup-restore/online-backup.adoc#backup-chain[backup chains].
13+
A backup chain is a sequence of one or more backup(s) logically connected.
14+
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.
15+
16+
The metadata contains the following information:
17+
18+
* *Database*: database name of the database fragment that the backup includes.
19+
* *Database ID*: a unique identifier that distinguishes databases (even with the same name).
20+
* *Time*: time the backup was taken.
21+
* *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).
22+
* *Compressed*: indicates whether the backup data inside the backup file is compressed.
23+
* *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.
24+
* *Highest transaction ID*: similarly, this value indicates the last transaction ID stored in the backup file.
25+
26+
[[inspect-backup-syntax]]
27+
=== Syntax
28+
29+
[source,role=noheader]
30+
----
31+
neo4j-admin backup inspect [-h] [--empty] [--expand-commands] [--latest-backup]
32+
[--latest-chain] [--show-metadata] [--verbose]
33+
[--additional-config=<file>] [--database=<database>]
34+
[--format=<value>] <backup-path>
35+
----
36+
37+
=== Description
38+
39+
Command to read the backup metadata.
40+
41+
[[inspect-backup-command-parameters]]
42+
=== Parameters
43+
44+
.`neo4j-admin backup inspect` parameters
45+
[options="header", cols="1m,3a"]
46+
|===
47+
| Parameter
48+
| Description
49+
50+
|<backup-path>
51+
|Path denoting either a directory where backups are stored or a single backup to inspect.
52+
|===
53+
54+
[NOTE]
55+
====
56+
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).
57+
====
58+
59+
[[inspect-backup-command-options]]
60+
=== Options
61+
62+
.`neo4j-admin backup inspect` options
63+
[options="header", cols="5m,6a,4m"]
64+
|===
65+
| Option
66+
| Description
67+
| Default
68+
69+
|--additional-config=<file>
70+
|Configuration file with additional configuration.
71+
|
72+
73+
| --expand-commands
74+
| Allow command expansion in config value evaluation.
75+
|
76+
77+
|-h, --help
78+
|Show this help message and exit.
79+
|
80+
81+
| --latest-backup
82+
| Show only the latest backup.
83+
| false
84+
85+
| --latest-chain
86+
| List the full backup chain ending with the latest downloaded backup.
87+
| false
88+
89+
| --show-metadata
90+
| Show the backup metadata.
91+
| false
92+
93+
| --database=<database>
94+
| Name of the database to inspect.
95+
|
96+
97+
| --format=<value>
98+
| Format of the output of the command. Possible values are: 'JSON, TABULAR'.
99+
| TABULAR
100+
101+
| --empty
102+
| Include empty backups.
103+
| false
104+
105+
|--verbose
106+
|Enable verbose output.
107+
|
108+
|===
109+
110+
111+
[[aggregate-backup-example]]
112+
== Examples
113+
114+
Given the folder _/backups_ containing a set of database backups:
115+
116+
[source,shell]
117+
----
118+
/backups
119+
├── london-2024-10-07T16-03-51.backup
120+
├── london-2024-10-07T16-04-05.backup
121+
├── malmo-2024-10-07T16-00-07.backup
122+
├── malmo-2024-10-07T16-00-19.backup
123+
├── malmo-2024-10-07T16-00-34.backup
124+
├── malmo-2024-10-07T16-00-44.backup
125+
├── malmo-2024-10-07T16-00-50.backup
126+
├── malmo-2024-10-07T16-01-08.backup
127+
├── malmo-2024-10-07T16-01-24.backup
128+
└── neo4j-2024-10-07T16-05-37.backup
129+
----
130+
131+
=== Listing the metadata of the backup files
132+
133+
The following command lists the backup files' names along with their respective metadata:
134+
135+
[source,shell]
136+
----
137+
bin/neo4j-admin backup inspect /backups --show-metadata --empty
138+
----
139+
140+
The `--empty` option is used to include the empty backups.
141+
An empty backup is created when a database is backed up but no new data exists.
142+
Empty backups are used to record the backup history.
143+
144+
.Example output
145+
[result]
146+
----
147+
| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX |
148+
| file:///backups/neo4j-2024-10-07T16-05-37.backup | neo4j | 7dcb1d0c-4374-4476-b8ae-d3c3f124683f | 2024-10-07T16:05:37 | true | true | 1 | 3 |
149+
| file:///backups/malmo-2024-10-07T16-01-24.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:24 | true | true | 1 | 8 |
150+
| file:///backups/malmo-2024-10-07T16-01-08.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:08 | true | true | 1 | 7 |
151+
| file:///backups/malmo-2024-10-07T16-00-50.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:50 | false | true | 0 | 0 |
152+
| file:///backups/malmo-2024-10-07T16-00-44.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:44 | false | true | 7 | 7 |
153+
| file:///backups/malmo-2024-10-07T16-00-34.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:34 | false | true | 6 | 6 |
154+
| file:///backups/malmo-2024-10-07T16-00-19.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:19 | false | true | 0 | 0 |
155+
| file:///backups/malmo-2024-10-07T16-00-07.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:07 | true | true | 1 | 5 |
156+
| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 |
157+
| file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 |
158+
----
159+
160+
=== Listing the latest backups
161+
162+
To list only the most recent backups performed for each database, use the `--latest-backup` option.
163+
164+
[source,shell]
165+
----
166+
bin/neo4j-admin backup inspect /backups --show-metadata --latest-backup
167+
----
168+
169+
.Example output
170+
[result]
171+
----
172+
| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX |
173+
| file:///backups/neo4j-2024-10-07T16-05-37.backup | neo4j | 7dcb1d0c-4374-4476-b8ae-d3c3f124683f | 2024-10-07T16:05:37 | true | true | 1 | 3 |
174+
| file:///backups/malmo-2024-10-07T16-01-24.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:24 | true | true | 1 | 8 |
175+
| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 |
176+
----
177+
178+
=== Inspecting backup chains
179+
180+
A backup chain corresponds to a sequence of one or more backup(s) logically connected by their transaction IDs.
181+
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:
182+
183+
[source,shell]
184+
----
185+
bin/neo4j-admin backup inspect /backups --show-metadata --latest-chain --database=london
186+
----
187+
188+
.Example output
189+
[result]
190+
----
191+
| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX |
192+
| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 |
193+
| file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 |
194+
----
195+
196+
The result returns a chain of size two:
197+
198+
* The first backup is a full backup containing the store files within the transaction range [1,5].
199+
* The second backup is a differential backup containing only the subsequent modifications to the store files.
200+
Those modifications are materialised by a sequence of transactions to apply.
201+
Its range is [6,6].
202+
203+
204+
=== Inspecting a backup chain ending with a specific backup
205+
206+
To inspect a backup chain ending with a specific backup, use the `--latest-chain` option as follows:
207+
208+
[source,shell]
209+
----
210+
bin/neo4j-admin backup inspect /backups/london-2024-10-07T16-04-05.backup --show-metadata --latest-chain
211+
----
212+
213+
.Example output
214+
[result]
215+
----
216+
| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX |
217+
| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 |
218+
| file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 |
219+
----
220+
221+
[NOTE]
222+
====
223+
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_.
224+
====
225+
226+
227+
228+
229+
230+
231+
232+
233+
234+
235+
236+

0 commit comments

Comments
 (0)