{"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"}],"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"],"short_desc":"Specifies the method used to extend data files during bulk operations such as COPY.","short_desc_zh":"","source_rev":"english-manuals:2f88147edd7f32931a98e87b8f783b613ec595c739a5cc3b4f63358dc36c678b","unit":"","vartype":"enum"}},"Definition":{"Collection":"guc","Key":"file_extend_method","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"file_extend_method","SourceRevision":"english-manuals:2f88147edd7f32931a98e87b8f783b613ec595c739a5cc3b4f63358dc36c678b","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.","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","unit":null,"vartype":"enum"},"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":"english-manuals:2f88147edd7f32931a98e87b8f783b613ec595c739a5cc3b4f63358dc36c678b","ContentHash":"44456d9db20859700f503193d66c2453c742e0cc36a8c78476e7c9dadfe7ff4a","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":"zh-Hans","Fallback":true,"Versions":["16","17","18","19","20"],"Locales":["en"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}