{"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"}],"derived_content_hash":"12ba5cb08a350aba1a95c2c6bfcff981cd76e0de5d9bb05325849dfb995bce3d","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"],"repair_provenance":{"original_source_revision":"english-manuals:879eb246586cf1908faac8499f15b8454b6a8c884593cd47e053f5faceee2bf7","receipt_sha256":"647c9ad94fd2f00676e4fc3ca934fd2cc79da1a9cefc3e536c3efc13a8e5e8d1","repair":"wiki-repair-20261023"},"short_desc":"Specifies the method used to copy files.","short_desc_zh":"","source_rev":"wiki-repair-20261023:4fc33312292c5bb2815dd6909c1c7967d3bf6ceae53308a099455fbe629ed00d","unit":"","vartype":"enum"}},"Definition":{"Collection":"guc","Key":"file_copy_method","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"file_copy_method","SourceRevision":"wiki-repair-20261023:4fc33312292c5bb2815dd6909c1c7967d3bf6ceae53308a099455fbe629ed00d","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.","description_zh":"指定用于复制文件的方法。可能的值包括 COPY（默认）和 CLONE（如果操作系统支持）。 此参数会影响： CREATE DATABASE ... STRATEGY=FILE_COPY ALTER DATABASE ... SET TABLESPACE ... CLONE 使用 copy_file_range()（Linux、FreeBSD）或 copyfile（macOS）系统调用，使内核有机会在某些文件系统上共享磁盘块，或将工作交由更低层处理。","description_zh_html":"\u003cp\u003e\n        指定用于复制文件的方法。可能的值包括 \u003ccode class=\"literal\"\u003eCOPY\u003c/code\u003e（默认）和\n        \u003ccode class=\"literal\"\u003eCLONE\u003c/code\u003e（如果操作系统支持）。\n       \u003c/p\u003e\u003cp\u003e\n        此参数会影响：\n       \u003c/p\u003e\u003cdiv class=\"itemizedlist\"\u003e\u003cul class=\"itemizedlist\" style=\"list-style-type: disc; \"\u003e\u003cli class=\"listitem\"\u003e\u003cp\u003e\n\u003ccode class=\"literal\"\u003e\u003ccode class=\"command\"\u003eCREATE DATABASE ... STRATEGY=FILE_COPY\u003c/code\u003e\u003c/code\u003e\n\u003c/p\u003e\u003c/li\u003e\u003cli class=\"listitem\"\u003e\u003cp\u003e\n\u003ccode class=\"command\"\u003eALTER DATABASE ... SET TABLESPACE ...\u003c/code\u003e\n\u003c/p\u003e\u003c/li\u003e\u003c/ul\u003e\u003c/div\u003e\u003cp\u003e\n\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）系统调用，使内核有机会在某些文件系统上共享磁盘块，或将工作交由更低层处理。\n       \u003c/p\u003e","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","translation_provenance":{"inputs":[{"kind":"current-pgdoc-translation","path":"/Users/vonng/pgsty/pgdoc/zh/18/html/runtime-config-resource.html","sha256":"f5fedbf88ec5f973aaf4e525c03e46dda2a2186dabee154e26780da96b2ac85a"}],"kind":"same-version-pgdoc","locale":"zh-Hans","source_revision":"b1b500221dbe5437cfca004d6b04d3f6e422765d","version":"18"},"unit":null,"vartype":"enum","zh_from":"same-version-pgdoc"},"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":"center","Version":"18","Locale":"en","Title":"file_copy_method","Summary":"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.","BodyHTML":"\u003cp\u003eSpecifies 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.\u003c/p\u003e","SourceRevision":"wiki-repair-20261023:4fc33312292c5bb2815dd6909c1c7967d3bf6ceae53308a099455fbe629ed00d","ContentHash":"1a01d4132cb60fd6cf1aa0828221d2ae7791f200171942661a2958a79967f656","Payload":{"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."}},"RequestedLocale":"en","Fallback":false,"Versions":["18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}