Transaction logging

Neo4j keeps track of all write operations to each database to ensure data consistency and enable recovery.

Transaction log files

A transaction log file contains a sequence of records with all changes made to a particular database as part of each transaction, including data, indexes, and constraints.

The transaction log serves multiple purposes, including providing differential backups and supporting cluster operations. At a minimum, the most recent non-empty transaction log is retained for any given configuration. It is important to note that transaction logs are unrelated to log monitoring.

The transaction logging configuration is set per database and can be configured using the following configuration settings:

Configure transaction log location

By default, transaction logs for a database are located at <NEO4J_HOME>/data/transactions/<database-name>.

The root directory where those folders are located is configured by server.directories.transaction.logs.root. The value is a path. If relative, it is resolved from server.directories.data. For maximum performance, it is recommended to configure transaction logs to be stored on a dedicated device.

Configure transaction log preallocation

You can specify if Neo4j should try to preallocate logical log files in advance using the parameter db.tx_log.preallocate. By default, it is true. Log preallocation optimizes the filesystem by ensuring there is room to accommodate newly generated files and avoid file-level fragmentation. This configuration setting is dynamic and can be changed at runtime.

Configure transaction log rotation size

You can specify how much space a single transaction log file can roughly occupy using db.tx_log.rotation.size. By default, it is set to 256 MiB, which means that after a transaction log file reaches this size, it is rotated and a new one is created. The minimum accepted value is 128K (128 KiB). This configuration setting is dynamic and can be changed at runtime.

This setting influences how much space can be reclaimed by all checkpoint strategies under the following:

To reclaim a given file, the newest checkpoint for the transaction log must exist in another file. So if you have a huge transaction log, then it is likely that your latest checkpoint is in the same file, making it impossible to reclaim said file. For information about checkpointing, see Control transaction log pruning.

Configure transaction log retention policy

Manually deleting transaction log files is not supported.

You can control the number of transaction logs that Neo4j keeps to back up the database using the parameter db.tx_log.rotation.retention_policy. This configuration setting is dynamic and can be changed at runtime. For more information about how to do it, see Update dynamic settings.

Up to Neo4j 5.12, the default value is set to 2 days, which means Neo4j keeps logical logs that contain any transaction committed within 2 days and prunes the ones that only contain transactions older than 2 days.

From Neo4j 5.9 onwards, you can optionally add a period-based restriction to the size of logs to keep. For example, 2 days 1G prunes logical logs that only contain transactions older than 2 days or are larger than 1G.

Starting from Neo4j 5.13, the default value is changed to 2 days 2G, which means Neo4j keeps logical logs that contain any transaction committed within 2 days from the current time and within the allocated log space (2G).

Other possible ways to configure the log retention policy are:

db.tx_log.rotation.retention_policy=true|keep_all — keep transaction logs indefinitely.

This option is not recommended due to the effectively unbounded storage usage. Old transaction logs cannot be safely archived or removed by external jobs since safe log pruning requires knowledge about the most recent successful checkpoint.

db.tx_log.rotation.retention_policy=false|keep_none — keep only the most recent non-empty log.

Log pruning is called only after checkpoint completion to ensure at least one checkpoint and points to a valid place in the transaction log data. In reality, this means that all transaction logs created between checkpoints are kept for some time, and only after a checkpoint, the pruning strategy removes them. For more details on how to speed up checkpointing, see Configure log pruning. To force a checkpoint, run the procedure CALL db.checkpoint().

This option is not recommended in production Enterprise Edition environments, as differential backups rely on the presence of the transaction logs since the last backup.

<number><optional unit> <type> <optional space restriction> where valid units are K, M, and G, and valid types are files, size, txs, entries, hours, and days. Valid optional space restriction is a logical log space restriction like 1G. For example, 2 days 1G limits the logical log space on the disk to 1G at most 2 days per database.

Table 1. Types that can be used to control log retention
Type	Description	Example
`files`	The number of the most recent transaction log files to keep after pruning.	`db.tx_log.rotation.retention_policy=10 files`
`size`	The max disk size of the transaction log files to keep after pruning. For example, `500M size` leaves at least 500M worth of files behind.	`db.tx_log.rotation.retention_policy=300M size`
`txs or entries`	The number of transactions (in the files) to keep after pruning, regardless of file count or size. `txs` and `entries` are synonymous. If set, the policy keeps the 500k latest transactions from each database and prunes any older transactions.	`db.tx_log.rotation.retention_policy=500k txs`
`hours`	Keep logs that contain any transaction committed within the specified number of hours from the current time. The value of `10 hours` ensures that at least 10 hours' worth of transactions is present in the logs.	`db.tx_log.rotation.retention_policy=10 hours`
`days`	Keep logs that contain any transaction committed within the specified number of days from the current time.	`db.tx_log.rotation.retention_policy=30 days`
`days and size`	Keep logs that contain any transaction committed within the specified number of days from the current time and within the allocated log space.	`db.tx_log.rotation.retention_policy=2 days 1G`