file_copy_method

file_copy_method — Selects the file copy method. Observed in PG18–19 Beta 3; its last measured boot default is copy in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Selects the file copy method.”

Identity

Type , Valueenum: Upstream pg_settings type
Context , Valueuser: Settable by an ordinary user
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Valuecopy, clone: — for non-enum types
Category , ValueResource Usage / Disk: Upstream classification
Latest boot value , Valuecopy: copy

Lifecycle

Fact	Value
First observed	PG18
Present in	PG18–19 Beta 3
Removed in	No
Introduction commit	`f78ca6f3ebbb` — Introduce file_copy_method setting.
Commit date	2025-04-08
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG18–19 Beta 3	`copy`	—	copy

How it works

file_copy_method chooses COPY or CLONE for CREATE DATABASE … STRATEGY=FILE_COPY and ALTER DATABASE … SET TABLESPACE. It does not change SQL COPY or general file reads.

CLONE uses copy_file_range() on Linux/FreeBSD or copyfile on macOS, allowing supporting file systems to share blocks or offload the operation. Availability and the actual optimization depend on the operating system and file system; selecting CLONE does not prove that blocks were shared.

Copy-on-write can make the initial operation fast, but later writes allocate private blocks and snapshots still share failure domains. Backup, quota, and free-space accounting must understand the file system semantics. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
OLTP	Use COPY as the compatibility baseline. Select CLONE only after CREATE DATABASE … STRATEGY=FILE_COPY and ALTER DATABASE … SET TABLESPACE are tested on the exact kernel and file system, including backup, quota, and free-space monitoring.
OLAP	Workload type does not determine the method; clone support and copy-on-write behavior do. CLONE can shorten large database copies, but benchmark the initial operation and subsequent write amplification before standardizing it.
Small nodes	Prefer COPY unless the file system’s clone semantics are known and operational tooling understands shared extents. A fast initial clone can still create later space pressure on a small volume.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	`clone`	different	`clone`
OLAP	`clone`	different	`clone`
CRIT	`clone`	different	`clone`
TINY	`clone`	different	`clone`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG18–19 Beta 3 = clone (dcs); OLAP: PG18–19 Beta 3 = clone (dcs); CRIT: PG18–19 Beta 3 = clone (dcs); TINY: PG18–19 Beta 3 = clone (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The template comment explicitly targets near-instant database cloning on copy-on-write file systems; support and free-space semantics still require deployment validation.

Common pitfalls

Assuming CLONE guarantees copy-on-write block sharing; the kernel and file system decide the actual optimization.
Expecting the parameter to affect SQL COPY or ordinary relation reads.
Ignoring later private-block allocation and free-space pressure after a fast clone.
Using CLONE before backup, quota, and filesystem tooling understand shared extents.

file_extend_method · data_directory · temp_tablespaces · shared_buffers