From 58a2070ecbf4286cb9768e884941e6f988bfd86a Mon Sep 17 00:00:00 2001 From: Ibrahim Serdar Acikgoz Date: Mon, 28 Oct 2024 06:04:25 +0100 Subject: [PATCH] mysql deprecation: add more troubleshooting steps (#7510) --- source/deploy/postgres-migration.rst | 50 ++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/source/deploy/postgres-migration.rst b/source/deploy/postgres-migration.rst index 53f86014a15..d5303ff1f06 100644 --- a/source/deploy/postgres-migration.rst +++ b/source/deploy/postgres-migration.rst @@ -61,9 +61,55 @@ Errors during the pgloader command execution If you encounter errors during the execution of the ``pgloader`` command, ensure that both of the databases are accessible and that the users have the necessary permissions to access the database. Do not continue with the migration if there are errors during the execution of the ``pgloader`` command. -Also, there may be cases where ``pgloader`` continue to migration remaining tables and skip one or more tables. In such cases, it is recommended to identify issues with the table and fix them before running the ``pgloader`` command again with a clean database. It is possible to run the ``pgloader`` command with the ``--debug`` flag to get more information about the errors. +.. note:: + + For experienced users, it is recoverable to run the ``pgloader`` without requiring a restart of the migration from scratch. In this case, you will need to manually fix the issues with the table, and run the ``pgloader`` command with a tailored configuration specifically for those tables. Also ensure that the schema name is reverted back to ``public``, and the ``search_path`` is restored (or remove necessary clauses from the configuration). + +The following sections detail how to resolve some common errors you may encounter during the execution of the ``pgloader`` command: + +Invalid input syntax for type JSON +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you receive an error message similar to the following: + +.. code-block:: text + + ERROR Database error 22P02: invalid input syntax for type json + +The data in the MySQL database is not in a valid JSON format. You can fix this issue by updating the data in the MySQL database to be in a valid JSON format. To find out which row is causing the issue, run the following query (where ```` and ```` should be replaced with the actual table and column names indicated in the ``pgloader`` output): + +.. code-block:: sql + + SELECT * FROM WHERE JSON_VALID() = 0; + +You can find and update the data in the MySQL database to be in a valid JSON format with the query above. After updating the data, you can run the ``pgloader`` command again. + +Failed to find column or table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you receive an error message similar to the following: + +.. code-block:: text + + pgloader failed to find column + +The column or table is missing in the PostgreSQL database. You can fix this issue by checking whether you have created the correct version of Postgres schema. After re-creating the schema, you can run the ``pgloader`` command again. + +Fell through ECASE expression +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you receive an error message similar to the following: + +.. code-block:: text + + ERROR mysql: 76 fell through ECASE expression. + +It is a `known issue `_ with pgloader. You can fix this issue by either compiling ``pgloader`` from source or simply avoid this by running ``pgloader`` with our docker image. See: :ref:`install pgloader ` for more information. + +.. note:: + + Also, there may be cases where pgloader continues to migrate remaining tables and skip one or more tables during migration. In such cases, we recommend identifying issues with the table and fixing them before running the ``pgloader`` command again with a clean database. It is possible to run the ``pgloader`` command with the ``--debug`` flag to get more information about the errors. -For experienced users, it is recoverable to run the ``pgloader`` without requiring to restart the migration from scratch. In this case, you will need to manually fix the issues with the table and run the ``pgloader`` command with a tailored configuration just for those tables. Also ensure that the schema name is reverted back to ``public`` and the ``search_path`` is restored or remove necessary clauses form the configuration. Mattermost can't connect to the PostgreSQL database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~