file_copy_method

Definition PG 18 manual

Specifies the method used to copy files. Possible values are COPY (default) and CLONE (if operating support is available).

This parameter affects:

CLONE uses the copy_file_range() (Linux, FreeBSD) or copyfile (macOS) system calls, giving the kernel the opportunity to share disk blocks or push work down to lower layers on some file systems.

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.

Operational considerations

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.

Workload guidance

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.

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.

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