Vitess time_zone session delegation lacks a cluster-wide normalization boundary

Question

In current Vitess releases, Vitess forwards session variables such as SET time_zone directly to the underlying MySQL shard, so the effective time zone is determined by each shard's server configuration rather than by Vitess itself. When shards run with different system time zones or MySQL time-zone tables, the same logical query can return different timestamp values depending on which shard executes it.

There is no documented Vitess routing-layer setting that forces a single global time zone or automatically translates timestamps between shards in different zones. It is unresolved whether Vitess should intercept and normalize time_zone session state across shards, or continue delegating entirely to MySQL; this remains an implementation detail without a unified configuration contract.

Because MySQL time-zone tables are optional, a shard may fall back to the system zone, leading to daylight-saving-time mismatches when shards run in different local zones. Applications that store and compare UTC timestamps avoid the inconsistency, while applications relying on local timestamps or date arithmetic across shards may observe divergent results.

Should Vitess introduce a VTGate-level configuration to normalize time_zone session state before routing, or is per-shard configuration the intended boundary? If normalization is absent, what is the supported contract for applications requiring consistent cross-shard timestamp semantics without rewriting queries to UTC? How should daylight-saving transitions be handled when shards maintain independent time-zone tables?

Tasadduq Burney · Answer

Short answer
Do not rely on VTGate as a cluster-wide time_zone normalization boundary. In current Vitess behavior, the supported boundary is per-shard MySQL configuration plus an explicit application-level session or UTC contract. A VTGate-level normalizer would be a new feature, not a documented setting; verify your exact Vitess release before designing around one.
Established behavior vs likely explanation
Established behavior: Vitess forwards SET time_zone to the MySQL connection used for the query. MySQL then applies that session zone to TIMESTAMP conversion and functions such as NOW() and CURDATE(); DATETIME values are not converted. Named zones require populated MySQL time-zone tables; otherwise named-zone support can be missing and the server may fall back to the system zone.
Likely explanation for divergent results: shards differ in OS tzdata, MySQL time-zone tables, or global/session zone settings. Connection pooling and resharding can also change which shard or pooled connection serves a query, so session state must be re-established or verified per connection. Vitess does not rewrite result timestamps between shard zones; it is a routing/proxy layer, not a value translator.
Supported contract

RequirementSupported approach

Same local zone on every shardMake shards operationally identical: same MySQL version, time-zone tables/tzdata, global zone, and system zone. Have the application run SET SESSION time_zone to the same fixed zone after connecting.
Heterogeneous shardsThere is no supported local-zone contract. Store and compare UTC timestamps, then convert to local zones at the presentation layer.
DST correctnessUse named zones only when every shard has identical time-zone tables. Otherwise use UTC or a fixed numeric offset, accepting that fixed offsets are not DST-aware.

If you truly cannot rewrite queries to UTC, the only supported alternative is identical shard configuration plus an explicit session zone. Otherwise, cross-shard local-time semantics are not reliable.
Verify before changing anything

On each shard, run this read-only check at the same instant and compare results:

SELECT @@global.time_zone, @@session.time_zone, @@system_time_zone, NOW(), UTC_TIMESTAMP();

Check named-zone support with a session-scoped test on one connection per shard, replacing UTC with the zone you intend to use:

SET SESSION time_zone = 'UTC';
SELECT @@session.time_zone;

Run the same cross-shard query returning a known TIMESTAMP or DATETIME row from each shard and compare values, ideally around a DST boundary.
Confirm against your exact Vitess release and configuration that no VTGate flag exists for time_zone normalization.

The one diagnostic that changes the recommendation: do all shards report identical @@global.time_zone, @@system_time_zone, and named-zone support? If yes, investigate client/session handling. If no, normalize shard configuration first and do not add VTGate translation.

Vitess time_zone session delegation lacks a cluster-wide normalization boundary

1 answer

Short answer

Established behavior vs likely explanation

Supported contract

Verify before changing anything

Your perspective belongs here.

0 question comments

Requirement	Supported approach
Same local zone on every shard	Make shards operationally identical: same MySQL version, time-zone tables/tzdata, global zone, and system zone. Have the application run `SET SESSION time_zone` to the same fixed zone after connecting.
Heterogeneous shards	There is no supported local-zone contract. Store and compare UTC timestamps, then convert to local zones at the presentation layer.
DST correctness	Use named zones only when every shard has identical time-zone tables. Otherwise use UTC or a fixed numeric offset, accepting that fixed offsets are not DST-aware.