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 opcional de fuso horário. Se nenhum parâmetro de fuso horário for fornecido em uma função, os bancos de dados do Spanner usarão o fuso horário America/Los_Angeles por padrão.

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 conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

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

  • defina 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:

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 a ser definido como padrão do banco de dados. Precisa ser uma entrada válida do banco de dados de fuso horário da IANA. Por exemplo, Etc/UTC.

PostgreSQL

Use a instrução ALTER DATABASE:

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 a ser definido como padrão do banco de dados. Precisa ser uma entrada válida do banco de dados de fuso horário da IANA. Por exemplo, Etc/UTC.

Exemplos

Os exemplos de consultas 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.

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 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.

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 |
 *----------------------*/

Fuso horário padrão 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 padrão do banco 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 |
 *----------------------*/