データベースのデフォルトのタイムゾーンを設定する

Spanner は、GoogleSQL と Cloud SQL for PostgreSQL で日付関数とタイムスタンプ関数を提供します。TIMESTAMP などの一部の関数はタイムゾーンに依存し、タイムゾーン パラメータ（省略可）を受け入れます。関数でタイムゾーン パラメータが指定されていない場合、Spanner データベースはデフォルトで America/Los_Angeles タイムゾーンになります。

Spanner では、データベースのデフォルトのタイムゾーンを変更して、この動作をカスタマイズできます。

制限事項

  • テーブルのない空のデータベースのタイムゾーンのみを変更できます。
  • ステートメント内でタイムゾーン パラメータを指定すると、そのステートメントに対してデータベースのデフォルトのタイムゾーンがオーバーライドされます。
  • REST API と RPC API のタイムスタンプはすべて UTC を使用し、大文字の Z で終わる必要があります。
  • クエリ結果のタイムスタンプは、Z が付加された UTC で常に表示されます。表示タイムゾーンの変換は行われません。

必要なロール

データベースのデフォルトのタイムゾーンを設定するために必要な権限を取得するには、データベースに対する 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 の値は null になり、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 |
 *----------------------*/