feat(mssql-driver): Support use named timezones (cube-js#10582)

Add CUBEJS_DB_MSSQL_USE_NAMED_TIMEZONES env variable to enable
server-side DST-aware timezone conversion via AT TIME ZONE in MSSQL.

Previously, convertTz() computed a fixed UTC offset at query build time
using moment().tz().format('Z'), which didn't account for DST transitions
within the queried data range.

When enabled, IANA timezone names (e.g. 'America/New_York') are
automatically mapped to Windows timezone names (e.g. 'Eastern Standard
Time') required by MSSQL's AT TIME ZONE clause.

Defaults to false for backward compatibility..

Author: ovr

packages/cubejs-backend-shared/src/env.ts

@@ -1055,33 +1055,29 @@ const variables: Record<string, (...args: any) => any> = {
    * @see https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_convert-tz
    * @see https://dev.mysql.com/doc/refman/8.4/en/time-zone-support.html
    */
-  mysqlUseNamedTimezones: ({ dataSource }: { dataSource: string }) => {
-    const val = process.env[
-      keyByDataSource(
-        'CUBEJS_DB_MYSQL_USE_NAMED_TIMEZONES',
-        dataSource,
-      )
-    ];
+  mysqlUseNamedTimezones: ({ dataSource }: { dataSource: string }) => (
+    get(keyByDataSource('CUBEJS_DB_MYSQL_USE_NAMED_TIMEZONES', dataSource))
+      // It's true in schema-compiler integration tests
+      .default('false')
+      .asBool()
+  ),
 
-    if (val) {
-      if (val.toLocaleLowerCase() === 'true') {
-        return true;
-      } else if (val.toLowerCase() === 'false') {
-        return false;
-      } else {
-        throw new TypeError(
-          `The ${
-            keyByDataSource(
-              'CUBEJS_DB_MYSQL_USE_NAMED_TIMEZONES',
-              dataSource,
-            )
-          } must be either 'true' or 'false'.`
-        );
-      }
-    } else {
-      return false;
-    }
-  },
+  /** ****************************************************************
+   * MSSQL Driver                                                    *
+   ***************************************************************** */
+
+  /**
+   * Use named timezones for date/time conversions via AT TIME ZONE.
+   * Defaults to FALSE, meaning that numeric offsets for timezone will be used.
+   *
+   * @see https://learn.microsoft.com/en-us/sql/t-sql/queries/at-time-zone-transact-sql
+   */
+  mssqlUseNamedTimezones: ({ dataSource }: { dataSource: string }) => (
+    get(keyByDataSource('CUBEJS_DB_MSSQL_USE_NAMED_TIMEZONES', dataSource))
+      // It's true in schema-compiler integration tests
+      .default('false')
+      .asBool()
+  ),
 
   /** ****************************************************************
    * Databricks Driver                                               *

packages/cubejs-schema-compiler/src/adapter/MssqlQuery.ts

@@ -1,11 +1,12 @@
 import R from 'ramda';
 import moment from 'moment-timezone';
 
-import { QueryAlias, parseSqlInterval } from '@cubejs-backend/shared';
+import { getEnv, QueryAlias, parseSqlInterval } from '@cubejs-backend/shared';
 import { BaseQuery } from './BaseQuery';
 import { BaseFilter } from './BaseFilter';
 import { BaseSegment } from './BaseSegment';
 import { ParamAllocator } from './ParamAllocator';
+import { resolveWindowsTimezone } from './windows-iana';
 
 const abbrs = {
   EST: 'Eastern Standard Time',
@@ -73,6 +74,14 @@ class MssqlSegment extends BaseSegment {
 }
 
 export class MssqlQuery extends BaseQuery {
+  private readonly useNamedTimezones: boolean;
+
+  public constructor(compilers: any, options: any) {
+    super(compilers, options);
+
+    this.useNamedTimezones = getEnv('mssqlUseNamedTimezones', { dataSource: this.dataSource });
+  }
+
   public newFilter(filter) {
     return new MssqlFilter(this, filter);
   }
@@ -90,6 +99,11 @@ export class MssqlQuery extends BaseQuery {
   }
 
   public convertTz(field) {
+    if (this.useNamedTimezones) {
+      const windowsTz = resolveWindowsTimezone(this.timezone);
+      return `CAST(${field} AT TIME ZONE 'UTC' AT TIME ZONE '${windowsTz}' AS DATETIME2)`;
+    }
+
     const offset = moment().tz(this.timezone).format('Z');
 
     // 1. Treating the field as UTC (add '+00:00' offset)

packages/cubejs-schema-compiler/src/adapter/MysqlQuery.ts

@@ -45,6 +45,7 @@ export class MysqlQuery extends BaseQuery {
     if (this.useNamedTimezones) {
       return `CONVERT_TZ(${field}, @@session.time_zone, '${this.timezone}')`;
     }
+
     return `CONVERT_TZ(${field}, @@session.time_zone, '${moment().tz(this.timezone).format('Z')}')`;
   }