Plantilla de Sourcedb a Spanner

La plantilla de SourceDB a Spanner es una canalización por lotes que copia los datos de una base de datos relacional a una base de datos de Spanner existente. Esta canalización utiliza JDBC para conectarse a las bases de datos relacionales. Puedes usar esta plantilla para copiar datos desde cualquier base de datos relacional con controladores de JDBC disponibles en Spanner. Solo admite un conjunto limitado de tipos de MySQL.

Para obtener una capa adicional de protección, también puedes pasar una clave de Cloud KMS junto con un nombre de usuario, contraseña y parámetros de cadena de conexión codificados en Base64 encriptados con la clave de Cloud KMS. Consulta el extremo de encriptación de la API de Cloud KMS para obtener más información acerca de cómo encriptar los parámetros de nombre de usuario, contraseña y cadena de conexión.

Requisitos de la canalización

  • Los controladores de JDBC de la base de datos relacional deben estar disponibles.
  • Las tablas de Spanner deben existir antes de ejecutar la canalización.
  • Las tablas de Spanner deben tener un esquema compatible.
  • La base de datos relacional debe ser accesible desde la subred en la que se ejecuta Dataflow.

Parámetros de la plantilla

Parámetros obligatorios

  • sourceConfigURL: Es la URL del archivo de configuración de la conexión de origen. El formato de archivo depende del tipo de fuente. En el caso de Astra, apuntará a un archivo de configuración de conexión de Astra (muestra). Para JDBC, apuntará a un archivo de configuración de fragmentación de JDBC (ejemplo). En el caso de Cassandra, apuntará a un archivo de configuración del controlador de Cassandra (ejemplo). Este parámetro es obligatorio. Por ejemplo, gs://your-bucket/source-config.json. La configuración predeterminada es vacía.
  • instanceId: Es la instancia de destino de Cloud Spanner.
  • databaseId: Es la base de datos de destino de Cloud Spanner.
  • projectId: Este es el nombre del proyecto de Cloud Spanner.
  • outputDirectory: Este directorio se usa para volcar los registros con errores, omitidos o filtrados en una migración.

Parámetros opcionales

  • sourceDbDialect: Los valores posibles son CASSANDRA, MYSQL, POSTGRESQL, ORACLE y SQLSERVER. La configuración predeterminada es MYSQL.
  • jdbcDriverJars: Es la lista separada por comas de los archivos JAR del controlador. Por ejemplo, gs://your-bucket/driver_jar1.jar,gs://your-bucket/driver_jar2.jar La configuración predeterminada es vacía.
  • jdbcDriverClassName: Es el nombre de la clase del controlador de JDBC. Por ejemplo, com.mysql.jdbc.Driver La configuración predeterminada es com.mysql.jdbc.Driver.
  • tables: Son las tablas que se migrarán desde la fuente. La configuración predeterminada es vacía.
  • numPartitions: Es la cantidad de particiones. Esto, junto con el límite inferior y superior, forma segmentaciones de particiones para las expresiones de cláusula WHERE generadas que se usan para dividir la columna de partición de manera uniforme. Cuando la entrada es menor que 1, se establece el número en 1. La configuración predeterminada es 0.
  • fetchSize: Es la cantidad de filas que se recuperarán por página leída para la fuente de JDBC. Si no se establece, se infiere automáticamente a partir del tipo de máquina de trabajador y el tamaño estimado de la fila, y se recurre a 50,000 filas si no se puede inferir (por ejemplo, cuando no se especifica el tipo de máquina de trabajador). Si el dialecto de origen es Mysql, consulta la nota que aparece a continuación. En última instancia, esto se tradujo en la llamada a Statement.setFetchSize en la capa de JDBC. SOLO se debe usar si el valor predeterminado arroja errores de memoria.Nota para la fuente de MySql: El conector de Mysql ignora FetchSize, a menos que useCursorFetch=true también forme parte de las propiedades de conexión. Para el dialecto de MySql, la canalización agregará useCursorFetch=true a las propiedades de conexión de forma predeterminada, a menos que el parámetro fetchSize se establezca de forma explícita en 0.
  • spannerHost: Es el extremo de Cloud Spanner al que se llamará en la plantilla. Por ejemplo, https://batch-spanner.googleapis.com La configuración predeterminada es https://batch-spanner.googleapis.com.
  • maxConnections: Configura el grupo de conexiones de JDBC en cada trabajador con la cantidad máxima de conexiones. Usa un número negativo para no tener límite. Por ejemplo, -1 La configuración predeterminada es 0.
  • sessionFilePath: Es la ruta del archivo de sesión en Cloud Storage que contiene información de asignación de la herramienta de migración de Spanner. La configuración predeterminada es vacía.
  • transformationJarPath: Es la ubicación de archivo JAR personalizada en Cloud Storage que contiene la lógica de transformación personalizada para procesar registros. La configuración predeterminada es vacía.
  • transformationClassName: Es el nombre de clase completamente calificado que tiene la lógica de transformación personalizada. Es un campo obligatorio en caso de que se especifique transformJarPath. La configuración predeterminada es vacía.
  • transformationCustomParameters: Es la cadena que contiene cualquier parámetro personalizado que se pasará a la clase de transformación personalizada. La configuración predeterminada es vacía.
  • insertOnlyModeForSpannerMutations: De forma predeterminada, la canalización usa Upserts para escribir filas en Spanner. Esto significa que se reemplazarían las filas existentes. Si se habilita el modo InsertOnly, se usarán inserciones en lugar de actualizaciones o inserciones, y no se reemplazarán las filas existentes.
  • batchSizeForSpannerMutations: Es el tamaño del lote en bytes para las mutaciones de Spanner. Si se establece en menos de 0, se usa el valor predeterminado de SpannerIO de Apache Beam, que es de 1 MB. Establece este valor en 0 o 10 para inhabilitar las mutaciones por lotes.
  • spannerPriority: Es la prioridad de solicitud para las llamadas de Cloud Spanner. El valor debe ser uno de los siguientes: [HIGH,MEDIUM,LOW]. El valor predeterminado es HIGH.
  • tableOverrides: Son las anulaciones de nombres de tablas de origen a Spanner. Se escriben en el siguiente formato: [{SourceTableName1, SpannerTableName1}, {SourceTableName2, SpannerTableName2}]. En este ejemplo, se muestra la asignación de la tabla Singers a Vocalists y de la tabla Albums a Records. Por ejemplo, [{Singers, Vocalists}, {Albums, Records}] La configuración predeterminada es vacía.
  • columnOverrides: Son las anulaciones de nombres de columnas de origen a Spanner. Se escriben con el siguiente formato: [{SourceTableName1.SourceColumnName1, SourceTableName1.SpannerColumnName1}, {SourceTableName2.SourceColumnName1, SourceTableName2.SpannerColumnName1}]. Ten en cuenta que SourceTableName debe ser el mismo en el par de origen y Spanner. Para anular los nombres de las tablas, usa tableOverrides.En el ejemplo, se muestra la asignación de SingerName a TalentName y de AlbumName a RecordName en las tablas Singers y Albums, respectivamente. Por ejemplo, [{Singers.SingerName, Singers.TalentName}, {Albums.AlbumName, Albums.RecordName}] La configuración predeterminada es vacía.
  • schemaOverridesFilePath: Es un archivo que especifica las anulaciones de nombres de tablas y columnas de la fuente a Spanner. La configuración predeterminada es vacía.
  • uniformizationStageCountHint: Es una sugerencia para la cantidad de etapas de uniformización. Actualmente, solo se aplica a fuentes basadas en JDBC, como MySQL o PostgreSQL. Deja 0 o el valor predeterminado para inhabilitar la uniformización. Establece en -1 para una cantidad de etapas de log(numPartition). Si el espacio de clave primaria de origen se distribuye de manera uniforme (por ejemplo, una clave de incremento automático con espacios dispersos), se basa en dejarlo inhabilitado. Si tu espacio de claves no es uniforme, es posible que encuentres una VM rezagada en tu ejecución de Dataflow. En ese caso, puedes establecerlo en -1 para habilitar la uniformización. Establecerlo de forma manual en valores distintos de 0 o -1 te ayudaría a ajustar el equilibrio entre la sobrecarga que agregan las etapas de uniformización y la mejora del rendimiento debido a una mejor distribución del trabajo.
  • failureInjectionParameter: Es el parámetro de inyección de fallas. Solo se usa para pruebas. La configuración predeterminada es vacía.
  • maxCommitDelay: Es el tiempo máximo de retraso de confirmación para optimizar la capacidad de procesamiento de escritura en Spanner. Referencia https://cloud.google.com/spanner/docs/throughput-optimized-writes.Set -1 para permitir que Spanner elija el valor predeterminado. Establece un valor positivo para anular la mejor compensación entre la capacidad de procesamiento y la latencia.El valor predeterminado es -1.
  • gcsOutputDirectory: Este directorio se usa para escribir los archivos AVRO de los registros que se leen desde la fuente. Por ejemplo, gs://your-bucket/your-path La configuración predeterminada es vacía.
  • disabledAlgorithms: Algoritmos separados por comas que se deben inhabilitar. Si este valor se establece como none, no se inhabilita ningún algoritmo. Ten cuidado con este parámetro, ya que los algoritmos inhabilitados de forma predeterminada podrían tener vulnerabilidades o problemas de rendimiento. Por ejemplo, SSLv3, RC4.
  • extraFilesToStage: Rutas de Cloud Storage separadas por comas o Secrets de Secret Manager para los archivos que se deben almacenar en etapa intermedia en el trabajador. Estos archivos se guardan en el directorio /extra_files en cada trabajador. Por ejemplo, gs://<BUCKET_NAME>/file.txt,projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<VERSION_ID>

Ejecuta la plantilla

Console

  1. Ve a la página Crear un trabajo a partir de una plantilla de Dataflow.
  2. Ir a Crear un trabajo a partir de una plantilla
  3. En el campo Nombre del trabajo, ingresa un nombre de trabajo único.
  4. Opcional: Para Extremo regional, selecciona un valor del menú desplegable. La región predeterminada es us-central1.

    Para obtener una lista de regiones en las que puedes ejecutar un trabajo de Dataflow, consulta Ubicaciones de Dataflow.

  5. En el menú desplegable Plantilla de Dataflow, selecciona la plantilla Sourcedb to Spanner.
  6. En los campos de parámetros proporcionados, ingresa los valores de tus parámetros.
  7. Haz clic en Ejecutar trabajo.

gcloud CLI

En tu shell o terminal, ejecuta la plantilla:

gcloud dataflow flex-template run JOB_NAME \
    --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Sourcedb_to_Spanner_Flex \
    --project=PROJECT_ID \
    --region=REGION_NAME \
    --parameters \
       sourceConfigURL=SOURCE_CONFIG_URL,\
       instanceId=INSTANCE_ID,\
       databaseId=DATABASE_ID,\
       projectId=PROJECT_ID,\
       outputDirectory=OUTPUT_DIRECTORY,\

Reemplaza lo siguiente:

  • JOB_NAME: Es el nombre del trabajo que elijas
  • VERSION: Es la versión de la plantilla que deseas usar.

    Puedes usar los siguientes valores:

    • latest para usar la última versión de la plantilla, que está disponible en la carpeta superior non-dated en el bucket: gs://dataflow-templates/latest/
    • el nombre de la versión, como 2023-09-12-00_RC00, para usar una versión específica de la plantilla, que se puede encontrar anidada en la carpeta superior con fecha correspondiente en el bucket: gs://dataflow-templates/
  • REGION_NAME: La región en la que deseas implementar tu trabajo de Dataflow, por ejemplo, us-central1
  • SOURCE_CONFIG_URL: La URL para conectarse al host de la base de datos de origen. Puede ser cualquiera de las siguientes opciones: La URL de conexión de JDBC, que debe contener el host, el puerto y el nombre de la base de datos de origen y, de forma opcional, puede contener propiedades como autoReconnect, maxReconnects, etc. Formato: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. La ruta de acceso de configuración del fragmento
  • INSTANCE_ID: El ID de la instancia de Cloud Spanner.
  • DATABASE_ID: El ID de la base de datos de Cloud Spanner.
  • PROJECT_ID: El ID del proyecto de Cloud Spanner.
  • OUTPUT_DIRECTORY: El directorio de salida para los eventos con errores, omitidos o filtrados.

API

Para ejecutar la plantilla con la API de REST, envía una solicitud POST HTTP. Para obtener más información de la API y sus permisos de autorización, consulta projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
{
   "launchParameter": {
     "jobName": "JOB_NAME",
     "parameters": {
       "sourceConfigURL": "SOURCE_CONFIG_URL",
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "projectId": "PROJECT_ID",
       "outputDirectory": "OUTPUT_DIRECTORY",
     },
     "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Sourcedb_to_Spanner_Flex",
     "environment": { "maxWorkers": "10" }
  }
}

Reemplaza lo siguiente:

  • PROJECT_ID: el ID del proyecto de Google Cloud en el que deseas ejecutar el trabajo de Dataflow
  • JOB_NAME: Es el nombre del trabajo que elijas
  • VERSION: Es la versión de la plantilla que deseas usar.

    Puedes usar los siguientes valores:

    • latest para usar la última versión de la plantilla, que está disponible en la carpeta superior non-dated en el bucket: gs://dataflow-templates/latest/
    • el nombre de la versión, como 2023-09-12-00_RC00, para usar una versión específica de la plantilla, que se puede encontrar anidada en la carpeta superior con fecha correspondiente en el bucket: gs://dataflow-templates/
  • LOCATION: La región en la que deseas implementar tu trabajo de Dataflow, por ejemplo, us-central1
  • SOURCE_CONFIG_URL: La URL para conectarse al host de la base de datos de origen. Puede ser cualquiera de las siguientes opciones: La URL de conexión de JDBC, que debe contener el host, el puerto y el nombre de la base de datos de origen y, de forma opcional, puede contener propiedades como autoReconnect, maxReconnects, etc. Formato: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. La ruta de acceso de configuración del fragmento
  • INSTANCE_ID: El ID de la instancia de Cloud Spanner.
  • DATABASE_ID: El ID de la base de datos de Cloud Spanner.
  • PROJECT_ID: El ID del proyecto de Cloud Spanner.
  • OUTPUT_DIRECTORY: El directorio de salida para los eventos con errores, omitidos o filtrados.