From c5e637a54c2b83e5bd8c4155784d97e82937eb51 Mon Sep 17 00:00:00 2001 From: Samay Sharma Date: Mon, 6 Feb 2023 16:09:42 -0800 Subject: [PATCH v9 2/5] Add data layout options sub-section in installation docs This commit separates out blocksize, segsize and wal_blocksize options into a separate Data layout options sub-section in both the make and meson docs. They were earlier in a miscellaneous section which included several unrelated options. This change also helps reduce the repetition of the warnings that changing these parameters breaks on-disk compatibility. --- doc/src/sgml/installation.sgml | 160 +++++++++++++++++++-------------- 1 file changed, 92 insertions(+), 68 deletions(-) diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index e3b9b6c0d0..7e65cdd72e 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1470,6 +1470,35 @@ build-postgresql: + + + + + + Data Layout + + + These options affect how PostgreSQL lays out data on disk. + Note that changing these breaks on-disk database compatibility, + meaning you cannot use these binaries with data directories + created with different values of these options. + + + + + + + + + Set the block size, in kilobytes. This is the unit + of storage and I/O within tables. The default, 8 kilobytes, + is suitable for most situations; but other values may be useful + in special cases. + The value must be a power of 2 between 1 and 32 (kilobytes). + + + + @@ -1488,25 +1517,6 @@ build-postgresql: also set limits on the usable file size. It is recommended, though not absolutely required, that this value be a power of 2. - Note that changing this value breaks on-disk database compatibility, - meaning you cannot use pg_upgrade to upgrade to - a build with a different segment size. - - - - - - - - - Set the block size, in kilobytes. This is the unit - of storage and I/O within tables. The default, 8 kilobytes, - is suitable for most situations; but other values may be useful - in special cases. - The value must be a power of 2 between 1 and 32 (kilobytes). - Note that changing this value breaks on-disk database compatibility, - meaning you cannot use pg_upgrade to upgrade to - a build with a different block size. @@ -1520,9 +1530,6 @@ build-postgresql: is suitable for most situations; but other values may be useful in special cases. The value must be a power of 2 between 1 and 64 (kilobytes). - Note that changing this value breaks on-disk database compatibility, - meaning you cannot use pg_upgrade to upgrade to - a build with a different WAL block size. @@ -2932,54 +2939,71 @@ ninja install - - - - - Set the segment size, in gigabytes. Large tables are - divided into multiple operating-system files, each of size equal - to the segment size. This avoids problems with file size limits - that exist on many platforms. The default segment size, 1 gigabyte, - is safe on all supported platforms. If your operating system has - largefile support (which most do, nowadays), you can use - a larger segment size. This can be helpful to reduce the number of - file descriptors consumed when working with very large tables. - But be careful not to select a value larger than is supported - by your platform and the file systems you intend to use. Other - tools you might wish to use, such as tar, could - also set limits on the usable file size. - It is recommended, though not absolutely required, that this value - be a power of 2. - - - + + - - - - - Set the block size, in kilobytes. This is the unit - of storage and I/O within tables. The default, 8 kilobytes, - is suitable for most situations; but other values may be useful - in special cases. - The value must be a power of 2 between 1 and 32 (kilobytes). - - - + + Data Layout + + + These options affect how PostgreSQL lays out data on disk. + Note that changing these breaks on-disk database compatibility, + meaning you cannot use these binaries with data directories + created with different values of these options. + + + + + + + + + Set the block size, in kilobytes. This is the unit + of storage and I/O within tables. The default, 8 kilobytes, + is suitable for most situations; but other values may be useful + in special cases. + The value must be a power of 2 between 1 and 32 (kilobytes). + + + + + + + + + Set the segment size, in gigabytes. Large tables are + divided into multiple operating-system files, each of size equal + to the segment size. This avoids problems with file size limits + that exist on many platforms. The default segment size, 1 gigabyte, + is safe on all supported platforms. If your operating system has + largefile support (which most do, nowadays), you can use + a larger segment size. This can be helpful to reduce the number of + file descriptors consumed when working with very large tables. + But be careful not to select a value larger than is supported + by your platform and the file systems you intend to use. Other + tools you might wish to use, such as tar, could + also set limits on the usable file size. + It is recommended, though not absolutely required, that this value + be a power of 2. + + + + + + + + + Set the WAL block size, in kilobytes. This is the unit + of storage and I/O within the WAL log. The default, 8 kilobytes, + is suitable for most situations; but other values may be useful + in special cases. + The value must be a power of 2 between 1 and 64 (kilobytes). + + + + + - - - - - Set the WAL block size, in kilobytes. This is the unit - of storage and I/O within the WAL log. The default, 8 kilobytes, - is suitable for most situations; but other values may be useful - in special cases. - The value must be a power of 2 between 1 and 64 (kilobytes). - - - - -- 2.38.1