add mysqlUseNamedTimezones flag

Author: KSDaemon

docs/pages/reference/configuration/environment-variables.mdx

@@ -603,6 +603,16 @@ The cluster name to use when connecting to [Materialize](/product/configuration/
 | --------------------------------------------------------- | ---------------------- | --------------------- |
 | A valid Materialize cluster name                          | N/A                    | N/A                   |
 
+## `CUBEJS_DB_MYSQL_USE_NAMED_TIMEZONES`
+
+This flag controls how timezones are passed to CONVERT_TZ. If it is set to TRUE - timezone names will be used.
+IF it is set to FALSE - numeric offsets will be passed instead. To use named timezones, MySQL Server needs
+to be [configured][mysql-server-tz-support] properly.
+
+| Possible Values                       | Default in Development | Default in Production |
+| ------------------------------------- | ---------------------- | --------------------- |
+| Whether to use named timezones or not | `false`                | `false`               |
+
 ## `CUBEJS_DB_SNOWFLAKE_ACCOUNT`
 
 The Snowflake account identifier to use when connecting to the database.
@@ -1552,3 +1562,4 @@ The port for a Cube deployment to listen to API connections on.
 [ref-sql-api]: /product/apis-integrations/sql-api
 [ref-sql-api-streaming]: /product/apis-integrations/sql-api#streaming
 [ref-row-limit]: /product/apis-integrations/queries#row-limit
+[mysql-server-tz-support]: https://dev.mysql.com/doc/refman/8.4/en/time-zone-support.html

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

@@ -853,6 +853,44 @@ const variables: Record<string, (...args: any) => any> = {
     return undefined;
   },
 
+  /** ****************************************************************
+   * MySQL Driver                                                    *
+   ***************************************************************** */
+
+  /**
+   * Use timezone names for date/time conversions.
+   * Defaults to FALSE, meaning that numeric offsets for timezone will be used.
+   * @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,
+      )
+    ];
+
+    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;
+    }
+  },
+
   /** ****************************************************************
    * Databricks Driver                                               *
    ***************************************************************** */

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

@@ -1,7 +1,5 @@
 import moment from 'moment-timezone';
-
-import { parseSqlInterval } from '@cubejs-backend/shared';
-
+import { getEnv, parseSqlInterval } from '@cubejs-backend/shared';
 import { BaseQuery } from './BaseQuery';
 import { BaseFilter } from './BaseFilter';
 import { UserError } from '../compiler/UserError';
@@ -26,39 +24,50 @@ class MysqlFilter extends BaseFilter {
 }
 
 export class MysqlQuery extends BaseQuery {
+  private readonly useNamedTimezones: boolean;
+
+  public constructor(compilers: any, options: any) {
+    super(compilers, options);
+
+    this.useNamedTimezones = getEnv('mysqlUseNamedTimezones', { dataSource: this.dataSource });
+  }
+
   public newFilter(filter) {
     return new MysqlFilter(this, filter);
   }
 
-  public castToString(sql) {
+  public castToString(sql: string) {
     return `CAST(${sql} as CHAR)`;
   }
 
-  public convertTz(field) {
+  public convertTz(field: string) {
+    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')}')`;
   }
 
-  public timeStampCast(value) {
+  public timeStampCast(value: string) {
     return `TIMESTAMP(convert_tz(${value}, '+00:00', @@session.time_zone))`;
   }
 
   public timestampFormat() {
     return 'YYYY-MM-DDTHH:mm:ss.SSS';
   }
 
-  public dateTimeCast(value) {
+  public dateTimeCast(value: string) {
     return `TIMESTAMP(${value})`;
   }
 
-  public subtractInterval(date, interval) {
+  public subtractInterval(date: string, interval: string) {
     return `DATE_SUB(${date}, INTERVAL ${this.formatInterval(interval)})`;
   }
 
-  public addInterval(date, interval) {
+  public addInterval(date: string, interval: string) {
     return `DATE_ADD(${date}, INTERVAL ${this.formatInterval(interval)})`;
   }
 
-  public timeGroupedColumn(granularity, dimension) {
+  public timeGroupedColumn(granularity: string, dimension) {
     return `CAST(${GRANULARITY_TO_INTERVAL[granularity](dimension)} AS DATETIME)`;
   }