Cómo crear y administrar flujos de cambios

En esta página, se describe cómo crear, modificar y ver los flujos de cambios de Spanner. Para obtener más información sobre los flujos de cambios, consulta Acerca de los flujos de cambios.

Debido a que los flujos de cambios son objetos de esquema, los creas y administras a través de las mismas actualizaciones de esquema basadas en DDL que se usan para cualquier otro tipo de trabajo de definición de bases de datos, como crear tablas o agregar índices.

Spanner inicia una operación de larga duración después de que envíes una declaración DDL de cambio de esquema, incluidas las que se usan para crear, modificar o borrar flujos de cambios. Un flujo de cambios nuevo o modificado comenzará a observar las columnas o tablas especificadas por su nueva configuración una vez que se complete esta operación de larga duración.

Crear transmisión de cambios

Para crear un flujo de cambios, debes proporcionar su nombre y los objetos de esquema que observará: toda la base de datos o una lista de tablas y columnas específicas. De manera opcional, puedes especificar lo siguiente:

GoogleSQL

La sintaxis de DDL para crear un flujo de cambios con GoogleSQL se ve de la siguiente manera:

CREATE CHANGE STREAM change_stream_name
  [FOR column_or_table_watching_definition[, ... ] ]
  [
    OPTIONS (
      retention_period = timespan,
      value_capture_type = type,
      exclude_ttl_deletes = boolean,
      exclude_insert = boolean,
      exclude_update = boolean,
      exclude_delete = boolean
    )
  ]

PostgreSQL

La sintaxis de DDL para crear un flujo de cambios con PostgreSQL se ve de la siguiente manera:

CREATE CHANGE STREAM change_stream_name
  [FOR column_or_table_watching_definition[, ... ] ]
  [
    WITH (
      retention_period = timespan,
      value_capture_type = type,
      exclude_ttl_deletes = boolean,
      exclude_insert = boolean,
      exclude_update = boolean,
      exclude_delete = boolean
    )
  ]

Una transmisión de cambios nueva comienza a observar sus objetos de esquema asignados en cuanto se completa la operación de larga duración que la creó.

En los siguientes ejemplos, se ilustra la creación de flujos de cambios con varias configuraciones.

Observa una base de datos completa

Para crear un flujo de cambios que observe todos los cambios en los datos realizados en las tablas de una base de datos, usa la palabra clave ALL:

CREATE CHANGE STREAM EverythingStream
FOR ALL;

La configuración de ALL incluye de forma implícita todas las tablas y columnas de datos futuras de la base de datos en cuanto se crean. No incluye vistas, tablas de esquema de información ni otros objetos además de tablas de datos normales.

Observa tablas específicas

Para limitar el alcance de un flujo de cambios a tablas específicas, en lugar de una base de datos completa, especifica una lista de una o más tablas:

CREATE CHANGE STREAM SingerAlbumStream
FOR Singers, Albums;

Spanner actualiza automáticamente los flujos de cambios que supervisan tablas completas para reflejar los cambios de esquema que afectan a esas tablas, como columnas agregadas o descartadas.

Consultar columnas específicas

Usa la sintaxis table(column_1[, column_2, ...]) para observar los cambios en una o más columnas específicas y sin clave dentro de las tablas a las que nombras:

CREATE CHANGE STREAM NamesAndTitles
FOR Singers(FirstName, LastName), Albums(Title);

No puedes especificar columnas de clave primaria aquí porque cada flujo de cambios siempre realiza un seguimiento de las claves primarias de cada tabla que supervisa. Esto permite que cada registro de cambios en los datos identifique la fila modificada por su clave primaria.

Observa tablas y columnas en una sola transmisión

Puedes combinar la sintaxis de observación de tablas y de observación de columnas de los dos ejemplos anteriores en un solo flujo de cambios:

CREATE CHANGE STREAM NamesAndAlbums
FOR Singers(FirstName, LastName), Albums;

Especifica un período de retención más largo

Para especificar un período de retención de datos del flujo de cambios mayor que el predeterminado de un día, establece retention_period en un período de hasta una semana, expresado como horas (h) o días (d).

Dos ejemplos:

GoogleSQL 

CREATE CHANGE STREAM LongerDataRetention
FOR ALL
OPTIONS ( retention_period = '36h' );

CREATE CHANGE STREAM MaximumDataRetention
FOR ALL
OPTIONS ( retention_period = '7d' );

PostgreSQL 

CREATE CHANGE STREAM LongerDataRetention
FOR ALL
WITH ( retention_period = '36h' );

CREATE CHANGE STREAM MaximumDataRetention
FOR ALL
WITH ( retention_period = '7d' );

Cómo especificar un tipo de captura de valor diferente

Para especificar un tipo de captura de valor del flujo de cambios que no sea OLD_AND_NEW_VALUES, establece value_capture_type en NEW_VALUES o NEW_ROW, como se muestra en los siguientes ejemplos:

GoogleSQL 

CREATE CHANGE STREAM NewRowChangeStream
FOR ALL
OPTIONS ( value_capture_type = 'NEW_ROW' );

CREATE CHANGE STREAM NewValuesChangeStream
FOR ALL
OPTIONS ( value_capture_type = 'NEW_VALUES' );

PostgreSQL 

CREATE CHANGE STREAM NewRowChangeStream
FOR ALL
WITH ( value_capture_type = 'NEW_ROW' );

CREATE CHANGE STREAM NewValuesChangeStream
FOR ALL
WITH ( value_capture_type = 'NEW_VALUES' );

Filtrar eliminaciones basadas en el TTL

Puedes filtrar las eliminaciones basadas en TTL del alcance de tu flujo de cambios con el filtro exclude_ttl_deletes.

Para obtener más información sobre cómo funciona este filtro, consulta Filtro de eliminaciones basadas en el tiempo de actividad.

GoogleSQL

Para crear un flujo de cambios con el filtro de eliminaciones basado en el TTL, usa lo siguiente:

CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
OPTIONS (exclude_ttl_deletes = true)

Reemplaza lo siguiente:

  • CHANGE_STREAM_NAME: Es el nombre del flujo de cambios nuevo.

En el siguiente ejemplo, se crea un flujo de cambios llamado NewFilterChangeStream que excluye todas las eliminaciones basadas en el TTL:

CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
OPTIONS (exclude_ttl_deletes = true)

PostgreSQL

Para crear un flujo de cambios con el filtro de eliminaciones basado en el TTL, usa lo siguiente:

CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
WITH (exclude_ttl_deletes = true)

Reemplaza lo siguiente:

  • STREAM_NAME: Es el nombre del flujo de cambios nuevo.

En el siguiente ejemplo, se crea un flujo de cambios llamado NewFilterChangeStream que excluye todas las eliminaciones basadas en el TTL:

CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
WITH (exclude_ttl_deletes = true)

Para agregar o quitar el filtro de eliminaciones basadas en el TTL de un flujo de cambios existente, consulta Modifica el filtro de eliminaciones basadas en el TTL. Para confirmar tus filtros de flujo de cambios, consulta las definiciones del flujo de cambios como DDL.

Filtrar por tipo de modificación de tabla

Filtra una o más de estas modificaciones de tabla del alcance de tu flujo de cambios mediante las siguientes opciones de filtro disponibles:

  • exclude_insert: Excluye todas las modificaciones de la tabla INSERT
  • exclude_update: Excluye todas las modificaciones de la tabla UPDATE
  • exclude_delete: Excluye todas las modificaciones de la tabla DELETE

Para obtener más información sobre cómo funcionan estos filtros, consulta Filtros de tipo de modificación de tabla.

GoogleSQL

Para crear un flujo de cambios con uno o más filtros de tipo de modificación de tabla, usa lo siguiente:

CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
OPTIONS (MOD_TYPE_FILTER_NAME = true)

Reemplaza lo siguiente:

  • CHANGE_STREAM_NAME: Es el nombre del flujo de cambios nuevo.
  • MOD_TYPE_FILTER_NAME: Es el filtro que deseas agregar: exclude_insert, exclude_update o exclude_delete. Si agregas más de un filtro a la vez, separa cada uno con una coma.

En el siguiente ejemplo, se crea un flujo de cambios llamado NewFilterChangeStream que excluye los tipos de modificación de tabla INSERT y UPDATE:

CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
OPTIONS (exclude_insert = true, exclude_update = true)

PostgreSQL

Para crear un flujo de cambios con uno o más filtros de tipo de modificación de tabla, usa lo siguiente:

CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
WITH (MOD_TYPE_FILTER_NAME = true)

Reemplaza lo siguiente:

  • CHANGE_STREAM_NAME: Es el nombre del flujo de cambios existente.
  • MOD_TYPE_FILTER_NAME: Es el filtro que deseas agregar: exclude_insert, exclude_update o exclude_delete. Si agregas más de un filtro a la vez, separa cada uno con una coma.

En el siguiente ejemplo, se crea un flujo de cambios llamado NewFilterChangeStream que excluye los tipos de transacciones de modificación de tablas INSERT y UPDATE:

CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
WITH (exclude_insert = true, exclude_update = true)

Para agregar o quitar un filtro de tipo de modificación de tabla de un flujo de cambios existente, consulta Modifica el filtro por tipo de modificación de tabla. Si deseas confirmar qué filtros de tipo de modificación de tabla existen para tu flujo de cambios, consulta las definiciones del flujo de cambios como DDL.

Cómo modificar un flujo de cambios

Para modificar la configuración de un flujo de cambios, usa una declaración DDL ALTER CHANGE STREAM. Usa una sintaxis similar a CREATE CHANGE STREAM. Puedes cambiar qué columnas supervisa una transmisión o la duración de su período de retención de datos. También puedes suspender la supervisión por completo mientras conservas sus registros de cambios de datos.

Cómo modificar lo que mira un flujo de cambios

En este ejemplo, se agrega toda la tabla Songs al flujo de cambios NamesAndAlbums configurado antes:

ALTER CHANGE STREAM NamesAndAlbums
SET FOR Singers(FirstName, LastName), Albums, Songs;

Spanner reemplaza el comportamiento del flujo de cambios con nombre por la configuración nueva cuando se completa la operación de larga duración que actualiza la definición del flujo de cambios dentro del esquema de la base de datos.

Modifica el período de retención de datos de un flujo de cambios

Para modificar el período por el que una transmisión de cambios retiene sus registros internos, configura retention_period en una declaración DDL ALTER CHANGE STREAM.

En este ejemplo, se ajusta el período de retención de datos al flujo de cambios NamesAndAlbums que se creó antes:

GoogleSQL 

ALTER CHANGE STREAM NamesAndAlbums
SET OPTIONS ( retention_period = '36h' );

PostgreSQL 

ALTER CHANGE STREAM NamesAndAlbums
SET ( retention_period = '36h' );

Modifica el tipo de captura de valores de un flujo de cambios

Para modificar el tipo de captura de valores de un flujo de cambios, configura la cláusula value_capture_type en una declaración DDL ALTER CHANGE STREAM.

En este ejemplo, se ajusta el tipo de captura de valor a NEW_VALUES.

GoogleSQL 

ALTER CHANGE STREAM NamesAndAlbums
SET OPTIONS ( value_capture_type = 'NEW_VALUES' );

PostgreSQL 

ALTER CHANGE STREAM NamesAndAlbums
SET ( value_capture_type = 'NEW_VALUES' );

Modificar filtro de eliminaciones basadas en el TTL

Si deseas modificar el filtro de eliminaciones basadas en TTL para un flujo de cambios, configura el filtro exclude_ttl_deletes en una declaración DDL ALTER CHANGE STREAM. Puedes usar esto para agregar o quitar el filtro de los flujos de cambios existentes.

Para obtener más información sobre cómo funcionan estos filtros, consulta Filtro de eliminaciones basadas en el tiempo de actividad.

Agrega el filtro de eliminaciones basado en el TTL a un flujo de cambios existente

GoogleSQL

Si deseas agregar el filtro de eliminaciones basado en el TTL a un flujo de cambios existente, usa lo siguiente para establecer el filtro en true:

ALTER CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
SET OPTIONS (exclude_ttl_deletes = true)

Reemplaza lo siguiente:

  • CHANGE_STREAM_NAME: Es el nombre del flujo de cambios existente.

En el siguiente ejemplo, se agrega el filtro exclude_ttl_deletes a un flujo de cambios existente llamado NewFilterChangeStream, que excluye todas las eliminaciones basadas en el TTL:

ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET OPTIONS (exclude_ttl_deletes = true)

Esto excluye todas las eliminaciones basadas en el TTL del flujo de cambios.

PostgreSQL

Si deseas agregar el filtro de eliminaciones basado en el TTL a un flujo de cambios existente, usa lo siguiente para establecer el filtro en True:

ALTER CHANGE STREAM STREAM_NAME FOR ALL
SET (exclude_ttl_deletes = true)

Reemplaza lo siguiente:

  • STREAM_NAME: Es el nombre del flujo de cambios existente.

En el siguiente ejemplo, el filtro exclude_ttl_deletes se agrega a un flujo de cambios existente llamado NewFilterChangeStream:

ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET (exclude_ttl_deletes = true)

Esto excluye todas las eliminaciones basadas en el TTL futuras del flujo de cambios.

Quita el filtro de eliminaciones basado en el TTL de un flujo de cambios existente

GoogleSQL

Para quitar el filtro de eliminaciones basado en el TTL de un flujo de cambios existente, usa lo siguiente para establecer el filtro en False:

ALTER CHANGE STREAM STREAM_NAME FOR ALL
SET OPTIONS (exclude_ttl_deletes = false)

Reemplaza lo siguiente:

  • STREAM_NAME: Es el nombre del flujo de cambios nuevo.

En el siguiente ejemplo, se quita el filtro exclude_ttl_deletes de un flujo de cambios existente llamado NewFilterChangeStream:

ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET OPTIONS (exclude_ttl_deletes = false)

Esto incluye todas las eliminaciones futuras basadas en el TTL del flujo de cambios.

También puedes establecer el filtro en null para quitar el filtro de eliminaciones basado en el TTL.

PostgreSQL

Para quitar el filtro de eliminaciones basado en el TTL de un flujo de cambios existente, usa lo siguiente para establecer el filtro en False:

ALTER CHANGE STREAM STREAM_NAME FOR ALL
SET (exclude_ttl_deletes = false)

Reemplaza lo siguiente:

  • STREAM_NAME: Es el nombre del flujo de cambios nuevo.

En el siguiente ejemplo, se quita el filtro exclude_ttl_deletes de un flujo de cambios existente llamado NewFilterChangeStream:

ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET (exclude_ttl_deletes = false)

Esto incluye todas las eliminaciones futuras basadas en el TTL del flujo de cambios.

También puedes establecer el filtro en null para quitar el filtro de eliminaciones basado en el TTL.

Modificar filtro por tipo de modificación de tabla

Si deseas modificar los filtros de tipo de modificación de tabla para un flujo de cambios, configura el tipo de filtro en una declaración DDL ALTER CHANGE STREAM. Puedes usarlo para agregar un filtro nuevo o quitar uno existente del flujo de cambios.

Cómo agregar un filtro de tipo de modificación de tabla a un flujo de cambios existente

GoogleSQL

Para agregar uno o más filtros nuevos de tipo de modificación de tabla a un flujo de cambios existente, usa lo siguiente para establecer el filtro en true:

ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET OPTIONS (MOD_TYPE_FILTER_NAME = true)

Reemplaza lo siguiente:

  • CHANGE_STREAM_NAME: Se reemplaza por el nombre del flujo de cambios existente.
  • MOD_TYPE_FILTER_NAME: Reemplázalo por el filtro que deseas agregar: exclude_insert, exclude_update o exclude_delete. Si agregas más de un filtro a la vez, separa cada uno con una coma.

En el siguiente ejemplo, el filtro exclude_delete se agrega a un flujo de cambios existente llamado NewFilterChangeStream:

ALTER CHANGE STREAM NewFilterChangeStream
SET OPTIONS (exclude_delete = true)

PostgreSQL

Para agregar uno o más filtros nuevos de tipo de modificación de tabla a un flujo de cambios existente, usa lo siguiente para establecer el filtro en true:

ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET (MOD_TYPE_FILTER_NAME = true)

Reemplaza lo siguiente:

  • CHANGE_STREAM_NAME: Se reemplaza por el nombre del flujo de cambios existente.
  • MOD_TYPE_FILTER_NAME: Reemplázalo por el filtro que deseas agregar: exclude_insert, exclude_update o exclude_delete. Si agregas más de un filtro a la vez, separa cada uno con una coma.

En el siguiente ejemplo, el filtro exclude_delete se agrega a un flujo de cambios existente llamado NewFilterChangeStream:

ALTER CHANGE STREAM NewFilterChangeStream
SET (exclude_delete = true)

Cómo quitar un filtro de tipo de modificación de tabla de un flujo de cambios existente

GoogleSQL

Para quitar uno o más filtros de tipo de modificación de tabla existentes en el flujo de cambios, usa lo siguiente para establecer el filtro en false:

ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET OPTIONS (MOD_TYPE_FILTER_NAME = false)

Reemplaza lo siguiente:

  • CHANGE_STREAM_NAME: Se reemplaza por el nombre del flujo de cambios existente.
  • MOD_TYPE_FILTER_NAME: Reemplázalo por el filtro que deseas quitar: exclude_insert, exclude_update o exclude_delete. Si quitas más de un filtro a la vez, separa cada uno con una coma.

En el siguiente ejemplo, el filtro exclude_delete se quita de un flujo de cambios existente llamado NewFilterChangeStream:

ALTER CHANGE STREAM NewFilterChangeStream
SET OPTIONS (exclude_delete = false)

También puedes quitar un filtro de modificación de tablas si lo configuras de nuevo en el valor predeterminado. Para ello, establece el valor del filtro en null.

PostgreSQL

Para quitar uno o más filtros de tipo de modificación de tabla existentes en el flujo de cambios, usa lo siguiente para establecer el filtro en False:

ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET (MOD_TYPE_FILTER_NAME = false)

Reemplaza lo siguiente:

  • CHANGE_STREAM_NAME: Se reemplaza por el nombre del flujo de cambios existente.
  • MOD_TYPE_FILTER_NAME: Reemplázalo por el filtro que deseas agregar: exclude_insert, exclude_update o exclude_delete. Si agregas más de un filtro a la vez, separa cada uno con una coma.

En el siguiente ejemplo, el filtro exclude_delete se quita de un flujo de cambios existente llamado NewFilterChangeStream:

ALTER CHANGE STREAM NewFilterChangeStream
SET (exclude_delete = false)

También puedes quitar un filtro de modificación de tablas si lo configuras de nuevo en el valor predeterminado. Para ello, establece el valor del filtro en null.

Cómo suspender una transmisión de cambios

Si deseas que un flujo de cambios detenga su actividad, pero que conserve sus registros internos (al menos durante el período de retención de datos), puedes modificarlo para que no observe nada.

Para ello, emite una declaración DDL ALTER CHANGE STREAM que reemplace la definición del flujo de cambios por la frase especial DROP FOR ALL. Por ejemplo:

ALTER CHANGE STREAM MyStream DROP FOR ALL;

La transmisión sigue existiendo en la base de datos, pero no supervisa objetos y no genera más registros de cambios en los datos. Los registros de cambios existentes permanecen intactos, sujetos a la política de retención de datos de la transmisión.

Para reanudar una transmisión suspendida, emite otra declaración ALTER CHANGE STREAM con su configuración anterior.

Cómo borrar un flujo de cambios

Para borrar una transmisión de cambios de forma permanente, emite una declaración DROP CHANGE STREAM que incluya el nombre de la transmisión:

DROP CHANGE STREAM NamesAndAlbums;

Spanner detiene de inmediato la transmisión, la quita del esquema de la base de datos y borra sus registros de cambios de datos.

Enumerar y ver flujos de cambios

La consola de Google Cloud proporciona una interfaz web para enumerar y revisar las definiciones del flujo de cambios de una base de datos. También puedes ver la estructura de los flujos de cambios como sus declaraciones DDL equivalentes o mediante una consulta del esquema de información de la base de datos.

Consulta las flujos de cambios con la consola de Google Cloud

Para ver una lista de los flujos de cambios de una base de datos y revisar sus definiciones, haz lo siguiente:

  1. Visita la página Instancias de Spanner en la consola de Google Cloud.

    Abrir la página Instancias

  2. Navega a la instancia y la base de datos correspondientes.

  3. Haz clic en Flujos de cambios en el menú de navegación.

Aquí se muestra una lista de todos los flujos de cambios de la base de datos y se resume la configuración de cada uno. Si haces clic en el nombre de una transmisión, se muestran más detalles sobre las tablas y columnas que observa.

Ver definiciones de flujos de cambios como DDL

La visualización del esquema de una base de datos como DDL incluye descripciones de todos sus flujos de cambios, en las que aparecen como declaraciones CREATE CHANGE STREAM.

  • Para hacerlo desde la consola, haz clic en el vínculo Mostrar DDL equivalente en la página de la base de datos en la consola de Google Cloud.

  • Para hacerlo desde la línea de comandos, usa el comando ddl describe de Google Cloud CLI.

Consultar el esquema de información sobre los flujos de cambios

Puedes consultar directamente el esquema de información de una base de datos sobre sus flujos de cambios. Las siguientes tablas contienen los metadatos que definen los nombres de los flujos de cambios, las tablas y columnas que observan, y sus períodos de retención:

Prácticas recomendadas para las transmisiones de cambios

Las siguientes son algunas prácticas recomendadas para configurar y administrar flujos de cambios.

Considera usar una base de datos de metadatos independiente

Los flujos de cambios usan una base de datos de metadatos para mantener el estado interno. La base de datos de metadatos puede ser igual o diferente a la base de datos que contiene los flujos de cambios. Te recomendamos crear una base de datos separada para el almacenamiento de metadatos.

El conector de flujos de cambios de Spanner necesita permisos de lectura y escritura para la base de datos de metadatos. No necesitas preparar esta base de datos con un esquema; el conector se encarga de eso.

Usar una base de datos de metadatos separada elimina las complejidades que podrían surgir de permitir que el conector escriba directamente en la base de datos de tu aplicación:

  • Cuando separa la base de datos de metadatos de la base de datos de producción con el flujo de cambios, el conector solo necesita permisos de lectura para la base de datos de producción.

  • Cuando se restringe el tráfico del conector a una base de datos de metadatos independiente, las escrituras que realiza el conector no se incluyen en los flujos de cambios de producción. Esto es particularmente relevante para los flujos de cambioss que observan toda la base de datos.

Si no se utiliza ninguna base de datos separada para almacenar los metadatos, recomendamos supervisar el impacto en la CPU del conector de flujos de cambios en sus instancias.

Haz una comparativa de los nuevos flujos de cambios y cambia su tamaño si es necesario.

Antes de agregar flujos de cambios nuevos a la instancia de producción, considera comparar una carga de trabajo realista en una instancia de etapa de pruebas con flujos de cambios habilitados. Esto te permite determinar si necesitas agregar nodos a tu instancia para aumentar sus capacidades de procesamiento y almacenamiento.

Ejecuta estas pruebas hasta que las métricas de CPU y almacenamiento se estabilicen. De manera óptima, el uso de CPU de la instancia debe permanecer por debajo de los valores máximos recomendados y su uso de almacenamiento no debe superar el límite de almacenamiento de la instancia.

Usa diferentes regiones para el balanceo de cargas

Cuando uses flujos de cambios en una configuración de instancia multirregional, considera ejecutar sus canalizaciones de procesamiento en una región diferente a la región líder predeterminada. Esto ayuda a distribuir la carga de transmisión entre las réplicas no líderes. Sin embargo, si necesitas priorizar el retraso de transmisión más bajo posible en el balanceo de cargas, ejecuta la carga de transmisión en la región líder.

¿Qué sigue?