# 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 {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `enum` | Upstream pg_settings type |
| Context | `user` | Settable by an ordinary user |
| Unit | — | Raw unit |
| Range | — | Raw limits in the last observed version |
| Enum values | `copy`, `clone` | — for non-enum types |
| Category | Resource Usage / Disk | Upstream classification |
| Latest boot value | `copy` | copy |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG18 |
| Present in | PG18–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`f78ca6f3ebbb`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=f78ca6f3ebbbff8c675c34b8ee61047223073866) — Introduce file_copy_method setting. |
| Commit date | 2025-04-08 |
| Discussion | [thread 1](https://postgr.es/m/CA%2BhUKGLM%2Bt%2BSwBU-cHeMUXJCOgBxSHLGZutV5zCwY4qrCcE02w%40mail.gmail.com) |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG18–19 Beta 3 | `copy` | — | copy |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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 {#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. |
{.full-width}

## Pigsty {#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` |
{.full-width}

> [!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 {#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.

## Related parameters {#related-parameters}

[`file_extend_method`](/parameters/file-extend-method/) · [`data_directory`](/parameters/data-directory/) · [`temp_tablespaces`](/parameters/temp-tablespaces/) · [`shared_buffers`](/parameters/shared-buffers/)

## References {#references}

- [PostgreSQL 19 Beta 3 — file_copy_method](https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-FILE-COPY-METHOD)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)