Defina o fuso horário predefinido de uma base de dados

O Spanner fornece funções de data e 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 não for fornecido nenhum parâmetro de fuso horário numa função, as bases de dados do Spanner usam como predefinição o fuso horário America/Los_Angeles.

O Spanner permite-lhe alterar o fuso horário predefinido de uma base de dados para personalizar este comportamento.

Limitações

  • Só pode alterar o fuso horário de bases de dados vazias sem tabelas.
  • A indicação de um parâmetro de fuso horário numa declaração substitui o fuso horário predefinido da base de dados para essa declaração.
  • Todas as indicações de tempo nas APIs REST e RPC têm de usar o fuso horário UTC e terminar com um Z em maiúsculas.
  • As datas/horas nos resultados da consulta são apresentadas de forma consistente em UTC, com Z anexado. Não são feitas conversões do fuso horário de apresentação.

Funções necessárias

Para receber as autorizações de que precisa para definir o fuso horário predefinido de uma base de dados, peça ao seu administrador para lhe conceder a função de IAM Administrador da base de dados do Cloud Spanner (roles/spanner.databaseAdmin) na base de dados. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para definir o fuso horário predefinido de uma base de dados. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para definir o fuso horário predefinido de uma base de dados:

  • defina o fuso horário predefinido de uma base de dados: spanner.databases.getDdl, spanner.databases.updateDdl

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Defina o fuso horário predefinido

Para alterar o fuso horário predefinido da sua base de dados, execute a seguinte declaração:

GoogleSQL

Use a declaração ALTER DATABASE:

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

Substitua o seguinte:

  • DATABASE-NAME: o nome da base de dados. Por exemplo, my-database.
  • TIME-ZONE-NAME: o nome do fuso horário para o qual a base de dados deve ser definida por predefinição. Tem de ser uma entrada válida da base de dados de fusos horários da IANA. Por exemplo, Etc/UTC.

PostgreSQL

Use a declaração ALTER DATABASE:

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

Substitua o seguinte:

  • DATABASE-NAME: o nome da base de dados. Por exemplo, my-database.
  • TIME-ZONE-NAME: o nome do fuso horário para o qual a base de dados deve ser definida por predefinição. Tem de ser uma entrada válida da base de dados de fusos horários da IANA. Por exemplo, Etc/UTC.

Exemplos

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

O fuso horário predefinido não está personalizado

Se a opção default_time_zone não estiver definida explicitamente no esquema da base de dados, o valor de default_time_zone é nulo e o Spanner usa America/Los_Angeles como o fuso horário predefinido. America/Los_Angeles tem uma diferença de UTC-8 para as datas/horas nos exemplos seguintes.

Declaração:

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

Saída:

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

Declaração:

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

Saída:

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

Declaração:

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

Saída:

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

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

Os exemplos seguintes mostram o comportamento das mesmas declarações quando a opção de fuso horário predefinido está definida como Etc/UTC.

Declaração:

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

Saída:

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

Declaração:

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

Saída:

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

Declaração:

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

Saída:

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

O fuso horário predefinido é substituído pelo parâmetro da função

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

Declaraçã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 |
 *--------------------------*/

Declaração:

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

Saída:

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