|
| 1 | +--- |
| 2 | +title: MySQL to Azure Database for MySQL Data Migration - MySQL Schema Migration |
| 3 | +description: Learn how to use the Azure Database for MySQL Data Migration - MySQL Schema Migration |
| 4 | +author: adig |
| 5 | +ms.author: adig |
| 6 | +ms.date: 07/23/2023 |
| 7 | +ms.service: dms |
| 8 | +ms.topic: conceptual |
| 9 | +ms.custom: references_regions |
| 10 | +--- |
| 11 | + |
| 12 | +# MySQL to Azure Database for MySQL Data Migration - MySQL Schema Migration |
| 13 | + |
| 14 | +MySQL Schema Migration is a new feature that allows users to migrate the schema for objects such as tables, views, triggers, events, stored procedures, and functions. This feature is useful for automating some of work required to prepare the target database prior to starting a migration. |
| 15 | + |
| 16 | +## Current implementation |
| 17 | + |
| 18 | +In the current implementation, users can select the **server objects (views, triggers, events, routines)** that they want to migrate in **Select databases** tab under **Select Server Objects** section when configuring the DMS migration project. Additionally, they can select the databases under **Select databases** section whose schema is to be migrated. |
| 19 | +:::image type="content" source="media/tutorial-mysql-to-azure-mysql-online/16-select-db.png" alt-text="Screenshot of a Select database."::: |
| 20 | + |
| 21 | +To migrate the schema for table objects, navigate to the **Select tables** tab. Before the tab populates, DMS fetches the tables from the selected database(s) on the source and target, and then determines whether the table exists and contains data. If you select a table in the source database that doesn't exist on the target database, the box under **Migrate schema** is selected by default. For tables that do exist in the target database, a note indicates that the selected table already contains and will be truncated. In addition, if the schema of a table on the target server doesn't match the schema on the source, the table will be dropped before the migration continues. |
| 22 | + |
| 23 | + :::image type="content" source="media/tutorial-mysql-to-azure-mysql-online/17-select-tables.png" alt-text="Screenshot of a Select Tables."::: |
| 24 | + |
| 25 | +When you continue to the next tab, DMS validates your inputs and confirms that the tables selected match if they were selected without the schema migration input. Once the validation passes, you can begin the migration scenario. |
| 26 | + |
| 27 | +After you begin the migration and as the migration progresses, each table is created prior to migrating its data from the source to the target. Except for triggers and views, which are migrated after data migration is complete, other objects are created for tables prior to the data migration. |
| 28 | + |
| 29 | +### How Schema Migration works |
| 30 | + |
| 31 | +Schema migration is supported by MySQL’s **“SHOW CREATE”** syntax to gather schema information for objects from the source. When migrating the schema for the objects from the source to the target, DMS processes the input and individually migrates the objects. DMS also wraps the collation, character set, and other relevant information that is provided by the “SHOW CREATE” query to the create query that is then processed on to the target. |
| 32 | + |
| 33 | +**Routines** and **Events** are migrated before any data is migrated. The schema for each individual **table** is migrated immediately prior to data movement starting for the table. **Triggers** are migrated after the data migration portion. For **views**, since MySQL validates the contents of views and they can depend on other tables, DMS first creates tables for views before the start of database data movement and then drops the temporary table and creates the view. |
| 34 | + |
| 35 | +When querying the source and target, if a transient error occurs, DMS **retries** the queries. However, if an error occurs that DMS can't recover from – as an example, an invalid syntax when performing a version upgrade migration – DMS fails and report that error message on completion. If the failure occurs when creating a table, the data for that table isn't migrated, but the data and schema migration for the other selected tables is attempted. If an unrecoverable error occurs for events, routines, or when creating the temporary table for views, the migration fails prior to running the migration for the selected tables and the objects that are migrated following the data migration portion. |
| 36 | + |
| 37 | +Since a temporary table is created for views, if there's a failure migrating a view, the temporary table is left on the target. After the underlying issue is fixed and the migration is retried, DMS deletes that table prior to creating the view. Alternatively, if electing not to use schema migration for views in a future migration, the temporary table needs to be manually deleted prior to manually migrating the view. |
| 38 | + |
| 39 | +## Prerequisites |
| 40 | + |
| 41 | +To complete a schema migration successfully, ensure that the following prerequisites are in place. |
| 42 | + |
| 43 | +* “READ” privilege on the source database. |
| 44 | +* “SELECT” privilege for the ability to select objects from the database |
| 45 | +* If migrating views, the user must have the “SHOW VIEW” privilege. |
| 46 | +* If migrating triggers, the user must have the “TRIGGER” privilege. |
| 47 | +* If migrating routines (procedures and/or functions), the user must be named in the definer clause of the routine. Alternatively, based on version, the user must have the following privilege: |
| 48 | + * For 5.7, have “SELECT” access to the “mysql.proc” table. |
| 49 | + * For 8.0, have “SHOW_ROUTINE” privilege or have the “CREATE ROUTINE,” “ALTER ROUTINE,” or “EXECUTE” privilege granted at a scope that includes the routine. |
| 50 | +* If migrating events, the user must have the “EVENT” privilege for the database from which the events are to be shown. |
| 51 | + |
| 52 | +## Limitations |
| 53 | + |
| 54 | +* When migrating non table objects, DMS doesn't support renaming databases. |
| 55 | +* When migrating to a target server that has bin_log enabled, log_bin_trust_function_creators should be enabled to allow for creation of routines and triggers. |
| 56 | +* When migrating please ensure that the database exists on the target server. Schema migration only supports migrating objects and doesn't support creating the database on the target server. |
| 57 | +* Currently there's no support for migrating the DEFINER clause for objects. All object types with definers on source get dropped and after the migration the default definer for tables are set to the login used to run the migration. |
| 58 | +* We haven't tested version upgrade scenarios and results aren't guaranteed. Some version upgrades aren't supported if there are breaking changes in version compatibility. Refer to the MySQL docs for more information on version upgrades. |
| 59 | +* Currently we can only migrate schema as part of data movement. If nothing is selected for data movement, no schema migration happens. If a table is selected for schema migration, it is selected for data movement. |
| 60 | + |
| 61 | +## Next steps |
| 62 | + |
| 63 | +- Learn more about [Data-in Replication](../mysql/concepts-data-in-replication.md) |
| 64 | + |
| 65 | +- [Tutorial: Migrate MySQL to Azure Database for MySQL offline using DMS](tutorial-mysql-azure-mysql-offline-portal.md) |
0 commit comments