{"Entry":{"collection":"guc","key":"file_copy_method","name":"file_copy_method","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Resource Usage / Disk","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"17","status":"added","to":"18"}],"content_hash":"cafbe750dd0f470e3900d17615a8e715a1f023665b37aa78ef4f4989b6e50ab2","context":"","default_changed_in":[],"default_history":[{"from":"18","to":"19","value":"copy"}],"editorial":{"advice":{"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."},"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."],"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."],"references":[{"title":"PostgreSQL 19 Beta 4: file_copy_method","url":"https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-FILE-COPY-METHOD"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["file_extend_method","data_directory","temp_tablespaces","shared_buffers"],"summary":"file_copy_method — Selects the file copy method. Observed in PG18–19 Beta 4; its last measured boot default is copy in PG19 Beta 4, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"18","group":"Resource Usage","group_slug":"resource","imported_at":"2026-09-27T17:57:31.277961+08:00","intro_commit":{"authored_at":"2025-04-08T20:52:47+12:00","discussion":["https://postgr.es/m/CA%2BhUKGLM%2Bt%2BSwBU-cHeMUXJCOgBxSHLGZutV5zCwY4qrCcE02w%40mail.gmail.com"],"hash":"f78ca6f3ebbbff8c675c34b8ee61047223073866","subject":"Introduce file_copy_method setting.","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=f78ca6f3ebbbff8c675c34b8ee61047223073866"},"key":"file_copy_method","last_version":"20","max_val":"","min_val":"","name":"file_copy_method","position":147,"present_in":["18","19","20"],"short_desc":"Specifies the method used to copy files.","short_desc_zh":"","source_rev":"english-manuals:879eb246586cf1908faac8499f15b8454b6a8c884593cd47e053f5faceee2bf7","unit":"","vartype":"enum"}},"Definition":{"Collection":"guc","Key":"file_copy_method","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"file_copy_method","SourceRevision":"english-manuals:879eb246586cf1908faac8499f15b8454b6a8c884593cd47e053f5faceee2bf7","Facts":{"boot_val":"copy","category":"Resource Usage / Disk","context":"user","description":"Specifies the method used to copy files. Possible values are COPY (default) and CLONE (if operating support is available). This parameter affects: CREATE DATABASE ... STRATEGY=FILE_COPY ALTER DATABASE ... SET TABLESPACE ... 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.","doc":{"anchor":"GUC-FILE-COPY-METHOD","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"},"documented":true,"enumvals":["copy","clone"],"extra_desc":null,"lang":"en","max_val":null,"metadata_version":"18","min_val":null,"name":"file_copy_method","short_desc":"Selects the file copy method.","source":"pg-settings-source-snapshot","unit":null,"vartype":"enum"},"ManualEvidence":{"doc":{"anchor":"GUC-FILE-COPY-METHOD","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"file_copy_method","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"file_copy_method","Summary":"","BodyHTML":"\u003cp\u003e指定用于复制文件的方法。可能的值包括 \u003ccode\u003eCOPY\u003c/code\u003e（默认）和 \u003ccode\u003eCLONE\u003c/code\u003e（如果操作系统支持）。\u003c/p\u003e\u003cp\u003e此参数会影响：\u003c/p\u003e\u003cdiv\u003e\u003cul\u003e\u003cli\u003e\u003cp\u003e\u003ccode\u003e\u003ccode\u003eCREATE DATABASE ... STRATEGY=FILE_COPY\u003c/code\u003e\u003c/code\u003e\u003c/p\u003e\u003c/li\u003e\u003cli\u003e\u003cp\u003e\u003ccode\u003eALTER DATABASE ... SET TABLESPACE ...\u003c/code\u003e\u003c/p\u003e\u003c/li\u003e\u003c/ul\u003e\u003c/div\u003e\u003cp\u003e\u003ccode\u003eCLONE\u003c/code\u003e 使用 \u003ccode\u003ecopy_file_range()\u003c/code\u003e（Linux、FreeBSD）或 \u003ccode\u003ecopyfile\u003c/code\u003e（macOS）系统调用，使内核有机会在某些文件系统上共享磁盘块，或将工作交由更低层处理。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"3a3d6c6d95ffb757a695fedd654d0edd386502882b93aa452549cc68c7d0d03a","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e指定用于复制文件的方法。可能的值包括 \u003ccode class=\"literal\"\u003eCOPY\u003c/code\u003e（默认）和 \u003ccode class=\"literal\"\u003eCLONE\u003c/code\u003e（如果操作系统支持）。\u003c/p\u003e\u003cp\u003e此参数会影响：\u003c/p\u003e\u003cdiv class=\"itemizedlist\"\u003e\u003cul\u003e\u003cli\u003e\u003cp\u003e\u003ccode class=\"literal\"\u003e\u003ccode class=\"command\"\u003eCREATE DATABASE ... STRATEGY=FILE_COPY\u003c/code\u003e\u003c/code\u003e\u003c/p\u003e\u003c/li\u003e\u003cli\u003e\u003cp\u003e\u003ccode class=\"command\"\u003eALTER DATABASE ... SET TABLESPACE ...\u003c/code\u003e\u003c/p\u003e\u003c/li\u003e\u003c/ul\u003e\u003c/div\u003e\u003cp\u003e\u003ccode class=\"literal\"\u003eCLONE\u003c/code\u003e 使用 \u003ccode class=\"function\"\u003ecopy_file_range()\u003c/code\u003e（Linux、FreeBSD）或 \u003ccode class=\"function\"\u003ecopyfile\u003c/code\u003e（macOS）系统调用，使内核有机会在某些文件系统上共享磁盘块，或将工作交由更低层处理。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}