# temp_file_limit

> A per-process safety limit on disk space consumed at one time by executor temporary files.
---

> [!NOTE]
> **Fact — official short description:** “Limits the total size of all temporary files used by each process.”

## Identity {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `integer` | Upstream pg_settings type |
| Context | `superuser` | Settable at runtime by a superuser |
| Unit | `kB` | Raw unit |
| Range | `-1` – `2147483647` | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Resource Usage / Disk | Upstream classification |
| Latest boot value | `-1` | -1 kB |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG9.2 |
| Present in | PG9.2–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`23e5b16c71f2`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=23e5b16c71f2706978c5f54aabd28ed23a54b6a5) — Add temp_file_limit GUC parameter to constrain temporary file space usage. |
| Commit date | 2011-07-17 |
| Discussion | — |

## Default history {#default-history}

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

## How it works {#mechanism}

temp_file_limit limits the total instantaneous size of temporary files owned by one PostgreSQL process, including sort and hash spill files and storage for held cursors. Exceeding it cancels the transaction.

The limit is per process, not cluster-wide, so concurrent backends and parallel workers can collectively consume multiples of it. The default -1 means no limit.

Explicit temporary-table storage is excluded from this limit. log_temp_files and pg_stat_database.temp_bytes observe related temporary-file activity but do not change the enforcement boundary.

## Tuning advice {#tuning-advice}

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

| Workload | Guidance |
| --- | --- |
| OLTP | Use a finite guardrail sized from filesystem headroom and worst-case concurrent spillers. Monitor temp_bytes and log_temp_files so the cap blocks pathological queries rather than routine bursts. |
| OLAP | Allow a larger but still finite budget for known large joins and sorts, and coordinate it with query concurrency and parallelism. Test cancellation behavior before relying on the limit in production. |
| Small nodes | Choose a modest fraction of the data filesystem and preserve emergency free space. Pair a lower limit with conservative work_mem and query timeouts. |
{.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 | `5GB` | different | `{{ ([pg_size_twentieth, 200])\|min }}GB` |
| OLAP | `20GB` | different | `{{ ([pg_size_twentieth * 4, 2000])\|min }}GB` |
| CRIT | `5GB` | different | `{{ ([pg_size_twentieth, 200])\|min }}GB` |
| TINY | `5GB` | different | `{{ ([pg_size_twentieth, 200])\|min }}GB` |
{.full-width}

> [!CAUTION]
> **Advice — pending human review.** Fact from the current Pigsty template projection: OLTP: PG9.2–19 Beta 3 = 5GB (dcs); OLAP: PG9.2–19 Beta 3 = 20GB (dcs); CRIT: PG9.2–19 Beta 3 = 5GB (dcs); TINY: PG9.2–19 Beta 3 = 5GB (dcs). Advice, pending human review — Editorial inference: these values act as process-level circuit breakers while giving analytical spills more room; aggregate multi-process exposure still needs capacity review.

## Common pitfalls {#common-pitfalls}

- Treating a per-process limit as a cluster-wide disk cap.
- Expecting it to constrain explicit temporary tables, which are excluded.
- Leaving -1 on a filesystem where one runaway query can exhaust shared storage.
- Setting the cap below normal spill sizes and discovering through transaction cancellations.

## Related parameters {#related-parameters}

[`work_mem`](/parameters/work-mem/) · [`hash_mem_multiplier`](/parameters/hash-mem-multiplier/) · [`log_temp_files`](/parameters/log-temp-files/) · [`temp_tablespaces`](/parameters/temp-tablespaces/) · [`max_parallel_workers_per_gather`](/parameters/max-parallel-workers-per-gather/)

## References {#references}

- [PostgreSQL 19 Beta 3 — temp_file_limit](https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-TEMP-FILE-LIMIT)
- [PostgreSQL 18: pg_stat_database temp_bytes](https://www.postgresql.org/docs/18/monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW)
- [Pigsty: Parameter Optimization Policy](https://pigsty.io/docs/pgsql/template/tune/)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)