Parameter · Query Tuning / Planner Method Configuration
enable_async_append
Enables the planner's use of async append plans.
- Default:
on - Type: bool
- Applies: Session (any user)
In plain words
When a partitioned table has partitions on other servers (through postgres_fdw), PostgreSQL can send the remote queries at the same time and use whichever answer arrives first. That is an asynchronous Append. Turning this off makes it wait for each remote server in turn.
For DBAs and operators
Async Append only applies to child plans that can run asynchronously; in core PostgreSQL that means postgres_fdw foreign scans whose server or table has async_capable 'true' (it is off by default in the FDW). When both this parameter and the FDW option are on, EXPLAIN shows Async Foreign Scan nodes under the Append.
The executor starts every async-capable child, then waits on their sockets and returns rows from whichever child is ready, while local children run in the gaps. For a query that fans out to several shards this can turn the total latency from the sum of the remote latencies into roughly the maximum.
ALTER SERVER shard1 OPTIONS (ADD async_capable 'true');
EXPLAIN (VERBOSE, COSTS OFF) SELECT count(*) FROM orders_all;
-- Append
-- -> Async Foreign Scan on orders_shard1 …Limits from the postgres_fdw docs: it opens only one connection per foreign server (per user mapping), so partitions on the same server are still queried one after another; and when an Append mixes local and remote children, rows from the async children are returned only after at least one local child has finished. Reasons to turn it off: debugging a remote server, or measuring whether the async overhead pays off.
How to change it
Any user can change it for their session with SET.
See it in context
Related parameters
enable_parallel_append enable_partition_pruning enable_partitionwise_join