Importar archivos Avro de Spanner

En esta página se describe cómo importar bases de datos de Spanner a Spanner mediante la consola. Google Cloud Para importar archivos Avro de otra fuente, consulta Importar datos de bases de datos que no usan Spanner.

El proceso usa Dataflow e importa datos de una carpeta de un segmento de Cloud Storage que contiene un conjunto de archivos Avro y archivos de manifiesto JSON. El proceso de importación solo admite archivos Avro exportados desde Spanner.

Para importar una base de datos de Spanner mediante la API REST o la gcloud CLI, sigue los pasos que se indican en la sección Antes de empezar de esta página y, a continuación, consulta las instrucciones detalladas en Importar archivos Avro de Cloud Storage a Spanner.

Antes de empezar

Para importar una base de datos de Spanner, primero debes habilitar las APIs de Spanner, Cloud Storage, Compute Engine y Dataflow:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

También necesitas suficiente cuota y los permisos de gestión de identidades y accesos necesarios.

Requisitos de cuota

Los requisitos de cuota para las tareas de importación son los siguientes:

• Spanner: debes tener suficiente capacidad de computación para admitir la cantidad de datos que vas a importar. No se necesita capacidad de computación adicional para importar una base de datos, aunque es posible que tengas que añadir más capacidad de computación para que el trabajo se complete en un tiempo razonable. Para obtener más información, consulta Trabajos de Optimize.
• Cloud Storage: para importar, debes tener un segmento que contenga los archivos que hayas exportado anteriormente. No es necesario que defina un tamaño para el segmento.
• Dataflow: las tareas de importación están sujetas a las mismas cuotas de CPU, uso de disco y dirección IP de Compute Engine que otras tareas de Dataflow.

• Compute Engine: antes de ejecutar el trabajo de importación, debes configurar las cuotas iniciales de Compute Engine, que utiliza Dataflow. Estas cuotas representan el número máximo de recursos que permites que Dataflow use en tu trabajo. Los valores iniciales recomendados son los siguientes:

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

  Por lo general, no tienes que hacer ningún otro ajuste. Dataflow proporciona autoescalado para que solo pagues por los recursos reales utilizados durante la importación. Si tu trabajo puede usar más recursos, la interfaz de usuario de Dataflow muestra un icono de advertencia. El trabajo debería finalizar aunque haya un icono de advertencia.

Roles obligatorios

Para obtener los permisos que necesitas para exportar una base de datos, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en la cuenta de servicio de trabajador de Dataflow:

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

Nota: El rol Administrador de base de datos de Spanner solo es necesario para los trabajos de importación.

Opcional: Busca la carpeta de tu base de datos en Cloud Storage

Para encontrar la carpeta que contiene la base de datos exportada en la consola deGoogle Cloud , ve al navegador de Cloud Storage y haz clic en el segmento que contiene la carpeta exportada.

Ir al navegador de Cloud Storage

El nombre de la carpeta que contiene los datos exportados empieza por el ID de tu instancia, el nombre de la base de datos y la marca de tiempo de la tarea de exportación. La carpeta contiene lo siguiente:

• Un archivo spanner-export.json.
• Un archivo TableName-manifest.json por cada tabla de la base de datos que hayas exportado.

• Uno o varios archivos TableName.avro-#####-of-#####. El primer número de la extensión .avro-#####-of-##### representa el índice del archivo Avro, que empieza por cero, y el segundo representa el número de archivos Avro generados para cada tabla.

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

• Un archivo ChangeStreamName-manifest.json por cada flujo de cambios de la base de datos que hayas exportado.

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

Importar una base de datos

Para importar tu base de datos de Spanner de Cloud Storage a tu instancia, sigue estos pasos.

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

   Ir a la página de instancias

2. Haga clic en el nombre de la instancia que contendrá la base de datos importada.

3. En el panel de la izquierda, haz clic en Importar/Exportar y, a continuación, en el botón Importar.

4. En Elegir una carpeta de origen, haz clic en Examinar.

5. Busca el contenedor que contiene la exportación en la lista inicial o haz clic en Buscar para filtrar la lista y encontrar el contenedor. Haz doble clic en el contenedor para ver las carpetas que contiene.

6. Busca la carpeta con los archivos exportados y haz clic para seleccionarla.

   Nota: Asegúrate de seleccionar la carpeta creada por el trabajo de exportación y no una carpeta de nivel superior que contenga la carpeta exportada.

7. Haz clic en Seleccionar.

8. Introduce un nombre para la nueva base de datos, que Spanner creará durante el proceso de importación. El nombre de la base de datos no puede existir ya en tu instancia.

9. Elige el dialecto de la nueva base de datos (GoogleSQL o PostgreSQL).

10. (Opcional) Para proteger la nueva base de datos con una clave de cifrado gestionada por el cliente, haz clic en Mostrar opciones de cifrado y selecciona Usar una clave de cifrado gestionada por el cliente (CMEK). A continuación, selecciona una clave de la lista desplegable.

11. Selecciona una región en el menú desplegable Selecciona una región para la tarea de importación.

    Nota: Para evitar cargos por transferencia de datos saliente, elige una región que se solape con la ubicación de tu segmento de Cloud Storage. Consulta la sección Elegir una región más abajo para obtener más información.

12. (Opcional) Para cifrar el estado de la canalización de Dataflow con una clave de cifrado gestionada por el cliente, haz clic en Mostrar opciones de cifrado y selecciona Usar una clave de cifrado gestionada por el cliente (CMEK). A continuación, selecciona una clave de la lista desplegable.

13. Seleccione la casilla de verificación de Confirm charges (Confirmar cargos) para confirmar que se aplicarán cargos adicionales a los de su instancia de Spanner.

14. Haz clic en Importar.

    En la consola se muestra la página Detalles de la base de datos, que ahora incluye un cuadro con información sobre el trabajo de importación, como el tiempo transcurrido: Google Cloud

    

Cuando el trabajo finaliza o termina, la Google Cloud consola muestra un mensaje en la página Detalles de la base de datos. Si el trabajo se completa correctamente, se muestra un mensaje de éxito:

Nota: Una vez que se haya completado correctamente la tarea de importación de Dataflow, Spanner creará índices y claves externas para la base de datos importada. Mientras se crea el índice, la consola Google Cloud muestra un icono de proceso en curso para indicar que se está llevando a cabo una operación de larga duración. El icono se encuentra junto al nombre del índice, en la jerarquía de la base de datos, a la izquierda de la página Detalles de la base de datos. Cuando el icono de en curso cambie al icono de índice , la creación de ese índice habrá finalizado. Puedes consultar SPANNER_STATE en la vista INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS para ver el progreso de la creación de claves externas.

Si el trabajo no se completa correctamente, aparece un mensaje de error:

Si la tarea falla, consulta los registros de Dataflow de la tarea para ver los detalles del error y consulta Solucionar problemas de tareas de importación fallidas.

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

Spanner usa la definición de cada columna generada del esquema Avro para recrear esa columna. Spanner calcula automáticamente los valores de las columnas generadas durante la importación.

Del mismo modo, Spanner usa la definición de cada flujo de cambios en el esquema de Avro para recrearlo durante la importación. Los datos de los cambios en tiempo real no se exportan ni se importan a través de Avro, por lo que todos los cambios en tiempo real asociados a una base de datos recién importada no tendrán registros de datos de cambios.

Nota sobre la importación de secuencias

Cada secuencia (GoogleSQL, PostgreSQL) que exporta Spanner usa la función GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) para registrar su estado actual. Spanner añade un búfer de 1000 al contador y escribe el nuevo valor del contador en las propiedades del campo de registro. Ten en cuenta que esta es solo una forma de evitar los errores de valores duplicados que pueden producirse después de la importación. Ajusta el contador de secuencia real si se realizan más escrituras en la base de datos de origen durante la exportación de datos.

Durante la importación, la secuencia empieza a partir de este nuevo contador en lugar del contador que se encuentra en el esquema. Si es necesario, puedes usar la instrucción ALTER SEQUENCE (GoogleSQL, PostgreSQL) para actualizar a un nuevo contador.

Nota sobre la importación de tablas intercaladas y claves externas

El trabajo de Dataflow puede importar tablas intercaladas, lo que le permite conservar las relaciones entre elementos principales y secundarios de su archivo de origen. Sin embargo, las restricciones de clave externa no se aplican durante la carga de datos. El trabajo de Dataflow crea todas las claves externas necesarias una vez que se ha completado la carga de datos.

Si tienes restricciones de clave externa en la base de datos de Spanner antes de que empiece la importación, es posible que se produzcan errores de escritura debido a infracciones de la integridad referencial. Para evitar errores de escritura, te recomendamos que elimines las claves externas que haya antes de iniciar el proceso de importación.

Selecciona una región para la tarea de importación

Puede que quieras elegir otra región en función de la ubicación de tu segmento de Cloud Storage. Para evitar cargos por transferencia de datos saliente, elige una región que coincida con la ubicación de tu segmento de Cloud Storage.

• Si la ubicación de tu segmento de Cloud Storage es una región, puedes aprovechar el uso de red gratuito eligiendo la misma región para tu tarea de importación, siempre que esté disponible.

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

• Si no hay ninguna región colocada disponible para tu tarea de importación o si la ubicación de tu segmento de Cloud Storage es una multirregión, se aplicarán cargos por transferencia de datos saliente. Consulta los precios de la transferencia de datos de Cloud Storage para elegir una región que genere los cargos más bajos por transferencia de datos.

Ver o solucionar problemas de trabajos en la interfaz de Dataflow

Una vez que hayas iniciado un trabajo de importación, podrás ver los detalles del trabajo, incluidos los registros, en la sección Dataflow de la Google Cloud consola.

Ver los detalles de una tarea de Dataflow

Para ver los detalles de las tareas de importación o exportación que hayas ejecutado en la última semana, incluidas las que se estén ejecutando en este momento, sigue estos pasos:

1. Vaya a la página Resumen de la base de datos de la base de datos.
2. Haz clic en la opción de menú Importar/Exportar del panel de la izquierda. En la página Importar/Exportar de la base de datos se muestra una lista de las tareas recientes.

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

   

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

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 de la Google Cloud consola.

   Ir a Tareas

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

   La consola 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 por los valores de las columnas Hora de inicio u Hora de finalización.

Ver los registros de Dataflow de tu trabajo

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

Si una tarea falla, busca errores en los registros. Si hay errores, el número de errores se mostrará junto a Registros:

Para ver los errores de las tareas, sigue estos pasos:

1. Haz clic en el número de errores situado junto a Registros.

   La Google Cloud consola muestra los registros del trabajo. Puede que tengas que desplazarte para ver los errores.

2. Busca las entradas que tengan el icono de error .

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

Para obtener más información sobre cómo solucionar problemas de trabajos de Dataflow, consulta el artículo Solucionar problemas de una canalización.

Solucionar problemas con tareas de importación fallidas

Si ves los siguientes errores en los registros de tu trabajo:

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

--or--

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

Consulta la latencia de escritura del 99% en la pestaña Monitorización de tu base de datos de Spanner en laGoogle Cloud consola. Si muestra valores altos (varios segundos), significa que la instancia está sobrecargada, lo que provoca que las escrituras se agoten y fallen.

Una de las causas de la alta latencia es que la tarea de Dataflow se ejecuta con demasiados trabajadores, lo que supone una carga excesiva para la instancia de Spanner.

Para especificar un límite en el número de trabajadores de Dataflow, en lugar de usar la pestaña Importar/Exportar de la página de detalles de la instancia de tu base de datos de Spanner en la Google Cloud consola, debes iniciar la importación con la plantilla de Avro de Cloud Storage a Spanner y especificar el número máximo de trabajadores tal como se describe a continuación:

Consola

Si usas la consola de Dataflow, el parámetro Máximo de trabajadores se encuentra en la sección Parámetros opcionales de la página Crear trabajo a partir de plantilla.

Ir a Dataflow

gcloud

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

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

Solucionar un error de red

Puede que se produzca el siguiente error al exportar tus bases de datos de Spanner:

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 se produce porque Spanner da por hecho que quieres usar una red 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 proyecto o si tu red de VPC está en una red de VPC de modo personalizado, debes crear un trabajo de Dataflow y especificar una red o subred alternativa.

Optimizar las tareas de importación lentas

Si has seguido las sugerencias de la sección Configuración inicial, no deberías tener que hacer ningún otro ajuste. Si tu trabajo se ejecuta lentamente, puedes probar otras optimizaciones:

• Optimizar la ubicación de la tarea y de los datos: ejecuta la tarea de Dataflow en la misma región en la que se encuentran tu instancia de Spanner y tu segmento de Cloud Storage.

• Asegúrate de que haya suficientes recursos de Dataflow: si las cuotas de Compute Engine pertinentes limitan los recursos de tu tarea de Dataflow, en la página de Dataflow de la Google Cloud consola se mostrará un icono de advertencia y mensajes de registro:

  

  En esta situación, aumentar las cuotas de CPUs, direcciones IP en uso y discos persistentes estándar podría acortar el tiempo de ejecución del trabajo, pero es posible que incurras en más cargos de Compute Engine.

• Comprueba la utilización de la CPU de Spanner: si ves que la utilización de la CPU de la instancia supera el 65%, puedes aumentar la capacidad de computación de esa instancia. La capacidad añade más recursos de Spanner y el trabajo debería acelerarse, pero incurrirás en más cargos de Spanner.

Factores que afectan al rendimiento de las tareas de importación

Hay varios factores que influyen en el tiempo que se tarda en completar una tarea de importación.

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

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

  • El número de tablas
  • El tamaño de las filas
  • Número de índices secundarios
  • Número de claves externas
  • El número de flujos de cambios

Ten en cuenta que la creación de índices y claves externas continúa después de que se complete la tarea de importación de Dataflow. Los flujos de cambios se crean antes de que se complete la tarea de importación, pero después de que se hayan importado todos los datos.

• Ubicación de los datos: los datos se transfieren entre Spanner y Cloud Storage mediante Dataflow. Lo ideal es que los tres componentes estén en la misma región. Si los componentes no están en la misma región, mover los datos entre regiones ralentiza el trabajo.

• Número de trabajadores de Dataflow: se necesitan trabajadores de Dataflow óptimos para conseguir un buen rendimiento. Con el autoescalado, Dataflow elige el número de trabajadores de la tarea en función de la cantidad de trabajo que se debe realizar. Sin embargo, el número de trabajadores estará limitado por las cuotas de CPUs, direcciones IP en uso y discos persistentes estándar. La interfaz de usuario de Dataflow muestra un icono de advertencia si se encuentra con límites de cuota. En esta situación, el progreso es más lento, pero el trabajo debería completarse igualmente. El autoescalado puede sobrecargar Spanner, lo que provoca errores cuando hay una gran cantidad de datos que importar.

• Carga existente en Spanner: una tarea de importación añade una carga de CPU significativa a una instancia de Spanner. Si la instancia ya tiene una carga considerable, la tarea se ejecutará más lentamente.

• Cantidad de capacidad de computación de Spanner: si la utilización de la CPU de la instancia supera el 65%, el trabajo se ejecuta más lentamente.

Ajustar los workers para que el rendimiento de la importación sea bueno

Al iniciar una tarea de importación de Spanner, los trabajadores de Dataflow deben tener un valor óptimo para que el rendimiento sea bueno. Si hay demasiados trabajadores, se sobrecarga Spanner, y si hay muy pocos, el rendimiento de la importación es mediocre.

El número máximo de trabajadores depende en gran medida del tamaño de los datos, pero, idealmente, el uso total de la CPU de Spanner debería estar entre el 70% y el 90%. De esta forma, se consigue un buen equilibrio entre la eficiencia de Spanner y la finalización de los trabajos sin errores.

Para alcanzar ese objetivo de utilización en la mayoría de los esquemas y las situaciones, recomendamos que el número máximo de vCPUs de trabajador sea entre 4 y 6 veces el número de nodos de Spanner.

Por ejemplo, en una instancia de Spanner de 10 nodos, si usas trabajadores n1-standard-2, deberías definir el número máximo de trabajadores en 25, lo que te daría 50 vCPUs.