Diagnostica problemas en las migraciones de PostgreSQL a AlloyDB para PostgreSQL

El proceso del trabajo 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, son recuperables, lo que significa que se pueden corregir y el trabajo de migración se reanuda automáticamente.
  • Algunos son irrecuperables, como los daños en los datos o las incompatibilidades de esquemas, lo que significa que el trabajo 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 de la falla.

Para solucionar problemas, navega al trabajo de migración con errores para ver el error y sigue los pasos que se indican en el mensaje de error.

Para ver más detalles sobre el error, navega a Cloud Monitoring con el vínculo del trabajo de migración. Los registros se filtran según el trabajo de migración específico.

En la siguiente tabla, se enumeran los problemas habituales y sus soluciones:

Situación Posible problema Solución
Cuando migras a un clúster de destino existente, recibes el siguiente mensaje de error: The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job. Tu clúster de destino de AlloyDB para PostgreSQL contiene datos de usuario adicionales. Solo puedes migrar a clústeres existentes que estén vacíos. Consulta Limitaciones conocidas. Borra los datos adicionales o en conflicto de tu clúster de destino y vuelve a intentar el trabajo de migración. Consulta Borra los datos adicionales de tu clúster de destino existente.
No se pudo establecer conexión con la instancia de la base de datos de origen. Hubo un problema de conectividad entre la instancia de la base de datos de origen y el clúster de AlloyDB para PostgreSQL de destino. Sigue los pasos que se indican en Cómo depurar la conectividad.
No se pudo ejecutar el trabajo de migración debido a que las versiones de las bases de datos de origen y de destino no son compatibles. Las versiones de la base de datos de origen y de destino no son una combinación compatible. Específicamente, 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. Asegúrate de que la versión de la base de datos de destino sea la misma o una versión principal compatible posterior a la versión de la base de datos de origen. Luego, crea un trabajo de migración nuevo.
Los lenguajes de definición de datos (DDL) o los lenguajes de manipulación de datos (DML) están bloqueados en la fuente. Se bloquean las DDL que requieren el bloqueo ACCESS EXCLUSIVE y que se ejecutan durante la fase de volcado completo.

Durante el proceso de sincronización inicial (volcado completo), se deben evitar los DDL o los programas que requieran bloqueos de ACCESS EXCLUSIVE, como ALTER TABLE o DROP TABLE, en las tablas. De lo contrario, los DDL o los programas esperan hasta 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 los comandos DDL y DML posteriores se bloquearán hasta que finalice la sincronización inicial.
Mensaje de error: No pglogical extension installed on databases (X) Una o más bases de datos de origen no tienen instalado pglogical. Sigue estos lineamientos para instalar pglogical en las bases de datos de la instancia de origen.
Cuando migras a la versión 15 de PostgreSQL, después de varios intentos de reintento de conexión posteriores, se produce uno de los siguientes síntomas: Este problema suele atribuirse al interbloqueo en la extensión pglogical. Para obtener más información, consulta la Herramienta de seguimiento de errores 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 detalles, consulta Mensaje de error: Cannot connect to invalid database.
Mensaje de error: Replication user 'x' doesn't have sufficient privileges. El usuario que usa Database Migration Service no tiene los privilegios necesarios para realizar la operación designada. Sigue estos lineamientos para asegurarte de que este usuario tenga los privilegios necesarios.
Mensaje de error: Unable to connect to source database server. Database Migration Service no puede establecer una conexión con el servidor de la base de datos de origen. Asegúrate de que las instancias de 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 la configuración del trabajo de migración.
Mensaje de error: The source database 'wal_level' configuration must be equal to 'logical'. El wal_level de la base de datos de origen se establece en un valor distinto de logical. Establece wal_level en “logical”. Consulta Configuración del nivel de WAL.
Mensaje de error: The source database 'max_replication_slots' configuration is not sufficient. El parámetro max_replication_slots no se configuró correctamente. Sigue estos lineamientos para configurar 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 configuró correctamente. Sigue estos lineamientos para configurar 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 configuró correctamente. Sigue estos lineamientos para configurar 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.

La configuración necesaria para la replicación no se puede limpiar durante el ascenso de un trabajo de migración.

Para cada base de datos, ejecuta comandos como un usuario con el privilegio superuser.

Para obtener más información sobre qué comandos ejecutar, consulta Cómo limpiar las ranuras de replicación.

Mensaje de error: x509 certificate signed by unknown authority.

Es posible que el certificado de la AC de origen proporcionado a Database Migration Service solo contenga el certificado raíz. Sin embargo, el certificado de origen requiere tanto el certificado raíz como cualquier certificado intermedio.

Por ejemplo, en el caso de Amazon RDS, usar un certificado raíz independiente en lugar de un paquete de certificados podría causar este problema.

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

Para las fuentes de Amazon RDS, usa un paquete de certificados que incluya los certificados intermedios y raíz. Para obtener más información, consulta Descarga paquetes de certificados en la documentación de Amazon RDS.

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

El valor establecido para el parámetro max_locks_per_transaction no es suficiente. Establece el valor de este parámetro en, 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 Configura tu base de datos de origen.

Mensaje de error: Cannot assign TransactionIds during recovery.

La fuente configurada está en modo de recuperación. Configura una fuente que no esté en modo de recuperación.
El volcado completo es lento. La instancia principal del clúster de destino de AlloyDB para PostgreSQL puede tardar en importar datos grandes de la base de datos de origen.
  • Elige un nivel de máquina más alto para la instancia principal de AlloyDB para PostgreSQL de destino para obtener el ancho de banda de red y la capacidad de CPU máximos disponibles.
  • Ajusta la marca max_wal_size del destino. Por lo general, 32 GB o 64 GB es un buen valor para establecer en esta marca. No es necesario que reinicies el servidor de la base de datos para actualizar esta marca.
Mensaje de error: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

Se produjo un error en el trabajo de migración durante la fase de volcado completo y no se puede recuperar. La instancia de la base de datos de origen se reinició o estaba en modo de recuperación, o las conexiones de replicación finalizaron debido a un valor insuficiente establecido para el parámetro wal_sender_timeout.

Para encontrar la causa raíz del problema, haz lo siguiente:

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

Se agregó una columna a una tabla replicada en el nodo principal, pero no en el nodo de réplica.

Solo los cambios en el lenguaje de manipulación de datos (DML) se actualizan automáticamente durante las migraciones continuas. Debes administrar los cambios en el lenguaje de definición de datos (DDL) para que las bases de datos de origen y destino sigan siendo compatibles. Puedes lograrlo de dos maneras:

  • Detén las operaciones de escritura en la base de datos de origen y ejecuta los comandos de DDL en el origen y el destino. Antes de ejecutar los comandos de DDL en el destino, otorga el rol alloydbexternalsync al usuario de AlloyDB para PostgreSQL que aplica los cambios de DDL.
  • Usa pglogical.replicate_ddl_command para permitir que los comandos de DDL se ejecuten en el origen y el destino en un punto coherente. El usuario que ejecuta los comandos debe tener el mismo nombre de usuario tanto en el origen como en el destino, y debe ser el superusuario o el propietario del artefacto que se migra (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

Un usuario intentó truncar una tabla que tiene una restricción de clave externa.

Primero, quita la restricción de clave externa y, luego, trunca la tabla.
Mensaje de error: ERROR: connection to other side has died

La conexión de replicación finalizó debido a que se estableció un valor insuficiente para el parámetro wal_sender_timeout. Por lo general, el error se produce durante la fase de replicación después de que se completa correctamente el volcado inicial.

Considera aumentar el valor del parámetro wal_sender_timeout o inhabilitar el mecanismo de tiempo de espera estableciendo su valor en 0 en 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, por ejemplo, tablas sin claves primarias.

Este es un mensaje de advertencia. Puedes continuar con la migración, pero ten en cuenta que, en las migraciones estándar, las tablas sin claves primarias solo replican la instantánea inicial y las sentencias INSERT durante la fase de captura de datos modificados (CDC); las sentencias UPDATE y DELETE no se replican. Para obtener más información, consulta Configura tu base de datos de origen.

Cuando migras las bases de datos seleccionadas y el trabajo de migración no puede replicar datos en una o más bases de datos, se muestra el estado Con errores en la lista de bases de datos. Varios errores de trabajos de migración.

En la columna Errores, haz clic en Ver errores y corrígelos. También puedes quitar las bases de datos con errores del trabajo de migración.

Para obtener más información sobre cómo quitar una base de datos con errores de un trabajo de migración, consulta Administra trabajos de migración.

Borra los datos adicionales de tu clúster de destino existente

Cuando migras a un clúster de destino existente, recibes el siguiente mensaje de error: The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job.

Este problema puede ocurrir si tu clúster de destino contiene datos adicionales. Solo puedes migrar a clústeres existentes que estén vacíos. Consulta Limitaciones conocidas.

Solución

Borra los datos adicionales o en conflicto de tu clúster de destino y vuelve a iniciar el trabajo de migración siguiendo estos pasos:

  1. Detén el trabajo de migración.
  2. Conéctate a la instancia principal del clúster de AlloyDB para PostgreSQL de destino con psql o AlloyDB Studio.
  3. Quita los datos adicionales de las bases de datos del clúster de destino. Tu destino solo puede contener datos de configuración del sistema. Las bases de datos de destino no pueden contener datos del usuario (como tablas o rutinas definidas por el usuario). Existen diferentes sentencias de SQL que puedes ejecutar en tus bases de datos para encontrar datos que no sean del sistema:

    Ejemplo de instrucción de SQL para recuperar bases de datos que no son del sistema (haz clic para expandir)

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

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

    La base de datos postgres es una base de datos del sistema, pero puede contener datos que no son del sistema. Asegúrate de ejecutar estas instrucciones en la base de datos postgres. Si usas el cliente psql para conectarte al clúster de destino, puedes cambiar a otra base de datos sin restablecer la conexión con 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 NOT IN ('plpgsql', 'alloydb_utility');
  4. Descarta las bases de datos que no sean del sistema, las tablas de usuarios y las funciones definidas por el usuario que se identificaron en el paso anterior.
  5. Inicia el trabajo de migración.

Limpia las ranuras de replicación

Verás 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.

Posible problema

Cuando se asciende un clúster de destino de AlloyDB para PostgreSQL, si no se puede acceder a la instancia de origen desde el clúster de AlloyDB para PostgreSQL (por ejemplo, la instancia de origen no se está ejecutando o quitaste el clúster de AlloyDB para PostgreSQL de la lista de entidades permitidas de las instancias de origen), no se puede limpiar la configuración necesaria para la replicación durante el ascenso de un trabajo de migración. Debes limpiar las ranuras de replicación de forma manual.

Solución

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

  1. Obtén los nombres de las ranuras de replicación del mensaje de error y, luego, ejecuta el siguiente comando para descartar 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 existentes:

    SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots WHERE slot_name LIKE '%alloydb%' AND active = 'f';

  3. Si no hay réplicas de AlloyDB para PostgreSQL que usen la instancia de origen, ejecuta el siguiente comando para limpiar la configuración de pglogical:

    SELECT pglogical.drop_node(node_name) FROM pglogical.node WHERE node_name LIKE '%alloydb%';

  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

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

Posible problema

Este problema suele atribuirse al problema de interbloqueo en la extensión pglogical. Para obtener más información, consulta la herramienta de seguimiento de errores de pglogical en GitHub.

Solución

Vuelve a realizar el trabajo de migración con un clúster de destino nuevo

Intenta borrar el clúster de destino en el que experimentaste el problema y vuelve a crear el trabajo de migración. Lleva a cabo los pasos siguientes:

  1. Borra el trabajo de migración con errores. Consulta Revisa un trabajo de migración.
  2. Borra el clúster de destino en el que experimentaste el problema. Consulta Administración de clústeres de AlloyDB.
  3. Vuelve a crear el trabajo de migración. Consulta Crea un trabajo de migración.
Migra a una versión intermedia

Considera migrar a una versión anterior de PostgreSQL, como PostgreSQL 14. Después de una migración exitosa, puedes actualizar a la instancia de PostgreSQL 15 que desees. Consulta Actualiza una versión principal de la base de datos en la documentación de AlloyDB para PostgreSQL.

Borra los clústeres huérfanos de AlloyDB para PostgreSQL en modo de arranque

En casos extremos excepcionales, es posible que veas que se borró tu trabajo de migración, mientras que el clúster de AlloyDB para PostgreSQL asociado no se borró y aún está en modo de arranque. Puedes borrar el clúster con el comando gcloud alloydb clusters delete y la opción --force:

gcloud alloydb clusters delete CLUSTER_ID \
    --region=REGION_ID \
    --force

Ten en cuenta que borrar un clúster de arranque mientras lo usa un trabajo de migración activo genera un comportamiento indefinido.

Administra usuarios y roles

Migra usuarios existentes

Actualmente, Database Migration Service no admite la migración automática de usuarios y roles existentes de una instancia de origen a un clúster de AlloyDB para PostgreSQL de destino. Para administrar esta migración, crea los usuarios en AlloyDB para PostgreSQL de forma manual.

Acerca del usuario alloydbexternalsync

Durante una migración estándar, todos los objetos de la base de datos en la réplica de AlloyDB para PostgreSQL pertenecen al usuario alloydbexternalsync (las migraciones de inicio rápido usan el usuario postgres). Una vez que se migren los datos y se promocione el trabajo de migración, puedes modificar la propiedad de los objetos a otros usuarios de la aplicación completando los siguientes pasos:

  • Ejecuta el comando GRANT alloydbexternalsync TO USER;.
  • En cada base de datos, ejecuta el comando REASSIGN OWNED BY alloydbexternalsync TO USER;.
  • Para quitar el usuario alloydbexternalsync, ejecuta el comando DROP ROLE alloydbexternalsync;.