Diagnosticar problemas de migraciones homogéneas a Cloud SQL para PostgreSQL

El proceso de la tarea de migración puede generar errores durante el tiempo de ejecución.

  • Algunos errores, como una contraseña incorrecta en la base de datos de origen, se pueden recuperar, lo que significa que se pueden corregir y la tarea de migración se reanuda automáticamente.
  • Algunos son irrecuperables, como los errores en la replicación de datos, lo que significa que la tarea de migración debe reiniciarse desde el principio.

Cuando se produce un error, el estado del trabajo de migración cambia a Failed y el subestado refleja el último estado antes del fallo.

Para solucionar un error, vaya al trabajo de migración fallido para ver el error y siga los pasos que se indican en el mensaje de error.

Para ver más detalles sobre el error, vaya a Cloud Monitoring mediante el enlace del trabajo de migración. Los registros se filtran para mostrar solo los de la tarea de migración específica.

En la siguiente tabla, puedes ver algunos ejemplos de problemas y cómo se pueden resolver:

Para este problema... El problema puede deberse a lo siguiente: Prueba esto...
Cuando migras a una instancia de destino que ya existe, recibes el siguiente mensaje de error: The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job. Tu instancia de Cloud SQL de destino contiene datos adicionales. Solo puedes migrar a instancias vacías. Consulta las limitaciones conocidas. Promueve tu instancia de destino para convertirla en una instancia de lectura y escritura, elimina los datos adicionales y vuelve a intentar la tarea de migración. Consulta Borrar datos adicionales de una instancia de destino.
No se ha podido conectar a la instancia de base de datos de origen. Ha habido un problema de conectividad entre la instancia de base de datos de origen y la de destino. Sigue los pasos que se indican en Depuración de la conectividad.
No se ha podido ejecutar la tarea de migración porque las versiones de las bases de datos de origen y destino no son compatibles. Las versiones de las bases de datos de origen y destino no forman una combinación compatible. En concreto, la versión de la base de datos de origen proporcionada no es compatible con la versión de la base de datos de destino. Comprueba que la versión de la base de datos de destino sea la misma o una versión superior a la de la base de datos de origen. A continuación, crea una tarea de migración.
Los lenguajes de definición de datos (DDLs) o los lenguajes de manipulación de datos (DMLs) están bloqueados en la fuente. Se bloquean los DDLs que requieren el ACCESS EXCLUSIVE bloqueo y se ejecutan durante la fase de volcado completo.

Durante el proceso de sincronización inicial (volcado completo), se deben evitar en las tablas los DDLs o los programas que requieran ACCESS EXCLUSIVE bloqueos, como ALTER TABLE o DROP TABLE. De lo contrario, los DDLs o los programas esperarán a que finalice la sincronización inicial.

Por ejemplo, si una tabla aún está en el proceso de sincronización inicial y se ejecuta un comando ALTER TABLE en la misma tabla, el comando no se ejecutará y se bloquearán los comandos DDL y DML posteriores hasta que finalice la sincronización inicial.
Mensaje de error: No pglogical extension installed on databases (X) Una o varias bases de datos de origen no tienen instalado pglogical. Sigue estas directrices para instalar pglogical en las bases de datos de la instancia de origen.
Al migrar a la versión 15 de PostgreSQL, después de varios intentos de conexión posteriores, se produce uno de los siguientes síntomas: Este problema suele atribuirse al problema de interbloqueo de la extensión pglogical. Para obtener más información, consulta el gestor de problemas de pglogical en GitHub. Vuelve a intentar el trabajo de migración o migra primero a una versión intermedia de PostgreSQL. Para obtener más información, consulta Mensaje de error: Cannot connect to invalid database.
Mensaje de error: Replication user 'x' doesn't have sufficient privileges. El usuario que está usando Database Migration Service no tiene los privilegios necesarios para realizar la operación designada. Sigue estas directrices para asegurarte de que este usuario tenga los privilegios necesarios.
Mensaje de error: Unable to connect to source database server. El servicio de migración de bases de datos no puede establecer una conexión con el servidor de bases de datos de origen. Asegúrate de que las instancias de la base de datos de origen y de destino puedan comunicarse entre sí y de que hayas completado todos los requisitos previos que aparecieron cuando definiste los ajustes de la tarea de migración.
Mensaje de error: The source database 'wal_level' configuration must be equal to 'logical'. El valor de wal_level de la base de datos de origen es distinto de logical. Define wal_level en logical.
Mensaje de error: The source database 'max_replication_slots' configuration is not sufficient. El parámetro max_replication_slots no se ha configurado correctamente. Sigue estas directrices para definir este parámetro correctamente.
Mensaje de error: The source database 'max_wal_senders' configuration is not sufficient. El parámetro max_wal_senders no se ha configurado correctamente. Sigue estas directrices para definir este parámetro correctamente.
Mensaje de error: The source database 'max_worker_processes' configuration is not sufficient. El parámetro max_worker_processes no se ha configurado correctamente. Sigue estas directrices para definir este parámetro correctamente.

Mensaje de error: Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.

O

Mensaje de error: Error promoting EM replica: finished drop replication with errors.

Los ajustes necesarios para la replicación no se pueden limpiar durante la promoción de una tarea de migración.

En cada base de datos, ejecuta los comandos como usuario con el privilegio superuser.

Para obtener más información sobre los comandos que debes ejecutar, consulta Limpiar ranuras de replicación.

Mensaje de error: x509 certificate signed by unknown authority.

El certificado de AC de origen proporcionado al servicio de migración de bases de datos puede contener solo el certificado raíz. Sin embargo, el certificado de origen requiere tanto el certificado raíz como los certificados intermedios.

Por ejemplo, en Amazon Relational Database Service, usar el certificado rds-ca-2019-root.pem puede provocar este problema.

Crea un certificado de AC de origen combinado que contenga el certificado raíz y todos los certificados intermedios necesarios.

En el caso práctico de Amazon Relational Database Service, en lugar del certificado rds-ca-2019-root.pem, usa el certificado rds-combined-ca-bundle.pem.

Mensaje de error: ERROR: Out of shared memory HINT: You might need to increase max_locks_per_transaction.

El valor definido para el parámetro max_locks_per_transaction no es suficiente. El valor de este parámetro debe ser al menos {max_number_of_tables_per_database}/(max_connections + max_prepared_transactions).

Mensaje de error: ERROR: no data left in message.

El paquete pglogical no está instalado correctamente en la instancia de origen. Para obtener más información sobre cómo instalar este paquete correctamente, consulta Instalar el paquete pglogical en la instancia de origen.

Mensaje de error: Cannot assign TransactionIds during recovery.

La fuente configurada está en modo Recovery. Configura una fuente que no esté en modo de recuperación.
El volcado completo es lento. El destino de Cloud SQL puede tardar en importar grandes cantidades de datos de la base de datos de origen.
  • Al crear el destino, define el tamaño del disco de datos de forma que se aproxime al tamaño final. La fase de volcado completo usa una carga de trabajo intensiva de escritura de E/S, y un disco de mayor tamaño tiene un mejor rendimiento de E/S. Para obtener más información, consulta Rendimiento del almacenamiento en bloque.
  • Elige un nivel superior para el destino de Cloud SQL para obtener el ancho de banda de red y de disco máximo disponible.
  • Ajusta la marca max_wal_size de Cloud SQL de destino. Normalmente, 32 o 64 GB es un buen valor para esta marca. Para actualizar este indicador, no es necesario reiniciar el servidor.
Mensaje de error: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

La tarea de migración ha fallado durante la fase de volcado completo y no se puede recuperar. La instancia de la base de datos de origen se ha reiniciado o está en modo de recuperación, o bien las conexiones de replicación han finalizado porque no se ha definido un valor suficiente para el parámetro wal_sender_timeout.

Para encontrar la causa principal del problema, haz lo siguiente:

  1. Ve a la página Explorador de registros de la Google Cloud consola.
  2. En la lista de recursos, selecciona tu réplica de Cloud SQL. Aparecerá una lista de los registros más recientes de la réplica.
  3. En los nombres de los archivos de registro, selecciona postgres.log.
  4. Define el nivel de gravedad del registro en todos los niveles superiores a Warning. Los primeros registros de errores pueden ser la causa principal del fallo.
  • Asegúrate de que Database Migration Service siempre pueda conectarse a la instancia de base de datos de origen durante la fase de volcado completo.
  • Comprueba si el valor del parámetro wal_sender_timeout se ha definido en un número mayor (por ejemplo, 0) en la instancia de la base de datos de origen.
  • Reinicia la tarea de migración y vuelve a intentarlo.
Mensaje de error: ERROR: unknown column name {column_name}

Se ha añadido una columna a una tabla replicada en el nodo principal, pero no en el nodo de réplica.

Durante las migraciones continuas, solo se actualizan automáticamente los cambios del lenguaje de manipulación de datos (DML). El usuario es el responsable de gestionar los cambios del lenguaje de definición de datos (DDL) para que las bases de datos de origen y de destino sigan siendo compatibles. Para ello, puede usar dos métodos:

  • Deteniendo las operaciones de escritura en la base de datos de origen y ejecutando los comandos de DDL en el origen y en el destino. Antes de ejecutar los comandos de DDL en el destino, concede el rol cloudsqlexternalsync al usuario de Cloud SQL que vaya a aplicar los cambios en el DDL.
  • Usa pglogical.replicate_ddl_command para permitir que los comandos DDL se ejecuten en el origen y en el destino en un punto coherente. El usuario que ejecute los comandos debe tener el mismo nombre de usuario en el origen y en el destino, y debe ser el superusuario o el propietario del artefacto que se va a migrar (por ejemplo, la tabla, la secuencia, la vista o la base de datos).

    • Consulta Migración continua para ver ejemplos de uso de pglogical.replicate_ddl_command..
Mensaje de error: ERROR: cannot truncate a table referenced in a foreign key constraint

El usuario ha intentado truncar una tabla que tiene una restricción de clave externa.

Primero, elimina la restricción de clave externa y, después, trunca la tabla.
Mensaje de error: ERROR: connection to other side has died

La conexión de replicación ha finalizado porque se ha establecido un valor insuficiente para wal_sender_timeout parameter. El error suele producirse durante la fase de replicación, después de que se haya completado la copia inicial.

Aumenta el valor del parámetro wal_sender_timeout o inhabilita el mecanismo de tiempo de espera asignando el valor 0 a la instancia de la base de datos de origen.
Mensaje de advertencia: migration job test configuration has returned the following warnings: Some table(s) have limited support.

La fuente tiene tablas con compatibilidad limitada, como tablas sin claves principales.

Este es un mensaje de advertencia. Puedes continuar con la migración, pero ten en cuenta que las entidades no admitidas (por ejemplo, las tablas sin claves principales) no se migrarán. Para obtener más información, consulta el artículo Configurar las bases de datos de origen.

Cuando migras bases de datos seleccionadas y la tarea de migración no puede replicar datos en una o varias bases de datos, se muestra el estado Error en la lista de bases de datos. Se han producido varios errores en las tareas de migración.

En la columna Errores, haga clic en Ver errores y corríjalos. También puedes quitar las bases de datos que no se hayan migrado de la tarea de migración.

Para obtener más información sobre cómo quitar una base de datos fallida de una tarea de migración, consulta Gestionar tareas de migración.

Borrar datos adicionales de tu instancia de destino

Cuando migras a una instancia de destino que ya existe, recibes el siguiente mensaje de error: The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job.

Este problema puede producirse si su instancia de destino contiene datos adicionales. Solo puedes migrar a instancias vacías. Consulta las limitaciones conocidas.

Cosas que puedes probar

Borra los datos adicionales de la instancia de destino y vuelve a iniciar la tarea de migración siguiendo estos pasos:

  1. Detener la tarea de migración.
  2. En este punto, la instancia de Cloud SQL de destino está en modo `read-only`. Promueve la instancia de destino para obtener acceso de escritura.
  3. Conéctate a tu instancia de Cloud SQL de destino.
  4. Elimina los datos adicionales de las bases de datos de la instancia de destino. El destino solo puede contener datos de configuración del sistema. Las bases de datos de destino no pueden contener datos de usuario (como tablas). Hay diferentes instrucciones SQL que puedes ejecutar en tus bases de datos para encontrar datos que no sean del sistema. Por ejemplo:

    Ejemplo de instrucción SQL para obtener bases de datos que no sean del sistema (haga clic para ampliar)

    SELECT datname FROM pg_catalog.pg_database
WHERE datname NOT IN ('cloudsqladmin', 'template1', 'template0', 'postgres');

    Ejemplo de instrucción SQL para obtener datos que no son del sistema en la base de datos postgres (haz clic para ampliar)

    La base de datos postgres es una base de datos del sistema, pero puede contener datos que no sean del sistema. Asegúrate de ejecutar estas instrucciones en la base de datos postgres. Si usas el cliente psql para conectarte a la instancia de destino, puedes cambiar a otra base de datos sin restablecer la conexión mediante el comando \connect {database_name_here}.

    SELECT table_schema, table_name FROM information_schema.tables
WHERE table_schema != 'information_schema' AND table_schema not like 'pg\_%';

SELECT routine_schema, routine_name FROM information_schema.routines
WHERE routine_schema != 'information_schema' AND routine_schema not like 'pg\_%';

SELECT extname FROM pg_extension WHERE extname != 'plpgsql';
  5. Inicia la tarea de migración.

Limpiar las ranuras de replicación

Aparece uno de los siguientes mensajes:

  • Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.
  • Error promoting EM replica: finished drop replication with errors.

El problema puede deberse a lo siguiente:

Cuando se asciende una instancia de Cloud SQL, si no se puede acceder a la instancia de origen desde la instancia de Cloud SQL (por ejemplo, si la instancia de origen no está en ejecución o si has quitado la instancia de Cloud SQL de la lista de permitidos de instancias de origen), no se pueden limpiar los ajustes necesarios para la replicación durante el ascenso de una tarea de migración. Debes limpiar los slots de replicación manualmente.

Cosas que puedes probar

En cada base de datos, ejecuta los siguientes comandos como usuario con el privilegio superuser:

  1. Obtén los nombres de las ranuras de replicación del mensaje de error y, a continuación, ejecuta el siguiente comando para eliminar las ranuras una por una:

    select pg_drop_replication_slot({slot_name});

  2. Si los nombres de las ranuras de replicación no están disponibles en el mensaje de error, ejecuta el siguiente comando para consultar las ranuras de replicación que ya existen:

    select pg_drop_replication_slot(slot_name) from pg_replication_slots where slot_name like '%cloudsql%' and active = 'f';

  3. Si no hay réplicas de Cloud SQL que usen la instancia de origen, ejecuta el siguiente comando para limpiar los ajustes de pglogical:

    select pglogical.drop_node(node_name) from pglogical.node where node_name like 'cloudsql';

  4. Si ya no necesitas la extensión pglogical, ejecuta el siguiente comando para desinstalarla:

    DROP EXTENSION IF EXISTS pglogical;

Mensaje de error: Cannot connect to invalid database

Al migrar a la versión 15 de PostgreSQL, después de varios intentos de conexión posteriores, se produce uno de los siguientes síntomas:

El problema puede deberse a lo siguiente:

Este problema suele atribuirse al problema de interbloqueo de la extensión pglogical. Para obtener más información, consulta el gestor de incidencias de pglogical en GitHub.

Cosas que puedes probar

Volver a realizar la tarea de migración con una nueva instancia de destino

Prueba a eliminar la base de datos de destino en la que has tenido el problema y vuelve a crear la tarea de migración. Sigue estos pasos:

  1. Elimina la instancia de destino en la que has tenido problemas. Consulta Eliminar instancias en la documentación de Cloud SQL para PostgreSQL.
  2. Elimina la tarea de migración fallida. Consulta Revisar una tarea de migración.
  3. Vuelve a crear la tarea de migración. Consulta Crear una tarea de migración.

Migrar a una versión intermedia

Considera la posibilidad de migrar a una versión anterior de PostgreSQL, como PostgreSQL 14. Una vez que la migración se haya completado correctamente, puedes probar a actualizar a la instancia de PostgreSQL 15 que quieras. Consulta Actualizar la versión principal de la base de datos migrando datos en la documentación de Cloud SQL para PostgreSQL.

Gestionar usuarios y roles

Migrar usuarios

Actualmente, Database Migration Service no admite la migración de usuarios de una instancia de origen a una instancia de Cloud SQL de destino. Puedes gestionar esta migración creando los usuarios en Cloud SQL manualmente.

Acerca del usuario cloudsqlexternalsync

Durante la migración, todos los objetos de la réplica de Cloud SQL son propiedad del usuario cloudsqlexternalsync. Una vez que se hayan migrado los datos, puede modificar la propiedad de los objetos y asignársela a otros usuarios siguiendo estos pasos:

  • Ejecuta el comando GRANT cloudsqlexternalsync to {USER}.
  • En cada base de datos, ejecuta el comando reassign owned by cloudsqlexternalsync to {USER};.
  • Para quitar el usuario cloudsqlexternalsync, ejecuta el comando drop role cloudsqlexternalsync.

Importar datos en una instancia de Cloud SQL nueva

Si primero exportas datos de una instancia de Cloud SQL que Database Migration Service ha migrado a Cloud Storage y, a continuación, importas los datos de Cloud Storage a una instancia de Cloud SQL independiente, es posible que la importación falle porque el usuario cloudsqlexternalsync no existe en la instancia de destino.

Para mitigar el problema, crea el usuario cloudsqlexternalsync en la instancia de destino o elimina el usuario de la instancia migrada.