# huge_page_size

> huge_page_size — The size of huge page that should be requested. Observed in PG14–19 Beta 3; its last measured boot default is 0 B in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
---

> [!NOTE]
> **Fact — official short description:** “The size of huge page that should be requested.”

## Identity {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `integer` | Upstream pg_settings type |
| Context | `postmaster` | Requires a server restart |
| Unit | `kB` | Raw unit |
| Range | `0` – `2147483647` | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Resource Usage / Memory | Upstream classification |
| Latest boot value | `0` | 0 B |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG14 |
| Present in | PG14–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`d2bddc2500fb`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=d2bddc2500fb74d56e5bc53a1cfa269e2e846510) — Add huge_page_size setting for use on Linux. |
| Commit date | 2020-07-17 |
| Discussion | [thread 1](https://postgr.es/m/20200608154639.20254-1-odin%40ugedal.com) |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG14–19 Beta 3 | `0` | `kB` | 0 B |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

huge_page_size selects the explicit huge-page size requested for PostgreSQL's main shared-memory area when huge_pages is used. Zero means the operating system's default huge-page size.

This is a startup allocation choice, not an amount of memory. Supported nonzero sizes are architecture and kernel dependent, and PostgreSQL currently supports nondefault selection only on Linux.

The requested page size must match provisioned huge-page pools and the shared-memory allocation. It affects the main shared area, not ordinary backend allocations such as work_mem. Its postmaster context fixes the value at server start; changing it requires a restart.

## Tuning advice {#tuning-advice}

> [!TIP]
> **Advice.** These are workload-specific starting points and must be validated with measurements.

| Workload | Guidance |
| --- | --- |
| OLTP | Keep 0 so PostgreSQL uses the system's default explicit huge-page size. Choose a nonzero size only on Linux after provisioning the matching huge-page pool and verifying startup plus huge_pages_status with the intended shared-memory footprint. |
| OLAP | A large main shared-memory region can make page-table savings material, but the useful size depends on architecture, kernel pools, fragmentation, and restart operations—not bulk-I/O throughput. Benchmark the exact host and preserve enough ordinary memory for backends and the OS. |
| Small nodes | Keep 0. A nondefault explicit size adds kernel provisioning and startup-failure risk that rarely pays back on a small shared-memory allocation. |
{.full-width}

## Pigsty {#pigsty}

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

| Template | Effective value | Versus upstream boot | Source expression |
| --- | --- | --- | --- |
| OLTP | Unmodified | — | — |
| OLAP | Unmodified | — | — |
| CRIT | Unmodified | — | — |
| TINY | Unmodified | — | — |
{.full-width}

> [!CAUTION]
> **Advice — pending human review.** Fact from the current Pigsty template projection: OLTP: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

## Common pitfalls {#common-pitfalls}

- Reading 0 as zero-byte huge pages rather than 'use the system default huge-page size'.
- Selecting a nonzero size on a non-Linux platform, where nondefault sizes are not supported.
- Requesting a page size whose kernel pool has not been provisioned and causing startup failure when huge_pages=on.
- Confusing explicit huge pages for the main shared-memory area with Transparent Huge Pages or per-backend memory.

## Related parameters {#related-parameters}

[`huge_pages`](/parameters/huge-pages/) · [`huge_pages_status`](/parameters/huge-pages-status/) · [`shared_buffers`](/parameters/shared-buffers/) · [`shared_memory_type`](/parameters/shared-memory-type/) · [`min_dynamic_shared_memory`](/parameters/min-dynamic-shared-memory/)

## References {#references}

- [PostgreSQL 19 Beta 3 — huge_page_size](https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-HUGE-PAGE-SIZE)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)