Inspect the metadata of a backup file

You can inspect the metadata of a database backup file using the neo4j-admin backup inspect 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 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 restore or 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.

Syntax

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.

Parameters

Table 1. neo4j-admin backup inspect parameters
Parameter Description

<backup-path>

Path denoting either a directory where backups are stored or a single backup to inspect.

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

Options

Table 2. neo4j-admin backup inspect options
Option Description Default

--additional-config=<file>[1]

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.

1. See Tools → Configuration for details.

Examples

Given the folder /backups containing a set of database backups:

/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:

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

bin/neo4j-admin backup inspect /backups --show-metadata --latest-backup
Example output
|                                              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:

bin/neo4j-admin backup inspect /backups --show-metadata --latest-chain --database=london
Example output
|                                              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:

bin/neo4j-admin backup inspect /backups/london-2024-10-07T16-04-05.backup  --show-metadata --latest-chain
Example output
|                                              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 |

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.