# huge_pages_status

> huge_pages_status indicates the status of huge pages. It is read-only metadata in PG17–18, not a runtime tuning control.
---

> [!NOTE]
> **Fact — official short description:** “Indicates the status of huge pages.”

## Identity {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `enum` | Upstream pg_settings type |
| Context | `internal` | Internal/preset and not user-settable |
| Unit | — | Raw unit |
| Range | — | Raw limits in the last observed version |
| Enum values | `off`, `on`, `unknown` | — for non-enum types |
| Category | Preset Options | Upstream classification |
| Latest boot value | `unknown` | unknown |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG17 |
| Present in | PG17–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`a14354cac0e3`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=a14354cac0e32d5e169c1ea4225845f93922d483) — Add GUC parameter "huge_pages_status" |
| Commit date | 2023-07-06 |
| Discussion | [thread 1](https://postgr.es/m/TU4PR8401MB1152EBB0D271F827E2E37A01EECC9@TU4PR8401MB1152.NAMPRD84.PROD.OUTLOOK.COM) |

## Default history {#default-history}

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

## How it works {#mechanism}

Reports whether the main shared-memory area actually uses explicit huge pages. It is an internal, read-only startup result with values off, on, or unknown.

The result is derived after applying huge_pages and attempting startup allocation against operating-system support and the available huge-page pool. It is not fixed by the PostgreSQL binary or initdb.

Use shared_memory_size_in_huge_pages to estimate the required pool and compare huge_pages_status with the requested huge_pages policy after every restart. Transparent Huge Pages are a separate operating-system mechanism.

## Tuning advice {#tuning-advice}

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

| Workload | Guidance |
| --- | --- |
| OLTP | Not tunable directly. If on was requested but status is off, check huge_pages policy, OS support, pool size, permissions, and startup logs; resize the OS pool before restarting. |
| OLAP | Large shared memory can need many huge pages. Reserve the pool with headroom for the real shared_memory_size and verify NUMA placement and restart behavior on each node. |
| Small nodes | Keep huge_pages=try unless the platform policy says otherwise. Do not reserve a large OS huge-page pool merely to make the status on for a small shared-memory area. |
{.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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

## Common pitfalls {#common-pitfalls}

- Trying to SET a read-only startup result.
- Confusing huge_pages_status with the configured huge_pages request.
- Ignoring a too-small operating-system huge-page pool or startup allocation failure.
- Confusing explicit PostgreSQL huge pages with Transparent Huge Pages.
- Assuming a status from one node applies to failover nodes with different OS configuration.

## Related parameters {#related-parameters}

[`huge_pages`](/parameters/huge-pages/) · [`shared_memory_size_in_huge_pages`](/parameters/shared-memory-size-in-huge-pages/) · [`shared_memory_size`](/parameters/shared-memory-size/) · [`shared_buffers`](/parameters/shared-buffers/) · [`min_dynamic_shared_memory`](/parameters/min-dynamic-shared-memory/) · [`dynamic_shared_memory_type`](/parameters/dynamic-shared-memory-type/)

## References {#references}

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