{"Entry":{"collection":"guc","key":"file_extend_method","name":"file_extend_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":"15","status":"added","to":"16"}],"content_hash":"b2851199cc58ffd9f4c0e6a96a2e9020d0701e9b874ca300a5d6adc7c42a337d","context":"","default_changed_in":[],"default_history":[{"from":"16","to":"19","value":"posix_fallocate"}],"derived_content_hash":"1b42357f4d95b4d6448ebcd6ca711f7bccf732428ac3b0138b60882f320cf75b","editorial":{"advice":{"olap":"Large allocations or bulk I/O can make file_extend_method visible, but platform capability is the first gate. Benchmark on production-equivalent storage and include failure/fallback behavior.","oltp":"Keep file_extend_method at the detected/default value unless operating-system support and a controlled benchmark justify a change. Validate startup and recovery on the exact kernel and file system.","small":"Avoid nondefault file_extend_method on a small or heterogeneous fleet unless it solves a verified platform issue. Portability and reliable startup usually outweigh a speculative gain."},"mechanism":["file_extend_method chooses how PostgreSQL grows relation files during bulk extension: posix_fallocate when available or explicit zero writes. Extensions of eight blocks or fewer still use zero writes.","The first supported method is platform dependent. posix_fallocate reserves space without writing every block, but unsupported file systems silently fall back; on current BTRFS it can disable compression for the file.","This affects allocation behavior and bulk-write latency, not WAL durability. Storage reservations, sparse-file behavior, compression, and copy-on-write semantics vary by file system. Its SIGHUP context allows configuration reload without a server restart."],"pitfalls":["Changing file_extend_method without applying its documented unit and configuration context.","Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.","Assuming a configured value guarantees operating-system or storage behavior.","Failing to retest startup, failover, and workload latency after the change."],"references":[{"title":"PostgreSQL 19 Beta 4: file_extend_method","url":"https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-FILE-EXTEND-METHOD"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["file_copy_method","backend_flush_after","checkpoint_flush_after","wal_sync_method"],"summary":"file_extend_method — Selects the method used for extending data files. Observed in PG16–19 Beta 4; its last measured boot default is posix_fallocate in PG19 Beta 4, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"16","group":"Resource Usage","group_slug":"resource","imported_at":"2026-09-27T17:57:31.281115+08:00","intro_commit":{"authored_at":"2025-05-31T22:50:22+12:00","discussion":["https://postgr.es/m/b1843124-fd22-e279-a31f-252dffb6fbf2%40gmx.net"],"hash":"e37b598028469d260650e5e1671c8275d30e22b6","subject":"Add file_extend_method=posix_fallocate,write_zeros.","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=e37b598028469d260650e5e1671c8275d30e22b6"},"key":"file_extend_method","last_version":"20","max_val":"","min_val":"","name":"file_extend_method","position":148,"present_in":["16","17","18","19","20"],"repair_provenance":{"original_source_revision":"english-manuals:2f88147edd7f32931a98e87b8f783b613ec595c739a5cc3b4f63358dc36c678b","receipt_sha256":"de88c09979fceba0172f53f062a75422d4a36a76f5fac3d2fcdf5b0494017957","repair":"wiki-repair-20261023"},"short_desc":"Specifies the method used to extend data files during bulk operations such as COPY.","short_desc_zh":"","source_rev":"wiki-repair-20261023:d10cf5d9b48a09f5d12c874e3aa08e063230e8bc41a233438feb34ad0be208de","unit":"","vartype":"enum"}},"Definition":{"Collection":"guc","Key":"file_extend_method","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"file_extend_method","SourceRevision":"wiki-repair-20261023:d10cf5d9b48a09f5d12c874e3aa08e063230e8bc41a233438feb34ad0be208de","Facts":{"boot_val":"posix_fallocate","category":"Resource Usage / Disk","context":"sighup","description":"Specifies the method used to extend data files during bulk operations such as COPY. The first available option is used as the default, depending on the operating system: posix_fallocate (Unix) uses the standard POSIX interface for allocating disk space, but is missing on some systems. If it is present but the underlying file system doesn't support it, this option silently falls back to write_zeros. Current versions of BTRFS are known to disable compression when this option is used. This is the default on systems that have the function. write_zeros extends files by writing out blocks of zero bytes. This is the default on systems that don't have the function posix_fallocate. The write_zeros method is always used when data files are extended by 8 blocks or fewer.","description_zh":"指定在诸如 COPY 这类批量操作期间扩展数据文件时所使用的方法。默认会根据操作系统选择第一个可用选项： posix_fallocate（Unix）使用标准 POSIX 接口分配磁盘空间，但某些系统缺少该接口。如果接口存在但底层文件系统不支持，本选项会静默回退到 write_zeros。已知当前版本的 BTRFS 在使用该选项时会禁用压缩。在提供该函数的系统上，这是默认值。 write_zeros 通过写入全零数据块来扩展文件。在不提供 posix_fallocate 函数的系统上，这是默认值。 当数据文件扩展的块数不超过 8 个时，总是使用 write_zeros 方法。","description_zh_html":"\u003cp\u003e\n        指定在诸如 \u003ccode class=\"command\"\u003eCOPY\u003c/code\u003e 这类批量操作期间扩展数据文件时所使用的方法。默认会根据操作系统选择第一个可用选项：\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\"\u003eposix_fallocate\u003c/code\u003e（Unix）使用标准 POSIX 接口分配磁盘空间，但某些系统缺少该接口。如果接口存在但底层文件系统不支持，本选项会静默回退到 \u003ccode class=\"literal\"\u003ewrite_zeros\u003c/code\u003e。已知当前版本的 BTRFS 在使用该选项时会禁用压缩。在提供该函数的系统上，这是默认值。\n          \u003c/p\u003e\u003c/li\u003e\u003cli class=\"listitem\"\u003e\u003cp\u003e\n\u003ccode class=\"literal\"\u003ewrite_zeros\u003c/code\u003e 通过写入全零数据块来扩展文件。在不提供 \u003ccode class=\"function\"\u003eposix_fallocate\u003c/code\u003e 函数的系统上，这是默认值。\n          \u003c/p\u003e\u003c/li\u003e\u003c/ul\u003e\u003c/div\u003e\u003cp\u003e\n        当数据文件扩展的块数不超过 8 个时，总是使用 \u003ccode class=\"literal\"\u003ewrite_zeros\u003c/code\u003e 方法。\n       \u003c/p\u003e","doc":{"anchor":"GUC-FILE-EXTEND-METHOD","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"},"documented":true,"enumvals":["posix_fallocate","write_zeros"],"extra_desc":null,"lang":"en","max_val":null,"metadata_version":"18","min_val":null,"name":"file_extend_method","short_desc":"Selects the method used for extending data files.","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-EXTEND-METHOD","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"file_extend_method","SourceDatabase":"center","Version":"18","Locale":"en","Title":"file_extend_method","Summary":"Specifies the method used to extend data files during bulk operations such as COPY. The first available option is used as the default, depending on the operating system: posix_fallocate (Unix) uses the standard POSIX interface for allocating disk space, but is missing on some systems. If it is present but the underlying file system doesn't support it, this option silently falls back to write_zeros. Current versions of BTRFS are known to disable compression when this option is used. This is the default on systems that have the function. write_zeros extends files by writing out blocks of zero bytes. This is the default on systems that don't have the function posix_fallocate. The write_zeros method is always used when data files are extended by 8 blocks or fewer.","BodyHTML":"\u003cp\u003eSpecifies the method used to extend data files during bulk operations such as COPY. The first available option is used as the default, depending on the operating system: posix_fallocate (Unix) uses the standard POSIX interface for allocating disk space, but is missing on some systems. If it is present but the underlying file system doesn\u0026#39;t support it, this option silently falls back to write_zeros. Current versions of BTRFS are known to disable compression when this option is used. This is the default on systems that have the function. write_zeros extends files by writing out blocks of zero bytes. This is the default on systems that don\u0026#39;t have the function posix_fallocate. The write_zeros method is always used when data files are extended by 8 blocks or fewer.\u003c/p\u003e","SourceRevision":"wiki-repair-20261023:d10cf5d9b48a09f5d12c874e3aa08e063230e8bc41a233438feb34ad0be208de","ContentHash":"58512fe1d445ca334533a378b513f5ad3bbf0e2fac4b7e8b1883cf7ddc3fab03","Payload":{"description":"Specifies the method used to extend data files during bulk operations such as COPY. The first available option is used as the default, depending on the operating system: posix_fallocate (Unix) uses the standard POSIX interface for allocating disk space, but is missing on some systems. If it is present but the underlying file system doesn't support it, this option silently falls back to write_zeros. Current versions of BTRFS are known to disable compression when this option is used. This is the default on systems that have the function. write_zeros extends files by writing out blocks of zero bytes. This is the default on systems that don't have the function posix_fallocate. The write_zeros method is always used when data files are extended by 8 blocks or fewer."}},"RequestedLocale":"en","Fallback":false,"Versions":["16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}