# timing_clock_source

> timing_clock_source — Controls the clock source used for collecting timing measurements. Observed in PG19 Beta 3; its last measured boot default is auto in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
---

> [!NOTE]
> **Fact — official short description:** “Controls the clock source used for collecting timing measurements.”

## Identity {#identity}

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

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG19 Beta 3 |
| Present in | PG19 Beta 3 |
| Removed in | No |
| Introduction commit | [`294520c44487`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=294520c44487ecaade7a6ea8781b973f9ed03909) — instrumentation: Use Time-Stamp Counter on x86-64 to lower overhead |
| Commit date | 2026-04-07 |
| Discussion | [thread 1](https://postgr.es/m/20200612232810.f46nbqkdhbutzqdg@alap3.anarazel.de) |

## Default history {#default-history}

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

## How it works {#mechanism}

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.

## Tuning advice {#tuning-advice}

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

| Workload | Guidance |
| --- | --- |
| 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. |
| 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. |
| Small nodes | 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. |
{.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: PG19 Beta 3 unmodified; OLAP: PG19 Beta 3 unmodified; CRIT: PG19 Beta 3 unmodified; TINY: PG19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

## Common pitfalls {#common-pitfalls}

- 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.

## Related parameters {#related-parameters}

[`track_io_timing`](/parameters/track-io-timing/) · [`track_wal_io_timing`](/parameters/track-wal-io-timing/) · [`log_executor_stats`](/parameters/log-executor-stats/) · [`compute_query_id`](/parameters/compute-query-id/)

## References {#references}

- [PostgreSQL 19 Beta 3 — timing_clock_source](https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-TIMING-CLOCK-SOURCE)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)