From: mmoldfield (@mmoldfield) <noreply+mmoldfield@github.com>
To: pgbackrest/pgbackrest <noreply+pgbackrest-pgbackrest@github.com>
Subject: [pgbackrest/pgbackrest] issue #2888: Proposal: experimental `syncfs` option for fresh restores
Date: Tue, 27 Oct 2026 01:03:09 +0000
Message-ID: <gh-pgbackrest-pgbackrest-2888@github.com> (raw)
I propose adding an experimental, opt-in restore mode that uses `syncfs()` instead of syncing each restored file individually. I’ve benchmarked an initial prototype and would like feedback on the design before preparing an upstream implementation.
This relates to [#2861](https://github.com/pgbackrest/pgbackrest/issues/2861), but focuses on fresh restores rather than backup repository writes.
The main motivation is faster replica creation for clusters containing many databases and small relation files. With large file counts, repeated synchronization can contribute substantially to restore time relative to the amount of data transferred.
The proposed sequence would be:
1. Open the destination directory before restore writes begin, and retain that descriptor until the final `syncfs()` so writeback errors during the restore can be reported.
2. Restore files through the existing workers, preserving checksum verification and metadata handling while deferring per-file syncs.
3. After workers and recovery-setting writes finish, perform a checked `syncfs()` before publishing the final `pg_control`.
Files would still be created, opened, written, and closed normally. Existing directory synchronization and final control-file syncing would remain in place. The aim is to preserve restore durability while reducing repeated synchronization costs that scale poorly with high file counts.
The feature would be experimental and disabled by default, requiring explicit opt-in. For example:
```bash
pgbackrest --stanza=example --restore-syncfs restore
```
Or in configuration:
```ini
[global:restore]
restore-syncfs=y
```
The option name is open for discussion, including whether `restore-sync-method=fsync|syncfs` would be preferable.
For a narrow-scope initial implementation, I’d target fresh restores into empty destinations on Linux 5.8+, including standby creation with a mapped WAL directory on the same file system as PGDATA. Would it make sense to defer delta restores, resumed restores, tablespaces, and cross-filesystem destinations for the initial prototype, or would it be preferable to include any of these from the start?
I benchmarked an initial prototype using a synthetic cluster containing 4,000 databases, each with 1,000 tables and primary-key indexes. This produced approximately 340 GB of logical data and just over 25 million restored files.
Tests ran on AWS EC2 `r8g.2xlarge` instances, with each benchmark container limited to 6 CPUs and 24 GiB of memory. Each host used a dedicated 512 GiB EBS gp3 volume, formatted with XFS and provisioned for 16,000 IOPS and 1,000 MiB/s throughput. The backup repository was Amazon S3.
The comparison used eight pairs of restores, with each stock/prototype pair running on the same host and volume. Four pairs ran stock first; four ran the prototype first. Every restore used 90 workers and the same offline full backup, restoring into a fresh destination.
Across eight matched pairs using 90 workers, the median time for restore preparation and file restoration was:
| Build | Median preparation and file-restoration time |
| --- | --- |
| Stock pgBackRest 2.60 | 65m 11s |
| pgBackRest 2.60 with the `syncfs` prototype | 44m 33s |
These results show a restore-time benefit for this synthetic workload and suggest the approach is worth testing on other clusters with high file counts relative to their total data size.
Looking forward to discussing this more.