設定寬表串連時區 - Lindorm

寬表引擎2.7.6版本之前僅支援東八時區。 2.7.6版本之後，寬表引擎支援了跨時區特性。本文介紹如何設定當前串連的時區，以確保時間資料與您的期望一致。

背景資訊

目前Lindorm支援三種時間類型，其中TIMESTAMP類型和時區相關，DATE、TIME類型和時區不轉換。

資料類型	說明	時區特性
DATE	表示年月日，格式為`yyyy-mm-dd`，例如`2024-08-30`。	日期文字，不涉及時區。
TIME	表示時分秒，格式為`hh:mm:ss`，例如`08:11:15`。	時間字串，不涉及時區。
TIMESTAMP	表示年月日時分秒毫秒。格式有以下兩種： `yyyy-mm-dd hh:mm:ss.SSS`，例如`2024-08-30 08:11:15.354`，精確到毫秒。 epoch毫秒時間戳記，類型為長整型，例如`1724976675345`。	日期+時間字串，與時區相關，表示當前時區的時間+日期。長整型的毫秒時間戳記表示從UTC時區1970年1月1日00:00:00開始的毫秒數。

前提條件

寬表引擎為2.7.6及以上版本。如何查看或升級目前的版本，請參見寬表引擎版本說明和升級小版本。

重要

如果您的寬表引擎無法通過控制台升級至2.7.6及以上版本，請聯絡Lindorm支援人員（DingTalk號：s0s3eg3）。

使用限制

僅MySQL協議支援設定串連時區。MySQL協議串連方式，請參見使用MySQL協議（推薦）。

設定時區

重要

Lindorm預設時區為東八時區。
設定串連時區僅對當前串連生效。

您可以通過SET文法設定當前串連的時區，僅對當前串連生效。SET文法的詳細說明，請參見會話變數。

設定當前串連時區為UTC時區。
```
SET @@time_zone='UTC';
```
設定當前串連時區為+08:00時區。
```
SET @@time_zone='+08:00';
```
設定當前串連時區為上海時區（即上海的本地時間）。
```
SET @@time_zone='Asia/Shanghai';
```

查詢當前時區

SELECT @@time_zone;

樣本

MySQL命令列

通過MySQL命令列串連寬表引擎，請參見通過MySQL命令列串連寬表引擎。

假設表tb的結構、表中資料如下：

-- 建立表
CREATE TABLE tb(p1 int, c1 date, c2 time, c3 timestamp(3), PRIMARY KEY(p1));

-- 插入資料
UPSERT INTO tb(p1,c1,c2,c3) VALUES(1, '2024-08-30', '08:11:15', '2024-08-30 08:11:15.354');

您可以通過以下方式查看和修改串連時區。

查詢當前串連的時區。

SELECT @@time_zone;

返回結果：

+-------------+
| @@time_zone |
+-------------+
| +08:00      |
+-------------+

可以看到當前時區為東八區。

查看當前時區下的時間資料格式。

SELECT * FROM tb;

返回結果：

+------+------------+----------+-------------------------+
| p1   | c1         | c2       | c3                      |
+------+------------+----------+-------------------------+
|    1 | 2024-08-30 | 08:11:15 | 2024-08-30 08:11:15.354 |
+------+------------+----------+-------------------------+

修改當前串連時區為UTC。
```
SET @@time_zone='UTC';
```

驗證是否修改成功。

SELECT @@time_zone;

返回結果：

+-------------+
| @@time_zone |
+-------------+
| UTC         |
+-------------+

再次查看當前時區下的時間資料格式，驗證時區是否修改成功。

SELECT * FROM tb;

返回結果：

+------+------------+----------+-------------------------+
| p1   | c1         | c2       | c3                      |
+------+------------+----------+-------------------------+
|    1 | 2024-08-30 | 08:11:15 | 2024-08-30 00:11:15.354 |
+------+------------+----------+-------------------------+

可以看到DATE和DATE類型的c1、c2列由於與時區不轉換，因此資料格式無變化。TIMESTAMP類型的c3列中的資料已變為UTC時區下的日期時間。

Java

Java JDBC串連方式，請參見基於Java JDBC介面的應用開發。

當業務運行在非東八區時，建議您在串連串中添加參數forceConnectionTimeZoneToSession=true來設定串連時區。具體說明如下：

參數	樣本值	說明
connectionTimeZone	UTC	設定串連時區，預設為用戶端啟動並執行JVM時區（運行Java程式的虛擬機器所使用的預設時區）。如無特殊需要可以不設定。
forceConnectionTimeZoneToSession	true	將connectionTimeZone的值通過`set time_zone`語句設定到服務端。業務運行在非東八區時，建議添加該參數。

串連樣本

String url = "jdbc:mysql://ld-uf6k8yqb741t3****-proxy-sql-lindorm-public.lindorm.rds.aliyuncs.com:33060/" + database + "?sslMode=disabled&allowPublicKeyRetrieval=true&useServerPrepStmts=true&useLocalSessionState=true&rewriteBatchedStatements=true&cachePrepStmts=true&prepStmtCacheSize=100&prepStmtCacheSqlLimit=50000000&forceConnectionTimeZoneToSession=true";
Properties properties = new Properties();
properties.put("user", username);
properties.put("password", password);

//擷取串連
Connection connection = DriverManager.getConnection(url, properties);

Python

通過mysql-connector-python驅動串連寬表引擎，請參見基於Python的應用開發（mysql-connector-python）。

如果業務運行在UTC時區下，需要在串連串中添加time_zone參數來修改串連時區，使用方式：time_zone='UTC'。

參數	樣本值	說明
time_zone	`'UTC'`	建議設定為業務啟動並執行系統時區。系統將會通過`set time_zone`語句設定到服務端。

串連樣本：

connection = mysql.connector.connect(host='<MySQL相容地址>', port=33060, user='<使用者名稱>', passwd='<密碼>', database='<資料庫名>', time_zone='<時區>')

Go

通過Golang MySQL Driver驅動串連寬表引擎，請參見基於Go的應用開發。

如果業務運行在UTC時區下，需要在串連串中添加loc=Locall&time_zone=%27UTC%27。具體說明如下：

參數	樣本值	說明
parseTime	true	`parseTime=true`可以將DATE 和TIMESTAMP類型的資料輸出為`time.Time`類型。
loc	Local	設定解析 `time.Time` 類型時的時區，設定為`Local`表示使用系統時區。說明僅設定了`parseTime=true`時，該參數生效。
time_zone	%27UTC%27	設定為業務啟動並執行系統時區。

更多說明，請參見系統變數。

串連樣本：

urlString := fmt.Sprintf("%s:%s@tcp(%s:%d)/%s?timeout=%s&parseTime=true&loc=Local", user, password, host, port, database, connectTimeout)
timeZoneValue := url.QueryEscape("'UTC'")
urlString = urlString + "&time_zone=" + timeZoneValue
db, err := sql.Open("mysql", urlString)
if err != nil {
	panic(err.Error())
}