Exporta bases de datos de Spanner a Avro

En esta página, se describe cómo exportar bases de datos de Spanner con la consola de Google Cloud.

Para exportar una base de datos de Spanner con la API de REST o Google Cloud CLI, completa los pasos de la sección Antes de comenzar en esta página y, luego, consulta las instrucciones detalladas en Spanner a Cloud Storage Avro en la documentación de Dataflow. El proceso de exportación usa Dataflow y escribe los datos en una carpeta de bucket de Cloud Storage. La carpeta resultante contiene un conjunto de Archivos Avro y archivos de manifiesto JSON.

Antes de comenzar

Para exportar una base de datos de Spanner, primero debes habilitar la conexión de Spanner, Cloud Storage, Compute Engine y las API de Dataflow:

Enable the APIs

También necesitas una cuota suficiente y los permisos necesarios de IAM.

Requisitos de cuota

Los requisitos de cuota para los trabajos de exportación son los siguientes:

• Spanner: Sin datos adicionales se requiere capacidad de procesamiento para exportar una base de datos, aunque podrías necesitar agregar más capacidad de procesamiento para que el trabajo termine en una cantidad razonable un plazo determinado. Consulta Optimiza trabajos para obtener más detalles.
• Cloud Storage: Para exportar, debes crear un bucket para los archivos exportados si aún no tienes uno. Puedes hacerlo en la consola de Google Cloud ya sea a través de la página de Cloud Storage o mientras creas tu exportación a través de la página de Spanner. No es necesario que establezcas un tamaño para tu bucket.
• Dataflow: los trabajos de exportación están sujetos a las mismas cuotas de Compute Engine de direcciones IP, uso del disco y CPU que otros trabajos de Dataflow.

• Compute Engine: antes de ejecutar el trabajo de exportación, debes configurar las cuotas iniciales para Compute Engine, que Dataflow usa. Estas cuotas representan la cantidad máxima de recursos que permites que Dataflow use para tu trabajo. Los valores iniciales recomendados son los siguientes:

  • CPU: 200
  • Direcciones IP en uso: 200
  • Disco persistente estándar: 50 TB

  Por lo general, no es necesario hacer ningún otro ajuste. Dataflow proporciona el ajuste de escala automático para que solo pagues por los recursos reales que se usaron durante la exportación. Si tu trabajo puede utilizar más recursos, la IU de Dataflow muestra un ícono de advertencia. El trabajo debería completarse incluso si hay un ícono de advertencia.

Roles obligatorios

A fin de obtener los permisos que necesitas para exportar una base de datos, solicita a tu administrador que te otorgue el siguientes roles de IAM en la cuenta de servicio del trabajador de Dataflow:

• Visualizador de Cloud Spanner (roles/spanner.viewer)
• Trabajador de Dataflow (roles/dataflow.worker)
• Administrador de almacenamiento (roles/storage.admin)
• Lector de base de datos de Spanner (roles/spanner.databaseReader)
• Administrador de bases de datos (roles/spanner.databaseAdmin)

Nota: El rol de administrador de la base de datos de Spanner solo es obligatorio para los trabajos de importación.

Para usar los recursos de procesamiento independientes de Data Boost de Spanner durante una exportación, sigue estos pasos: también necesitas el permiso de IAM spanner.databases.useDataBoost permiso. Para obtener más información, consulta Descripción general de Data Boost.

Cómo exportar una base de datos

Una vez que cumplas con los requisitos de cuota y de IAM descritos anteriormente, puedes exportar una base de datos de Spanner existente.

Nota: Es seguro exportar una base de datos que esté en uso. Sin embargo, cualquier cambio que realizar después de que Dataflow crea una transacción de Spanner los datos exportados no son capturados por la exportación, ya que todos los datos exportados son de la misma instantánea de la base de datos.

Para exportar tu base de datos de Spanner a un bucket de Cloud Storage, sigue estos pasos:

1. Ve a la página Instancias de Spanner.

   Ir a Instancias

2. Haz clic en el nombre de la instancia que contiene tu base de datos.

3. Haz clic en el elemento de menú Importar/Exportar en el panel izquierdo y, luego, haz clic en Botón Exportar.

4. En Elegir dónde almacenar la exportación, haz clic en Explorar.

5. Si aún no tienes un bucket de Cloud Storage para tu exportación, sigue estos pasos:

   1. Haz clic en Nuevo bucket.
   2. Ingresa un nombre para tu bucket. Los nombres de depósito deben ser únicos en Cloud Storage.
   3. Selecciona una clase y una ubicación de almacenamiento predeterminadas y, a continuación, haz clic en Crear.
   4. Haz clic en tu bucket para seleccionarlo.

   Si ya tienes un depósito, selecciona el depósito de la lista inicial o haz clic en Buscar para filtrar la lista y, luego, haz clic en tu depósito a fin de seleccionarlo.

6. Haz clic en Seleccionar.

7. En el menú desplegable Elegir una base de datos para exportar, selecciona la base de datos que deseas exportar.

8. Opcional: Para exportar tu base de datos desde un momento anterior, marca la casilla y, luego, ingresa una marca de tiempo.

9. En el menú desplegable Elegir una región para el trabajo de exportación, selecciona una región.

   Nota: Para evitar los cargos de transferencia de datos, elige una región que se superponga con la configuración de tu instancia. Para obtener más información, consulta Elige una región.

10. Encriptar el estado de la canalización de Dataflow con una Clave de encriptación administrada por el cliente:

    1. Haz clic en Mostrar opciones de encriptación.
    2. Selecciona Usar una clave de encriptación administrada por el cliente (CMEK).
    3. Selecciona tu clave de la lista desplegable.

    Esta opción no afecta la encriptación a nivel del bucket de Cloud Storage de destino. Para habilitar CMEK en tu bucket de Cloud Storage, consulta Usa CMEK con Cloud Storage.

11. Opcional: Para exportar con Data Boost de Spanner, selecciona la casilla de verificación Usar Data Boost de Spanner. Para obtener más información, consulta Descripción general de Data Boost.

12. Selecciona la casilla de verificación en Confirmar cargos para confirmar que existen cargos adicionales a los incurridos por tu instancia existente de Spanner.

13. Haz clic en Exportar.

    La consola de Google Cloud muestra la página Importar/Exportar base de datos, que ahora muestra un elemento de una sola línea para tu trabajo de exportación en la lista de trabajos de Importar/Exportar, incluido el tiempo transcurrido del trabajo:

    

Cuando el trabajo finaliza, el estado se actualiza en la lista Importar/Exportar. Si la tarea se realizó correctamente, se mostrará el estado Succeeded:

Si el trabajo falló, se mostrará el estado Failed:

Para ver los detalles de la operación de Dataflow de tu trabajo, haz clic en el nombre del trabajo en la columna Nombre del trabajo de Dataflow.

Si tu trabajo falla, revisa los registros de Dataflow del trabajo para ver los detalles del error.

Para evitar que Cloud Storage cobre cargos por los archivos que creó el trabajo de exportación con errores, borra la carpeta y sus archivos. Consulta Visualiza la exportación para obtener información sobre cómo encontrar la carpeta.

Nota sobre la exportación de columnas generadas y flujos de cambios

No se exportan los valores de una columna generada almacenada. La definición de la columna se exporta al esquema de Avro como un campo de registro de tipo nulo, con la definición de la columna como propiedades personalizadas del campo. Hasta que se completa la operación de reabastecimiento de una columna generada recién agregada, esta se ignora como si no existiera en el esquema.

Los flujos de cambios exportados como archivos Avro solo contienen el esquema de los flujos de cambios y no los registros de cambios de datos.

Nota sobre la exportación de secuencias

Secuencias (GoogleSQL, PostgreSQL) son objetos de esquema que se usan para generar valores de número entero únicos. Spanner exporta cada uno de los objetos de esquema al esquema de Avro como un campo de registro, con su tipo de secuencia, rango omitido y contador como propiedades del campo. Ten en cuenta que, para evitar que se restablezca una secuencia y genere valores duplicados después de la importación, durante la exportación del esquema, la función GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) captura el contador de secuencia. Spanner agrega un búfer de 1, 000 en el contador y escribe el valor nuevo del contador en el campo de registro. Esta Evita los errores de valores duplicados que pueden ocurrir después de la importación. Si hay más escrituras en la base de datos de origen durante la exportación de datos, deberías ajustar el contador de secuencias real con ALTER SEQUENCE (GoogleSQL, PostgreSQL) declaración.

Durante la importación, la secuencia comienza desde este contador nuevo en lugar del contador que se encuentra en el esquema. Como alternativa, puedes usar la sentencia ALTER SEQUENCE (GoogleSQL, PostgreSQL) para actualizar la secuencia con un contador nuevo.

Consulta tu exportación en Cloud Storage

Para ver la carpeta que contiene tu base de datos exportada en la de la consola de Google Cloud, navega al navegador de Cloud Storage elige el bucket que seleccionaste anteriormente:

Ir al explorador de almacenamiento

El bucket ahora contiene una carpeta con la base de datos exportada dentro. El nombre de la carpeta comienza con el ID de la instancia, el nombre de la base de datos y la marca de tiempo de tu trabajo de exportación. La carpeta contiene estos archivos:

• Un archivo spanner-export.json
• Un archivo TableName-manifest.json para cada tabla de la base de datos que exportaste

• Uno o más archivos TableName.avro-#####-of-##### El primer número de la extensión .avro-#####-of-##### representa el índice del archivo Avro, comenzando en cero, y el segundo representa la cantidad de archivos Avro generados para cada tabla.

  Por ejemplo, Songs.avro-00001-of-00002 es el segundo de dos archivos que contiene los datos de la tabla Songs.

• Un archivo ChangeStreamName-manifest.json para cada flujo de cambios en la base de datos que y exportarse.

• Un ChangeStreamName.avro-00000-of-00001 para cada flujo de cambios. Este archivo contiene datos vacíos solo con el esquema de Avro del flujo de cambios.

Elige una región para tu trabajo de importación

Puedes elegir una región diferente según la ubicación de tu bucket de Cloud Storage. Para evitar cargos de transferencia de datos salientes, elige una región que coincida con la ubicación de tu bucket de Cloud Storage.

• Si la ubicación de tu bucket de Cloud Storage es una región, puedes aprovechar el uso gratuito de la red si eliges la misma región para tu trabajo de importación, siempre que esa región esté disponible.

• Si la ubicación de tu bucket de Cloud Storage es de región doble, puedes aprovechar el uso gratuito de red eligiendo una de las dos regiones que conforman la región doble para tu trabajo de importación, siempre que una de las regiones esté disponible.

• Si una región con ubicación compartida no está disponible para tu trabajo de importación o si tu La ubicación del bucket de Cloud Storage es una multirregión, se aplican cargos de transferencia de datos salientes. Consulta Cloud Storage transferencia de datos para elegir una región que incurra en los costos de transferencia de datos más bajos.

Cómo exportar un subconjunto de tablas

Si quieres exportar solo los datos de ciertas tablas y no los en toda la base de datos, podrás especificar esas tablas durante la exportación. En en este caso, Spanner exporta todo el esquema de la base de datos, incluidas los datos de las tablas que especifiques y dejando todas las demás tablas presentes, pero vacío en el archivo exportado.

Puedes especificar un subconjunto de tablas para exportar con el de Dataflow en la consola de Google Cloud gcloud CLI. (La página de Spanner no proporciona esta acción).

Si exportas los datos de una tabla que es secundaria de otra tabla, debería exportar su elemento superior datos de una tabla específica. Si los elementos superiores no se exportan, el trabajo de exportación falla.

Para exportar un subconjunto de tablas, inicia la exportación con la plantilla de Spanner a Avro de Cloud Storage de Dataflow y especifica las tablas con la página de Dataflow en la consola de Google Cloud o con gcloud CLI, como se describe a continuación:

Console

Si usas la página de Dataflow en la consola de Google Cloud, el parámetro Nombres de las tablas de Cloud Spanner se encuentra en la sección Parámetros opcionales de la página Crear trabajo a partir de una plantilla. Se pueden especificar varias tablas en formato separado por comas.

Ir a Dataflow

gcloud

Ejecuta el comando gcloud dataflow jobs run y especifica el argumento tableNames. Por ejemplo:

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=table1,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

Especificar varias tablas en gcloud requiere escapa de argumentos de tipo de diccionario. En el siguiente ejemplo, se usa “|” como carácter de escape:

 gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='^|^instanceId=test-instance|databaseId=example-db|tableNames=table1,table2|outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

El parámetro shouldExportRelatedTables es una opción conveniente para exportar automáticamente todas las tablas superiores de las tablas elegidas. Por ejemplo, en esta jerarquía de esquema con las tablas Singers, Albums y Songs, solo debes especificar Songs La opción shouldExportRelatedTables también exportará Singers. y Albums porque Songs es descendiente de ambos.

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=Songs,shouldExportRelatedTables=true,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

Visualiza o soluciona problemas de trabajos en la IU de Dataflow

Después de iniciar un trabajo de exportación, puedes ver los detalles del trabajo, incluido lo siguiente: en la sección Dataflow de la consola de Google Cloud.

Ver los detalles del trabajo de Dataflow

Para ver los detalles de los trabajos de importación o exportación que ejecutaste durante la última semana, incluidos los trabajos que se están ejecutando ahora:

1. Navega hasta la página Descripción general de la base de datos de la base de datos.
2. Haz clic en el elemento de menú del panel izquierdo Importar/Exportar. En la página Importar/Exportar de la base de datos, se muestra una lista de trabajos recientes.

3. En la página Importar/Exportar de la base de datos, haz clic en el nombre del trabajo en la columna Nombre del trabajo de Dataflow:

   

   En la consola de Google Cloud, se muestran los detalles del el trabajo.

Para ver un trabajo que ejecutaste hace más de una semana, sigue estos pasos:

1. Ve a la página de trabajos de Dataflow en la consola de Google Cloud.

   Ir a Trabajos

2. Busca tu trabajo en la lista y haz clic sobre su nombre.

   La consola de Google Cloud muestra los detalles del trabajo de Dataflow.

Nota: Los trabajos del mismo tipo para la misma base de datos tienen el mismo nombre. Puedes distinguir los trabajos de los valores en las columnas Hora de inicio o, también, Hora de finalización.

Visualiza los registros de Dataflow de tu trabajo

Para ver los registros de un trabajo de Dataflow, navega hasta la página de detalles del trabajo y, luego, haz clic en Registros a la derecha del nombre del trabajo.

Si un trabajo falla, busca errores en los registros. Si hay errores, el recuento de errores se muestra junto a Registros (Logs):

Para ver los errores del trabajo, sigue estos pasos:

1. Haz clic en el recuento de errores junto a Registros (Logs).

   La consola de Google Cloud muestra los registros del trabajo. Es posible que debas desplazarte para ver los errores.

2. Identifica las entradas con el ícono de error .

3. Haz clic en una entrada de registro individual para expandir su contenido.

Para obtener más información sobre cómo solucionar problemas de trabajos de Dataflow, consulta Solución de problemas y depuración.

Soluciona problemas de trabajos de exportación con errores

Si ves los siguientes errores en tus registros de trabajos, haz lo siguiente:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Verifica la latencia de lectura del 99% en la pestaña Supervisión de tu base de datos de Spanner en la consola de Google Cloud. Si se muestran valores altos (de varios segundos), eso indica que la instancia está sobrecargada, lo que hace que las lecturas agoten el tiempo de espera y fallen.

Una de las causas de la latencia alta es que el trabajo de Dataflow se ejecuta con demasiados trabajadores, lo que pone demasiada carga en la instancia de Spanner.

Especificar un límite en la cantidad de trabajadores de Dataflow, en lugar de desde la pestaña Importar/Exportar de la página de detalles de la instancia Spanner en la consola de Google Cloud, debes comenzar la exportación con el Dataflow Plantilla de Spanner a Cloud Storage en Avro y especifica la cantidad máxima de trabajadores como se describe:

Console

Si usas la consola de Dataflow, la columna Máx. de trabajadores se encuentra en la sección Parámetros opcionales de la Página Crear un trabajo a partir de una plantilla.

Ir a Dataflow

gcloud

Ejecuta gcloud dataflow jobs run. y especifica el argumento max-workers. Por ejemplo:

  gcloud dataflow jobs run my-export-job \
    --gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,outputDir=gs://my-gcs-bucket' \
    --max-workers=10 \
    --network=network-123

Cómo solucionar problemas de red

El siguiente error puede ocurrir cuando exportas tu Spanner bases de datos:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Este error ocurre porque Spanner supone que quieres usar una red de VPC de modo automático llamada default en el mismo proyecto que el trabajo de Dataflow. Si no tienes una red de VPC predeterminada en el o si tu red de VPC está en una red de VPC en modo personalizado, debes crear un trabajo de Dataflow y especifica una red o subred alternativa.

Optimiza los trabajos de exportación de ejecución lenta

Si seguiste las sugerencias de la configuración inicial, por general, no se debe realizar ningún otro ajuste. Si tu trabajo se ejecuta a poca velocidad, existen otras optimizaciones que puedes probar:

• Optimiza el trabajo y la ubicación de los datos: Ejecuta tu trabajo de Dataflow en la misma región donde se encuentran tu instancia de Spanner y el bucket de Cloud Storage.

• Garantiza recursos suficientes de Dataflow: Si las cuotas relevantes de Compute Engine limitan los recursos de tu trabajo de Dataflow, la página de Dataflow del trabajo en la consola de Google Cloud muestra un ícono de advertencia y mensajes de registro:

  

  En esta situación, aumentar las cuotas para CPU, direcciones IP en uso y el disco persistente estándar podría acortar el tiempo de ejecución del trabajo, pero se podrían generar más cargos de Compute Engine.

• Comprueba el uso de CPU de Spanner: Si ves que el uso de CPU de la instancia supera el 65%, puedes aumentar la capacidad de procesamiento en esa instancia. La capacidad agrega más Los recursos de Spanner y el trabajo deberían acelerarse, pero incurrirás en más Cargos de Spanner

Factores que afectan el rendimiento del trabajo de exportación

Varios factores influyen en el tiempo que lleva completar un trabajo de exportación.

• Tamaño de la base de datos de Spanner: Procesar más datos lleva más tiempo. y recursos.

• Esquema de la base de datos de Spanner, que incluye lo siguiente:

  • La cantidad de tablas
  • El tamaño de las filas
  • La cantidad de índices secundarios
  • La cantidad de claves externas
  • La cantidad de flujos de cambios

• Ubicación de los datos: Los datos se transfieren entre Spanner y Cloud Storage con Dataflow. Lo ideal es que los tres componentes se ubiquen en la misma región. Si los componentes no están en la misma región, mover los datos entre las regiones hace que la ejecución del trabajo sea más lenta.

• Cantidad de trabajadores de Dataflow: Los trabajadores óptimos de Dataflow son necesarios para un buen rendimiento. Mediante el ajuste de escala automático, Dataflow elige la cantidad de trabajadores en función de la cantidad de trabajo que se debe realizar. Sin embargo, la cantidad de trabajadores estará limitada por las cuotas de las CPU, las direcciones IP en uso y el disco persistente estándar. La IU de Dataflow muestra un ícono de advertencia si se alcanzan los límites de cuota. En esta situación, el progreso es más lento, pero el trabajo se completará de todos modos.

• Carga existente en Spanner: Por lo general, un trabajo de exportación agrega una carga ligera en una instancia de Spanner. Si la instancia ya tiene una carga sustancial existente, el trabajo se ejecutará más lento.

• Cantidad de capacidad de procesamiento de Spanner: Si el uso de CPU de la instancia supera el 65%, el trabajo se ejecutará más lento.