Merge pull request #753 from AdobeDocs/mariadb-internal-date-format-r…

…evised MariaDB internal date format revised
AdobeDocs · Feb 14, 2024 · 7199e74 · 7199e74
2 parents ea1015b + dbfb00a
commit 7199e74
Show file tree

Hide file tree

Showing 7 changed files with 57 additions and 20 deletions.
diff --git a/help/_includes/maria-db-config.md b/help/_includes/maria-db-config.md
@@ -7,6 +7,13 @@ Reindexing on MariaDB 10.4 and 10.6 takes more time compared to previous MariaDB
 
 If you experience performance degradation not related to indexation after upgrading to MariaDB 10.6, consider enabling the [`--query-cache-type`](https://mariadb.com/kb/en/server-system-variables/#query_cache_type) setting. For example, `--query-cache-type=ON`.
 
+Before upgrading Adobe Commerce on cloud infrastructure projects, you may also need to upgrade MariaDB ([see MariaDB upgrade best practices](../implementation-playbook/best-practices/maintenance/mariadb-upgrade.md)).
+
+For example:
+
+*  Adobe Commerce 2.4.6 with MariaDB version 10.5.1 or higher
+*  Adobe Commerce 2.3.5 with MariaDB version 10.3 or earlier
+
 In addition to these recommendations, you should consult with your database administrator on configuring the following parameters:
 
 >[!NOTE]

diff --git a/help/implementation-playbook/TOC.md b/help/implementation-playbook/TOC.md
@@ -117,5 +117,5 @@ mini-toc-levels: 3
     - [Scheduling Admin updates on production sites](best-practices/maintenance/scheduling-admin-updates-in-production.md)
     - [Update services](best-practices/maintenance/update-services.md)
     - [Upgrade checklist](best-practices/maintenance/upgrade-checklist.md)
-    - [Upgrade prerequisites for MariaDB](best-practices/maintenance/commerce-235-upgrade-prerequisites-mariadb.md)
+    - [Upgrade prerequisites for MariaDB](best-practices/maintenance/mariadb-upgrade.md)
 - [Return to Operational Guides](https://experienceleague.adobe.com/docs/commerce-operations/operational-guides/home.html)
diff --git a/...erce-235-upgrade-prerequisites-mariadb.md → ...-practices/maintenance/mariadb-upgrade.md b/...erce-235-upgrade-prerequisites-mariadb.md → ...-practices/maintenance/mariadb-upgrade.md
@@ -1,21 +1,55 @@
 ---
-title: Adobe Commerce Upgrade prerequisites for MariaDB
+title: Adobe Commerce upgrade prerequisites for MariaDB
 description: Learn how to prepare your Adobe Commerce database to upgrade MariaDB from a previous version.
 role: Developer
 feature: Best Practices
 exl-id: b86e471f-e81f-416b-a321-7aa1ac73d27c
 ---
+
 # Upgrade prerequisites for MariaDB
 
-Upgrading the MariaDB service on the cloud infrastructure from version 10.0 or 10.2 to version 10.3, 10.4, or 10.5. MariaDB version 10.3 and later require the database to use the dynamic table row format and Adobe Commerce requires using the InnoDB storage engine for tables. This article explains how to update your database to comply with these MariaDB requirements.
+Before upgrading Adobe Commerce on cloud infrastructure, you may also need to upgrade your database software if you are using MariaDB. For example:
 
-After you prepare the database, submit an Adobe Commerce support ticket to update the MariaDB service version on your cloud infrastructure before proceeding with the Adobe Commerce upgrade process.
+- Adobe Commerce 2.4.6 with MariaDB version 10.5.1 or higher
+- Adobe Commerce 2.3.5 with MariaDB version 10.3 or earlier
+
+## Adobe Commerce 2.4.6
+
+Starting with MariaDB 10.5.1, columns with old temporal formats are marked with a `/* mariadb-5.3 */` comment in the output of the `SHOW CREATE TABLE`, `SHOW COLUMNS`, `DESCRIBE` statements, as well as in the `COLUMN_TYPE` column of the `INFORMATION_SCHEMA.COLUMNS` table. [See MariaDB documentation](https://mariadb.com/kb/en/datetime/#internal-format).
+
+Adobe Commerce is not able to map the date columns to a proper data type due to the MariaDB comment, which may cause unexpected behaviour in custom code.
+
+To avoid unexpected behaviour when upgrading MariaDB from older versions to version 10.6, Adobe recommends migrating the columns to the new internal format.
+
+### Default configuration
+
+In MariaDB 10.1.2, a new temporal format was introduced from MySQL 5.6. The `mysql56_temporal_format` system variable allows the database to automatically convert the old date format to the new one when an alter table is executed or database is imported. The default configuration for `mysql56_temporal_format` is always enabled on Adobe Commerce on cloud infrastructure. 
+
+### Migrate date columns
 
-## Affected product and versions
+The following query shows the affected table and columns that must be migrated after upgrading MariaDB to 10.5.1 or later:
 
-Adobe Commerce on cloud infrastructure with  MariaDB version 10.3 or earlier.
+```mysql
+SELECT * FROM INFORMATION_SCHEMA.`COLUMNS` WHERE TABLE_SCHEMA = DATABASE() AND COLUMN_TYPE LIKE '%mariadb%';
+```
 
-## Prepare your database for the upgrade
+Migrating the columns to the new internal date format requires reimporting the database or executing alter on the identified column with the same column definition. The following query generates the necessary alter queries:
+
+```mysql
+SELECT CONCAT( 'ALTER TABLE `', COALESCE(TABLE_NAME), '`', ' MODIFY ', '`', COALESCE(COLUMN_NAME), '`', ' ', COALESCE(DATA_TYPE), ' ', IF(COALESCE(IS_NULLABLE)='YES','NULL', 'NOT NULL'), IF(COLUMN_DEFAULT IS NOT NULL,CONCAT(' DEFAULT ',COLUMN_DEFAULT),' '), ' ', COALESCE(EXTRA), ' COMMENT \'', COALESCE(COLUMN_COMMENT), '\';' ) as sql_query FROM INFORMATION_SCHEMA.`COLUMNS` WHERE TABLE_SCHEMA = DATABASE() AND COLUMN_TYPE LIKE '%mariadb%';
+```
+
+>[!NOTE]
+>
+>It is important to migrate the columns to the new internal date format _before_ deploying the new code to avoid unexpected behaviour.
+
+## Adobe Commerce 2.3.5
+
+Upgrading the MariaDB service on the cloud infrastructure from version 10.0 or 10.2 to version 10.3, 10.4, or 10.5. MariaDB version 10.3 and later require the database to use the dynamic table row format and Adobe Commerce requires using the InnoDB storage engine for tables. This article explains how to update your database to comply with these MariaDB requirements.
+
+After you prepare the database, submit an Adobe Commerce support ticket to update the MariaDB service version on your cloud infrastructure before proceeding with the Adobe Commerce upgrade process.
+
+### Prepare your database for the upgrade
 
 Before the Adobe Commerce Support team begins the upgrade process, prepare your database by converting your database tables:
 
@@ -32,7 +66,7 @@ Keep the following considerations in mind when you plan and schedule the convers
 
 - Switch your site to [maintenance mode](../../../installation/tutorials/maintenance-mode.md) before running the commands to convert database tables.
 
-### Convert database table row format
+#### Convert database table row format
 
 You can convert tables on one node in your cluster. The changes replicate automatically to the other service nodes.
 
@@ -60,7 +94,7 @@ You can convert tables on one node in your cluster. The changes replicate automa
    ALTER TABLE [ table name here ] ROW_FORMAT=DYNAMIC;
    ```
 
-### Convert database table storage format
+#### Convert database table storage format
 
 You can convert tables on one node in your cluster. The changes replicate automatically to the other service nodes.
 
@@ -110,7 +144,7 @@ The process to convert the storage format is different for Adobe Commerce Starte
    ALTER TABLE [ table name here ] ENGINE=InnoDB;
    ```
 
-### Verify the database conversion
+#### Verify the database conversion
 
 The day before the scheduled upgrade to MariaDB version 10.3, 10.4, or 10.6, verify that all tables have the correct row format and storage engine. Verification is required because code deployments made after you complete the conversion might cause some tables to be reverted to their original configuration.
 
@@ -130,11 +164,6 @@ The day before the scheduled upgrade to MariaDB version 10.3, 10.4, or 10.6, ver
 
 1. If any tables have been reverted, repeat the steps to change the table row format and storage engine.
 
-## Change the storage engine
+### Change the storage engine
 
 See [Convert MyISAM tables to InnoDB](../planning/database-on-cloud.md).
-
-## Additional information
-
-- [Database best practices for Adobe Commerce on cloud infrastructure](../planning/database-on-cloud.md)
-- [Updating MariaDB from 10.0 to 12.0 for Adobe Commerce on Cloud](https://experienceleague.adobe.com/docs/commerce-knowledge-base/kb/how-to/upgrade-mariadb-10.0-to-10.2-for-magento-commerce-cloud.html)
diff --git a/help/implementation-playbook/best-practices/maintenance/overview.md b/help/implementation-playbook/best-practices/maintenance/overview.md
@@ -42,7 +42,7 @@ The following sections include best practice information for the maintenance pha
 | Best practice                                                                                          | Description                                                                                         |
 |--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
 | [Resolve database performance issues](resolve-database-performance-issues.md)                           | Fix database issues that slow performance on Adobe Commerce sites deployed on cloud infrastructure. |
-| [Adobe Commerce 2.3.5 upgrade prerequisites for MariaDB](commerce-235-upgrade-prerequisites-mariadb.md) | Prepare your MariaDB database for an upgrade.                                                       |
+| [Adobe Commerce upgrade prerequisites for MariaDB](mariadb-upgrade.md) | Prepare your MariaDB database for an upgrade.                                                       |
 
 ## Feature enhancements
 

diff --git a/help/implementation-playbook/best-practices/planning/database-on-cloud.md b/help/implementation-playbook/best-practices/planning/database-on-cloud.md
@@ -94,5 +94,5 @@ See [Enable archiving](https://experienceleague.adobe.com/docs/commerce-admin/st
 ## Additional information
 
 - [MySQL Storage Engines](https://dev.mysql.com/doc/refman/8.0/en/storage-engines.html)
-- [Adobe Commerce 2.3.5 upgrade prerequisites for MariaDB](../maintenance/commerce-235-upgrade-prerequisites-mariadb.md)
+- [Adobe Commerce 2.3.5 upgrade prerequisites for MariaDB](../maintenance/mariadb-upgrade.md)
 - [Best practices to resolve database performance issues](../maintenance/resolve-database-performance-issues.md)
diff --git a/help/upgrade/prepare/prerequisites.md b/help/upgrade/prepare/prerequisites.md
@@ -166,7 +166,7 @@ We recommend that you contact your search engine vendor to determine whether you
 
 ## Convert database table format
 
-You must convert the format of all database tables from `COMPACT` to `DYNAMIC`. You must also convert the storage engine type from `MyISAM` to `InnoDB`. See [best practices](../../implementation-playbook/best-practices/maintenance/commerce-235-upgrade-prerequisites-mariadb.md).
+You must convert the format of all database tables from `COMPACT` to `DYNAMIC`. You must also convert the storage engine type from `MyISAM` to `InnoDB`. See [best practices](../../implementation-playbook/best-practices/maintenance/mariadb-upgrade.md).
 
 ## Set the open files limit
 

diff --git a/redirects.csv b/redirects.csv
@@ -30,4 +30,5 @@ https://experienceleague.adobe.com/docs/commerce-operations/implementation-playb
 https://experienceleague.adobe.com/docs/commerce-operations/implementation-playbook/best-practices/launch/security-notification-service.html,https://www.adobe.com/subscription/adbeSecurityNotifications.html
 https://experienceleague.adobe.com/docs/commerce-operations/implementation-playbook/architecture/global-reference.html,https://experienceleague.adobe.com/docs/commerce-operations/implementation-playbook/architecture/global-reference-architecture/overview.html
 https://experienceleague.adobe.com/docs/commerce-operations/implementation-playbook/infrastructure/cloud/environments.html,https://experienceleague.adobe.com/docs/commerce-cloud-service/user-guide/architecture/pro-architecture.html
-https://experienceleague.adobe.com/docs/commerce-operations/implementation-playbook/infrastructure/cloud/managed-services.html,https://experienceleague.adobe.com/docs/commerce-operations/implementation-playbook/maintenance/adobe-managed-services.html
+https://experienceleague.adobe.com/docs/commerce-operations/implementation-playbook/infrastructure/cloud/managed-services.html,https://experienceleague.adobe.com/docs/commerce-operations/implementation-playbook/maintenance/adobe-managed-services.html
+https://experienceleague.adobe.com/docs/commerce-operations/implementation-playbook/best-practices/maintenance/commerce-235-upgrade-prerequisites-mariadb.html,https://experienceleague.adobe.com/docs/commerce-operations/implementation-playbook/best-practices/maintenance/mariadb-upgrade.html