Exporta bases de datos de Spanner a Avro

En esta página, se describe cómo exportar bases de datos de Cloud Spanner con Google Cloud Console. Para exportar una base de datos de Spanner mediante la API de REST o la herramienta de línea de comandos de gcloud spanner, completa los pasos de la sección Antes de comenzar en esta página y, luego, consulta las instrucciones detalladas en Cloud Spanner a Cloud Storage Avro. En el proceso de exportación, se usa Dataflow y se escriben datos en una carpeta de un 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 las API de Spanner, Cloud Storage, Compute Engine y Dataflow:

Habilita las API

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: no se requiere capacidad de procesamiento adicional para exportar una base de datos, aunque es posible que necesites agregar más capacidad de procesamiento a fin de que el trabajo se complete en un período razonable. Consulta Optimiza los trabajos para obtener más detalles.
  • Cloud Storage: a fin de exportar, debes crear un depósito para los archivos exportados si aún no tienes uno. Puedes hacerlo en la consola, ya sea a través de la página de Cloud Storage o mientras creas la 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.

Requisitos de IAM

Para exportar una base de datos, también necesitas tener funciones de IAM con permisos suficientes para usar todos los servicios involucrados en un trabajo de exportación. Para obtener información sobre cómo otorgar funciones y permisos, consulta Aplica funciones de IAM.

Para exportar una base de datos, necesitas las siguientes funciones:

  • A nivel de proyecto de Google Cloud:
    • Visualizador de Spanner
    • Administrador de Dataflow
    • Administrador de almacenamiento
  • A nivel de instancia o de la base de datos de Spanner, o a nivel de proyecto de Google Cloud:
    • Spanner Reader
    • Administrador de base de datos de Spanner (obligatorio solo para trabajos de importación)

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.

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 la página Instancias

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

  3. Haz clic en el elemento de menú Import/Export en el panel izquierdo y, luego, en el botón Export.

  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 bucketCaptura de pantalla del elemento de la IU del bucket nuevo.
    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 Captura de pantalla del elemento de IU de búsqueda 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 la base de datos de 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.

  10. Para encriptar el estado de la canalización de Dataflow con una clave de encriptación administrada por el cliente, haz lo siguiente (opcional):

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

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

  11. Selecciona la casilla de verificación en Confirmar cargos para confirmar que existen cargos adicionales a los que se generaron en tu instancia de Spanner existente.

  12. Haga clic en Exportar.

    En la consola, se muestra la página Importación/exportación de base de datos, que ahora muestra una línea de pedido para tu trabajo de exportación en la lista de trabajos de importación y exportación, incluido el tiempo transcurrido del trabajo:

    Captura de pantalla del trabajo en curso

Cuando el trabajo finaliza o se finaliza, el estado se actualiza en la lista de importaciones y exportaciones. Si el trabajo se realizó de forma correcta, se muestra el estado Correcto:

Mensaje de confirmación sobre la exportación de trabajo

Si el trabajo falló, se muestra el estado Con errores:

Mensaje de error sobre la exportación del trabajo

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 cambios de transmisiones

Los valores de una columna generada almacenada no se exportan. La definición de columna se exporta al esquema de Avro como un campo de registro de tipo nulo, con la definición de columna como propiedades personalizadas del campo. Hasta que se complete la operación de reabastecimiento de una columna generada recientemente, la columna generada se ignora como si no existiera en el esquema.

Las transmisiones de cambios exportadas como archivos Avro contienen solo el esquema de las transmisiones de cambios, y no todos los registros de cambios de datos.

Consulta tu exportación en Cloud Storage

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

Ir al navegador de Cloud Storage

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 contienen los datos de la tabla Songs.

  • Un archivo ChangeStreamName-manifest.json para cada transmisión de cambio de la base de datos que exportaste

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

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

Recomendamos que elijas una región diferente según la ubicación de tu bucket de Cloud Storage. Para evitar los cargos de salida de red, elige una región que coincida con la ubicación de tu bucket de Cloud Storage.

  • Si la ubicación del bucket de Cloud Storage es una región, puedes aprovechar el uso gratuito de la red. Para ello, selecciona la misma región para tu trabajo de importación y supone que esa región está disponible.

  • Si la ubicación de tu bucket de Cloud Storage es una región doble, puedes aprovechar el uso gratuito de red. Para ello, elige una de las dos regiones que conforman la región doble para tu trabajo de importación, si suponemos que una de las regiones está disponible.

  • Si una región ubicada en el mismo lugar no está disponible para el trabajo de importación o si la ubicación del bucket de Cloud Storage es una multirregión, se aplican los cargos de salida. Consulta los precios de salida de red de Cloud Storage para elegir una región que genere los cargos de salida de red más bajos.

Exportar un subconjunto de tablas

Si deseas exportar solo los datos de ciertas tablas y no toda la base de datos, puedes especificar esas tablas durante la exportación. En este caso, Cloud Spanner exporta el esquema completo de la base de datos, incluidos los datos de las tablas que especificas y deja todas las demás tablas presentes, pero vacías en el archivo exportado.

Puedes especificar un subconjunto de tablas para exportar con la página de Dataflow en Google Cloud Console o la línea de comandos. (La página de Cloud Spanner no proporciona esta acción).

Si exportas los datos de una tabla que es secundaria de otra, también debes exportar sus datos de la tabla superior. Si no se exportan los elementos superiores, el trabajo de exportación fallará.

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

Google Cloud Console

Si usas la página de Dataflow en Console, el parámetro Nombres de tabla 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 un formato separado por comas.

CLI de gcloud

Si usas la CLI de Google Cloud, usa el argumento tableNames para especificar la tabla deseada. 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

Para especificar varias tablas en gcloud, se requiere el escape de argumentos de tipo 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

El parámetro shouldExportRelatedTables es una opción conveniente para exportar de forma automática todas las tablas superiores de las tablas que desees. Por ejemplo, en esta jerarquía de esquemas con las tablas Singers, Albums y Songs, solo debemos 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

Vea o solucione problemas en los trabajos en la IU de Dataflow

Después de iniciar un trabajo de exportación, puedes ver los detalles del trabajo, incluidos los registros, en la sección de Dataflow de la consola.

Ver detalles del trabajo de Dataflow

Para ver los detalles de cualquier trabajo de importación o exportación que ejecutes durante la última semana, incluidos los trabajos que se estén ejecutando:

  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:

    Mensaje de estado del trabajo en curso

    La consola muestra los detalles del trabajo de Dataflow.

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

  1. Vaya a la página Trabajos de Dataflow en Console.

    Ir a la página Trabajos

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

    La consola muestra los detalles del trabajo de Dataflow.

Consulta 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 como se describió con anterioridad 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):

Ejemplo de recuento de errores junto al botón 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 muestra los registros del trabajo. Es posible que debas desplazarte para ver los errores.

  2. Identifica las entradas con el ícono de error Í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 Solucionar problemas de la canalizació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 Monitoring de la base de datos de Cloud Spanner en la consola. 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 Cloud Spanner.

Para especificar un límite en la cantidad de trabajadores de Dataflow, en lugar de usar la pestaña Importar/Exportar en la página de detalles de la instancia de tu base de datos de Cloud Spanner en la consola, debes iniciar la exportación con la plantilla de Cloud Spanner a Cloud Storage Avro y especificar la cantidad máxima de trabajadores como se describe a continuación:
  • Si usas la consola de Dataflow, el parámetro Cantidad máxima de trabajadores se encuentra en la sección Parámetros opcionales de la página Crear un trabajo a partir de una plantilla.

  • Si usas gcloud, 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
    

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 tus recursos de trabajo de Dataflow, la página de Dataflow del trabajo en Google Cloud Console muestra un ícono de advertencia Ícono de advertencia y mensajes de registro:

    Captura de pantalla de la advertencia de límite de cuota

    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.

  • Verifica 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 recursos de Spanner y el trabajo debería acelerarse, pero se te cobrarán 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 transmisiones de cambios

  • Ubicación de los datos: los datos se transfieren entre Spanner y Cloud Storage mediante 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.