設定資料庫的預設時區

Spanner 在 GoogleSQL 和 PostgreSQL 適用的 Cloud SQL 中提供 date 和 timestamp 函式。部分函式 (例如 TIMESTAMP) 會受到時區影響，並接受選用的時區參數。如果函式中未提供時區參數，Spanner 資料庫會預設為 America/Los_Angeles 時區。

Spanner 可讓您變更資料庫的預設時區，自訂這項行為。

限制

• 只有在資料庫沒有任何資料表時，才能變更時區。
• 在陳述式中提供時區參數，即可為該陳述式覆寫資料庫的預設時區。
• REST 和 RPC API 中的所有時間戳記都必須使用世界標準時間，並以大寫 Z 結尾。
• 查詢結果中的時間戳記一律會以世界標準時間顯示，並附上 Z 。系統不會執行時區轉換。

必要的角色

如要取得設定資料庫預設時區所需的權限，請要求管理員授予您資料庫的 Cloud Spanner 資料庫管理員 (roles/spanner.databaseAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色具備設定資料庫預設時區所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：

所需權限

如要設定資料庫的預設時區，您必須具備下列權限：

• 設定資料庫的預設時區： spanner.databases.getDdl, spanner.databases.updateDdl

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

設定預設時區

如要變更資料庫的預設時區，請執行下列陳述式：

GoogleSQL

使用 ALTER DATABASE 陳述式：

ALTER DATABASE DATABASE-NAME SET OPTIONS (default_time_zone = 'TIME-ZONE-NAME');

更改下列內容：

• DATABASE-NAME：資料庫名稱。例如：my-database。
• TIME-ZONE-NAME：要設為資料庫預設時區的時區名稱。必須是 IANA 時區資料庫中的有效項目。例如：Etc/UTC。

PostgreSQL

使用 ALTER DATABASE 陳述式：

ALTER DATABASE DATABASE-NAME SET spanner.default_time_zone = 'TIME-ZONE-NAME';

更改下列內容：

• DATABASE-NAME：資料庫名稱。例如：my-database。
• TIME-ZONE-NAME：要設為資料庫預設時區的時區名稱。必須是 IANA 時區資料庫中的有效項目。例如：Etc/UTC。

範例

下列查詢範例說明如何使用預設時區選項。

未自訂預設時區

如果資料庫結構定義中未明確設定 default_time_zone 選項，則 default_time_zone 的值為空值，且 Spanner 會使用 America/Los_Angeles 做為預設時區。America/Los_Angeles 的時差為 UTC-8，以下範例中的時間戳記皆為此時區。

聲明：

SELECT TIMESTAMP("2072-12-25 15:30:00") AS timestamp_str;

輸出：

/*----------------------*
 | timestamp_str        |
 +----------------------+
 | 2072-12-25T23:30:00Z |
 *----------------------*/

聲明：

SELECT EXTRACT(HOUR FROM TIMESTAMP("2072-12-25 15:30:00")) AS hour;

輸出：

/*------*
 | hour |
 +------+
 | 23   |
 *------*/

聲明：

SELECT TIMESTAMP_TRUNC(TIMESTAMP "2072-12-25 15:30:00", DAY) AS date_str;

輸出：

/*----------------------*
 | date_str             |
 +----------------------+
 | 2072-12-25T08:00:00Z |
 *----------------------*/

預設時區選項設為「Etc/UTC」

下列範例顯示當預設時區選項設為 Etc/UTC 時，相同陳述式的行為。

聲明：

SELECT TIMESTAMP("2072-12-25 15:30:00") AS timestamp_str;

輸出：

/*----------------------*
 | timestamp_str        |
 +----------------------+
 | 2072-12-25T15:30:00Z |
 *----------------------*/

聲明：

SELECT EXTRACT(HOUR FROM TIMESTAMP("2072-12-25 15:30:00")) AS hour;

輸出：

/*------*
 | hour |
 +------+
 | 15   |
 *------*/

聲明：

SELECT TIMESTAMP_TRUNC(TIMESTAMP "2072-12-25 15:30:00+00", DAY) AS date_str;

輸出：

/*----------------------*
 | date_str             |
 +----------------------+
 | 2072-12-25T00:00:00Z |
 *----------------------*/

函式參數會覆寫預設時區

如果函式或字串常值包含已定義的時區參數，系統就不會套用資料庫的預設時區。

聲明：

SELECT FORMAT_TIMESTAMP("%c", TIMESTAMP "2050-12-25 15:30:55+00", "Australia/Sydney")
  AS formatted;

輸出：

/*--------------------------*
 | formatted                |
 +--------------------------+
 | Mon Dec 26 02:30:55 2050 |
 *--------------------------*/

聲明：

SELECT TIMESTAMP("2072-12-25 15:30:00+11:00") AS timestamp_str;

輸出：

/*----------------------*
 | timestamp_str        |
 +----------------------+
 | 2072-12-25T04:30:00Z |
 *----------------------*/