cloudnative-pg / cloudnative-pg/cloudnative-pg

[Feature]: Allow configuring pg_basebackup --sync-method=syncfs

Open
#11,379 0 comments 1 reaction 1 assignee Claimed by @gbartolini View on GitHub
triage
Dominant language
Go
Stars
9.3k
Forks
759
Avg merge
2d 6h
Merged PRs (30d)
44

Description

### Is there an existing issue already for this feature request/idea?

- [x] I have searched for an existing issue, and could not find anything. I believe this is a new feature request to be evaluated.

### What problem is this feature going to solve? Why should it be added?

CloudNativePG currently invokes `pg_basebackup` without exposing or passing
the `--sync-method` option.

The current `ClonePgData` implementation constructs the command with options
such as:

```text
-D
-v
-w
-d
--waldir # when configured
```

As a result, pg_basebackup uses its default fsync synchronization method.

PostgreSQL 17 and later support:

```text
pg_basebackup --sync-method=syncfs
```

For clusters with very large data directories or millions of files, the final
fsync phase can take a significant amount of time because PostgreSQL must
recursively open and synchronize individual files.

Using syncfs can avoid per-file synchronization and ask the operating system
to synchronize the filesystems containing the backup destination instead.
This can reduce replica provisioning and recovery time on supported Linux
systems.

This request is specifically about the final durability synchronization phase.
It is not expected to change the estimating backup size phase.

A related request exists for pg_rewind in #11378, but it does not cover
pg_basebackup.

### Describe the solution you'd like

Please expose an opt-in, typed CloudNativePG configuration for selecting the
pg_basebackup synchronization method.

When configured as syncfs, CloudNativePG should invoke:

```text
pg_basebackup --sync-method=syncfs ...
```

The setting should apply to every CloudNativePG operation that uses
ClonePgData, including:

- automatic replica joins and replica rebuilds;
- cluster bootstrap through pg_basebackup.

Suggested behavior:

- Keep fsync as the default for backward compatibility.
- Allow fsync and syncfs through a typed enum rather than arbitrary extra
command-line arguments.
- Support syncfs for PostgreSQL 17 and later.
- Return a clear validation or compatibility error for unsupported PostgreSQL
versions.
- Log the selected synchronization method when starting pg_basebackup.
- Document that syncfs is Linux-specific and can flush unrelated data located
on the same filesystem.
- Add tests that verify the generated pg_basebackup arguments.

The exact API field and location can follow the project's preferred
configuration design. The configuration must persist at cluster level so that
it also applies to automatic replica rebuilds, not only initial bootstrap.

### Describe alternatives you've considered


- Continue using the default fsync method. This is safe, but the final
synchronization phase can be slow when the data directory contains millions
of files.
- Run pg_basebackup manually. This bypasses the CloudNativePG instance
lifecycle and is operationally risky.
- Patch the generated join Job. The command is constructed internally by the
instance manager, so this is not a durable or supported solution.
- Use --no-sync. This weakens durability guarantees and is not an acceptable
alternative.
- Use volume snapshots. They are not available with every storage provider and
do not replace streaming replica joins in all environments.

### Additional context

Latest CloudNativePG release checked:

```text
v1.30.0
```

Current main implementation checked:

https://github.com/cloudnative-pg/cloudnative-pg/blob/84aa2a2a641c8014306c88e4caf94c8c6ec46350/pkg/management/postgres/join.go

Current BootstrapPgBaseBackup API:

https://github.com/cloudnative-pg/cloudnative-pg/blob/84aa2a2a641c8014306c88e4caf94c8c6ec46350/api/v1/cluster_types.go

Related pg_rewind feature request:

https://github.com/cloudnative-pg/cloudnative-pg/issues/11378

PostgreSQL documentation:

https://www.postgresql.org/docs/current/app-pgbasebackup.html

### Backport?

N/A

### Are you willing to actively contribute to this feature?

No

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.