Cómo establecer la zona horaria predeterminada de una base de datos

Spanner proporciona funciones de fecha y marca de tiempo en GoogleSQL y Cloud SQL para PostgreSQL. Algunas funciones, como TIMESTAMP, dependen de la zona horaria y aceptan un parámetro de zona horaria opcional. Si no se proporciona ningún parámetro de zona horaria en una función, las bases de datos de Spanner usan de forma predeterminada la zona horaria America/Los_Angeles.

Spanner te permite cambiar la zona horaria predeterminada de una base de datos para personalizar este comportamiento.

Limitaciones

  • Solo puedes cambiar la zona horaria de las bases de datos vacías que no tienen tablas.
  • Si se proporciona un parámetro de zona horaria en una instrucción, se anula la zona horaria predeterminada de la base de datos para esa instrucción.
  • Todas las marcas de tiempo en las APIs de REST y RPC deben usar UTC y terminar con una Z en mayúscula.
  • Las marcas de tiempo en los resultados de la búsqueda se presentan de forma coherente en UTC, con Z agregado. No se realizan conversiones de zona horaria de la pantalla.

Roles requeridos

Para obtener los permisos que necesitas para configurar la zona horaria predeterminada de una base de datos, pídele a tu administrador que te otorgue el rol de IAM Administrador de bases de datos de Cloud Spanner (roles/spanner.databaseAdmin) en la base de datos. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para establecer la zona horaria predeterminada de una base de datos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para establecer la zona horaria predeterminada de una base de datos:

  • Establece la zona horaria predeterminada de una base de datos: spanner.databases.getDdl, spanner.databases.updateDdl

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Cómo establecer la zona horaria predeterminada

Para cambiar la zona horaria predeterminada de tu base de datos, ejecuta la siguiente sentencia:

GoogleSQL

Usa la sentencia ALTER DATABASE:

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

Reemplaza lo siguiente:

  • DATABASE-NAME: Es el nombre de la base de datos. Por ejemplo, my-database
  • TIME-ZONE-NAME: Es el nombre de la zona horaria predeterminada de la base de datos. Debe ser una entrada válida de la base de datos de zonas horarias de IANA. Por ejemplo, Etc/UTC.

PostgreSQL

Usa la sentencia ALTER DATABASE:

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

Reemplaza lo siguiente:

  • DATABASE-NAME: Es el nombre de la base de datos. Por ejemplo, my-database
  • TIME-ZONE-NAME: Es el nombre de la zona horaria predeterminada de la base de datos. Debe ser una entrada válida de la base de datos de zonas horarias de IANA. Por ejemplo, Etc/UTC.

Ejemplos

En los siguientes ejemplos de consultas, se muestra cómo usar la opción de zona horaria predeterminada.

La zona horaria predeterminada no se personalizó

Si la opción default_time_zone no se configura de forma explícita en el esquema de la base de datos, el valor de default_time_zone será nulo y Spanner usará America/Los_Angeles como zona horaria predeterminada. America/Los_Angeles tiene un desplazamiento de UTC-8 para las marcas de tiempo en los siguientes ejemplos.

Declaración:

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

Resultado:

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

Declaración:

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

Resultado:

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

Declaración:

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

Resultado:

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

Opción de zona horaria predeterminada establecida en Etc/UTC

En los siguientes ejemplos, se muestra cómo se comportan las mismas instrucciones cuando la opción de zona horaria predeterminada se establece en Etc/UTC.

Declaración:

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

Resultado:

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

Declaración:

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

Resultado:

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

Declaración:

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

Resultado:

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

La zona horaria predeterminada se anula con el parámetro de la función

Cuando una función o un literal de cadena incluye un parámetro de zona horaria definido, no se aplica la zona horaria predeterminada de la base de datos.

Declaración:

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

Resultado:

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

Declaración:

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

Resultado:

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