Definir o fuso horário padrão de um banco de dados

O Spanner oferece funções de data e carimbo de data/hora no GoogleSQL e no Cloud SQL para PostgreSQL. Algumas funções, como TIMESTAMP, dependem do fuso horário e aceitam um parâmetro de fuso horário opcional. Se nenhum parâmetro de fuso horário for fornecido em uma função, os bancos de dados do Spanner serão definidos como America/Los_Angeles.

O Spanner permite mudar o fuso horário padrão de um banco de dados para personalizar esse comportamento.

Limitações

  • Só é possível mudar o fuso horário de bancos de dados vazios sem tabelas.
  • Fornecer um parâmetro de fuso horário em uma instrução substitui o fuso horário padrão do banco de dados para essa instrução.
  • Todos os carimbos de data/hora nas APIs REST e RPC precisam usar UTC e terminar com um Z maiúsculo.
  • Os carimbos de data/hora nos resultados da consulta são apresentados de forma consistente em UTC, com Z anexado. As conversões de fuso horário de exibição não são realizadas.

Funções exigidas

Para receber as permissões necessárias para definir o fuso horário padrão de um banco de dados, peça ao administrador para conceder a você o papel do IAM de Administrador do banco de dados do Cloud Spanner (roles/spanner.databaseAdmin) no banco de dados. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para definir o fuso horário padrão de um banco de dados. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para definir o fuso horário padrão de um banco de dados:

  • Definir o fuso horário padrão de um banco de dados: spanner.databases.getDdl, spanner.databases.updateDdl

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Definir o fuso horário padrão

Para mudar o fuso horário padrão do banco de dados, execute a seguinte instrução:

GoogleSQL

Use a instrução ALTER DATABASE statement:

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

Substitua:

  • DATABASE-NAME: o nome do banco de dados. Por exemplo, my-database.
  • TIME-ZONE-NAME: o nome do fuso horário para definir o padrão do banco de dados. Precisa ser uma entrada válida do banco de dados IANA. Por exemplo, Etc/UTC.

PostgreSQL

Use a instrução ALTER DATABASE statement:

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

Substitua:

  • DATABASE-NAME: o nome do banco de dados. Por exemplo, my-database.
  • TIME-ZONE-NAME: o nome do fuso horário para definir o padrão do banco de dados. Precisa ser uma entrada válida do banco de dados IANA. Por exemplo, Etc/UTC.

Exemplos

As consultas de exemplo a seguir mostram como usar a opção de fuso horário padrão.

Fuso horário padrão não personalizado

Se a opção default_time_zone não estiver definida explicitamente no esquema do banco de dados, o valor de default_time_zone será nulo e o Spanner usará America/Los_Angeles como o fuso horário padrão. America/Los_Angeles tem um deslocamento de UTC-8 para carimbos de data/hora nos exemplos a seguir.

Afirmação:

GoogleSQL 

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

PostgreSQL 

SELECT '2072-12-25 15:30:00'::timestamptz AS timestamp_str;

Saída:

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

Afirmação:

GoogleSQL 

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

PostgreSQL 

SELECT EXTRACT(HOUR FROM '2072-12-25 15:30:00Z'::timestamptz) AS hour;

Saída:

/*------*
 | hour |
 +------+
 |  7   |
 *------*/

Afirmação:

GoogleSQL 

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

PostgreSQL 

SELECT DATE_TRUNC('day', TIMESTAMPTZ '2072-12-25 15:30:00Z') AS date_str;

Saída:

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

Opção de fuso horário padrão definida como Etc/UTC

Os exemplos a seguir mostram como as mesmas instruções se comportam quando a opção de fuso horário padrão é definida como Etc/UTC.

Afirmação:

GoogleSQL 

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

PostgreSQL 

SELECT '2072-12-25 15:30:00'::timestamptz AS timestamp_str;

Saída:

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

Afirmação:

GoogleSQL 

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

PostgreSQL 

SELECT EXTRACT(HOUR FROM '2072-12-25 15:30:00Z'::timestamptz) AS hour;

Saída:

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

Afirmação:

GoogleSQL 

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

PostgreSQL 

SELECT DATE_TRUNC('day', TIMESTAMPTZ '2072-12-25 15:30:00Z') AS date_str;

Saída:

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

Fuso horário padrão substituído pelo parâmetro de função

Quando uma função ou um literal de string inclui um parâmetro de fuso horário definido, o fuso horário padrão do banco de dados não é aplicado.

GoogleSQL

Afirmação:

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

Saída:

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

Afirmação:

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

Saída:

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

PostgreSQL

Afirmação:

SELECT '2072-12-25 15:30:00+11:00'::timestamptz AS timestamp_str;

Saída:

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