timing_clock_source

Definition PG 20 devel manual

Selects the method for making timing measurements using the OS or specialized CPU instructions. Possible values are:

The default is auto. Only superusers can change this setting. Changing the setting during query execution is not recommended and may cause interval timings to jump significantly or produce negative values.

If enabled, the TSC clock source, named after the Time-Stamp Counter on x86-64, will use specialized CPU instructions when measuring time intervals. This lowers timing overhead compared to reading the OS system clock, and reduces the measurement error on top of the actual runtime, for example with EXPLAIN ANALYZE.

On x86-64 CPUs the TSC clock source utilizes the RDTSC instruction for EXPLAIN ANALYZE. For timings that require higher precision the RDTSCP instruction is used, which avoids inaccuracies due to CPU instruction re-ordering. Use of the TSC clock source is not supported on older x86-64 CPUs and other architectures, and is not advised on systems that utilize an emulated TSC, as it is likely slower than the system clock source.

To help decide which clock source to use you can run the pg_test_timing utility to check TSC availability, and perform timing measurements.

How it works

PostgreSQL describes timing_clock_source as follows: “Controls the clock source used for collecting timing measurements.” It can be changed at run time only by a superuser or a role with an appropriate SET grant. The atlas measures it in PG19 Beta 3; boot_val is the compiled or initialized baseline, not proof of a running cluster's effective setting.

auto selects a supported x86-64 Time-Stamp Counter when appropriate and otherwise uses the operating-system monotonic clock; system forces the OS clock and tsc requests CPU instructions such as RDTSC/RDTSCP. The faster source lowers EXPLAIN ANALYZE measurement overhead, but emulated or unstable TSC behavior can be slower or invalid.

Read it together with track_io_timing, track_wal_io_timing, log_executor_stats, compute_query_id. Check SHOW and pg_settings on the target server, verify the source and pending_restart fields, and compare workload, logs, and resource metrics before and after any change.

Operational considerations

Treating the measured boot_val for timing_clock_source as proof of the effective value on an initialized or managed cluster.

Applying a change as though it were immediate while pg_settings reports superuser context.

Changing this setting in isolation without checking the linked limits, observability, and rollback path.

Depending on beta behavior in production without retesting the PostgreSQL 19 final release.

Workload guidance

OLAP: Use representative scans, prefetch, and spill phases. Increase concurrency or worker capacity only while throughput rises without unacceptable CPU overhead, memory pressure, or storage saturation.

OLTP: Benchmark with the production storage stack and concurrency. Optimize tail latency and queue depth, not only average throughput, and retain capacity for WAL, checkpoints, and foreground reads.

SMALL: Prefer auto or the upstream worker limits. Validate with pg_test_timing or I/O statistics as applicable; a larger pool on a small node can add context switching without useful parallelism.