# io_method

> io_method — Selects the method for executing asynchronous I/O. Observed in PG18–19 Beta 3; its last measured boot default is worker 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:** “Selects the method for executing asynchronous I/O.”

## Identity {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `enum` | Upstream pg_settings type |
| Context | `postmaster` | Requires a server restart |
| Unit | — | Raw unit |
| Range | — | Raw limits in the last observed version |
| Enum values | `sync`, `worker`, `io_uring` | — for non-enum types |
| Category | Resource Usage / I/O | Upstream classification |
| Latest boot value | `worker` | worker |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG18 |
| Present in | PG18–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`02844012b304`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=02844012b304ba80d1c48d51f6fe10bb622490cc) — aio: Basic subsystem initialization |
| Commit date | 2025-03-17 |
| Discussion | [thread 1](https://postgr.es/m/uvrtrknj4kdytuboidbhwclo4gxhswwcpgadptsjvjqcluzmah%40brqs62irg4dt) |

## Default history {#default-history}

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

## How it works {#mechanism}

worker sends eligible I/O through dedicated I/O worker processes; io_uring uses Linux io_uring and requires a build with liburing support; sync performs asynchronous-eligible operations synchronously. The upstream default is worker.

The PG18 AIO subsystem allows backends to queue multiple reads and can improve sequential scans, bitmap heap scans, vacuum, and other supported operations. It does not make every PostgreSQL I/O path asynchronous.

io_workers matters only when worker is selected. io_max_concurrency and the I/O combine limits control different dimensions of queue depth and request size, so method selection should be evaluated with them and with the storage stack.

## Tuning advice {#tuning-advice}

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

| Workload | Guidance |
| --- | --- |
| OLTP | Use worker as the compatibility baseline. Test io_uring only on a verified build and kernel, and keep it only if representative concurrent latency improves without destabilizing the storage queue. |
| OLAP | Sequential and bitmap-heavy analytical workloads are promising AIO candidates. Benchmark worker and io_uring with realistic scan concurrency, not just a single cold scan. |
| Small nodes | Worker is a safe default; sync can be a diagnostic fallback when worker overhead or platform constraints matter. Avoid spending scarce processes on excessive io_workers. |
{.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 | `worker` | same as boot | `{{ pg_effective_io_method }}` |
| OLAP | `worker` | same as boot | `{{ pg_effective_io_method }}` |
| CRIT | `worker` | same as boot | `{{ pg_effective_io_method }}` |
| TINY | `worker` | same as boot | `{{ pg_effective_io_method }}` |
{.full-width}

> [!CAUTION]
> **Advice — pending human review.** Fact from the current Pigsty template projection: OLTP: PG18–19 Beta 3 = worker (dcs); OLAP: PG18–19 Beta 3 = worker (dcs); CRIT: PG18–19 Beta 3 = worker (dcs); TINY: PG18–19 Beta 3 = worker (dcs). Advice, pending human review — Editorial hypothesis, pending maintainer review: Pigsty selects the portable PG18 AIO baseline while leaving io_uring as an explicit operator choice.

## Common pitfalls {#common-pitfalls}

- The parameter does not exist before PostgreSQL 18.
- Changing it requires a server restart.
- io_uring requires operating-system and build support; the enum value alone does not provide that support.
- io_workers has no effect unless io_method=worker.
- AIO benefits only eligible paths and cannot compensate for an overloaded or poorly configured storage layer.

## Related parameters {#related-parameters}

[`io_workers`](/parameters/io-workers/) · [`io_max_concurrency`](/parameters/io-max-concurrency/) · [`io_combine_limit`](/parameters/io-combine-limit/) · [`io_max_combine_limit`](/parameters/io-max-combine-limit/) · [`effective_io_concurrency`](/parameters/effective-io-concurrency/) · [`maintenance_io_concurrency`](/parameters/maintenance-io-concurrency/)

## References {#references}

- [PostgreSQL 19 Beta 3 — io_method](https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-IO-METHOD)
- [PostgreSQL 18 release notes: asynchronous I/O subsystem](https://www.postgresql.org/docs/18/release-18.html)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)