# Getting started with DMS Schema Conversion To get started with DMS Schema Conversion, use the following tutorial. In it, you can learn to set up DMS Schema Conversion, create a migration project, and connect to your data providers. Then, you can learn to assess the complexity of your migration, and convert your source database to a format compatible with your target database. In addition, you can learn to apply the converted code to your target database. The following tutorial covers the prerequisite tasks and demonstrates the conversion of an Amazon RDS for SQL Server database to Amazon RDS for MySQL. You can use any of the supported source and target data providers. For more information, see [Source data providers for DMS Schema Conversion](CHAP_Introduction.Sources.md#CHAP_Introduction.Sources.SchemaConversion). For more information about DMS Schema Conversion, read the step-by-step migration walkthroughs for [Oracle to PostgreSQL](https://docs.aws.amazon.com/dms/latest/sbs/schema-conversion-oracle-postgresql.html) and [SQL Server to MySQL](https://docs.aws.amazon.com/dms/latest/sbs/schema-conversion-sql-server-mysql.html) migrations. The following video introduces the DMS Schema Conversion user interface and helps you get familiar with the core components of this service. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/ki3r92Cfqwk/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/ki3r92Cfqwk) **Topics** + [ # Complete prerequisites for working with DMS Schema Conversion ](set-up.md) + [ # Create an instance profile for DMS Schema Conversion ](getting-started-instance.md) + [ # Configure your data providers for DMS Schema Conversion ](getting-started-data-providers.md) + [ # Create a migration project in DMS Schema Conversion ](getting-started-project.md) + [ # Create an assessment report in DMS Schema Conversion ](getting-started-assessment.md) + [ # Convert your source code in DMS Schema Conversion ](getting-started-convert.md) + [ # Apply the converted code for DMS Schema Conversion ](getting-started-apply.md) + [ # Clean up and troubleshoot to work with DMS Schema Conversion ](getting-started-clean-up.md) # Complete prerequisites for working with DMS Schema Conversion To set up DMS Schema Conversion, complete the following tasks. Then you can set up an instance profile, add data providers, and create a migration project. **Topics** + [ ## Create a VPC based on Amazon VPC ](#set-up-vpc) + [ ## Create an Amazon S3 bucket ](#set-up-s3-bucket) + [ ## Store database credentials in AWS Secrets Manager ](#set-up-secrets) + [ ## Create IAM policies ](#set-up-iam-policies) + [ ## Create IAM roles ](#set-up-iam-roles) ## Create a VPC based on Amazon VPC In this step, you create a virtual private cloud (VPC) in your AWS account. This VPC is based on the Amazon Virtual Private Cloud (Amazon VPC) service and contains your AWS resources. **To create a VPC for DMS Schema Conversion** 1. Sign in to the AWS Management Console and open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/). 1. Choose **Create VPC**. 1. On the **Create VPC** page, enter the following settings: + **Resources to create** – **VPC and more** + **Name tag auto-generation** – Choose **Auto-generate** and enter a globally unique name. For example, enter **sc-vpc**. + **IPv4 CIDR block** – **10.0.1.0/24** + **NAT gateways** – **In 1 AZ** + **VPC endpoints** – **None** 1. Keep the rest of the settings as they are, and then choose **Create VPC**. 1. Choose **Subnets**, and take a note of your public and private subnet IDs. To connect to your Amazon RDS databases, create a subnet group that includes public subnets. To connect to your on-premises databases, create a subnet group that includes private subnets. For more information, see [Create an instance profile for DMS Schema Conversion](getting-started-instance.md). 1. Choose **NAT gateways**. Choose your **NAT gateway** and take a note of your **Elastic IP address**. Configure your network to make sure that AWS DMS can access your source on-premises database from this NAT gateway's public IP address. For more information, see [Using an internet connection to a VPC](instance-profiles-network.md#instance-profiles-network-internet). Use this VPC when you create your instance profile and target databases on Amazon RDS. ## Create an Amazon S3 bucket To store information from your migration project, create an Amazon S3 bucket. DMS Schema Conversion uses this Amazon S3 bucket to save items such as assessment reports, converted SQL code, information about database schema objects, and so on. **To create an Amazon S3 bucket for DMS Schema Conversion** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. Choose **Create bucket**. 1. On the **Create bucket** page, select a globally unique name for your S3 bucket. For example, enter **sc-s3-bucket**. 1. For **AWS Region**, choose your Region. 1. For **Bucket Versioning**, choose **Enable**. 1. Keep the rest of the settings as they are, and then choose **Create bucket**. **Note** DMS Schema Conversion (SC) works only with S3 buckets that use Server-Side Encryption with Amazon S3-Managed Keys (SSE-S3). Other encryption configurations, including Server-Side Encryption with AWS KMS (SSE-KMS), Customer-Provided Keys (SSE-C), or Client-Side Encryption, are not currently supported by SC and prevents it from accessing the S3 bucket. If using a different encryption method, you must create a separate S3 bucket with SSE-S3 for use with DMS Schema Conversion. ## Store database credentials in AWS Secrets Manager Store your source and target database credentials in AWS Secrets Manager. Make sure that you replicate these secrets to your AWS Region. DMS Schema Conversion uses these secrets to connect to your databases in the migration project. **To store your database credentials in AWS Secrets Manager** 1. Sign in to the AWS Management Console and open the AWS Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/). 1. Choose **Store a new secret**. 1. The **Choose secret type** page opens. For **Secret type**, choose the type of database credentials to store: + **Credentials for Amazon RDS database** – Choose this option to store credentials for your Amazon RDS database. For **Credentials**, enter the credentials for your database. For **Database**, choose your database. + **Credentials for other database** – Choose this option to store credentials for your source Oracle or SQL Server databases. For **Credentials**, enter the credentials for your database. + **Other type of secret** – Choose this option to store only the user name and password to connect to your database. Choose **Add row** to add two key-value pairs. Make sure that you use **username** and **password** for key names. For values related to these keys, enter the credentials for your database. 1. For **Encryption key**, choose the AWS KMS key that Secrets Manager uses to encrypt the secret value. Choose **Next**. 1. On the **Configure secret** page, enter a descriptive **Secret name**. For example, enter **sc-source-secret** or **sc-target-secret**. 1. Choose **Replicate secret** and then for **AWS Region** choose your Region. Choose **Next**. 1. On the **Configure rotation** page, choose **Next**. 1. On the **Review** page, review your secret details, and then choose **Store**. To store credentials for your source and target databases, repeat these steps. ## Create IAM policies **To create an IAM policy for DMS Schema Conversion to access Amazon S3** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Policies**. 1. Choose **Create policy**. 1. On the **Select service** page, choose **Amazon S3** from the list. 1. In the **Actions allowed**, choose `PutObject`, `GetObject`, `GetObjectVersion`, `GetBucketVersioning`, `GetBucketLocation`, `ListBucket`. 1. In the **Resources** specify the ARN of the bucket that you created in the previous section. Choose **Next**. 1. On the **Review and create** page, enter a descriptive name. For example: `sc-s3-policy`. Then, choose **Create policy**. **To create an IAM policy for DMS Schema Conversionto access AWS Secrets Manager** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Policies**. 1. Choose **Create policy**. 1. On the **Select service** page, choose **Secrets Manager** from the list. 1. Choose **Next**. The **Add permissions** page opens. 1. In the **Actions allowed**, choose: `GetSecretValue` and `DescribeSecret`. 1. On the **Review and create** page, enter a descriptive name. For example: `sc-secrets-manager-policy`. Then, choose **Create policy**. ## Create IAM roles Create AWS Identity and Access Management (IAM) roles to use in your migration project. DMS Schema Conversion uses these IAM roles to access your Amazon S3 bucket and database credentials stored in AWS Secrets Manager. **To create an IAM role that provides access to your Amazon S3 bucket** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles**. 1. Choose **Create role**. 1. On the **Select trusted entity** page, choose **AWS service**. Choose **DMS**. 1. Choose **Next**. The **Add permissions** page opens. 1. For **Filter policies**, enter **S3**. Choose the **sc-s3-policy** policy that you created in the previous section. 1. Choose **Next**. The **Name, review, and create** page opens. 1. For **Role name**, enter a descriptive name. For example, enter **sc-s3-role**. Choose **Create role**. 1. On the **Roles** page, enter **sc-s3-role** for **Role name**. Choose **sc-s3-role**. 1. On the **sc-s3-role page**, choose the **Trust relationships** tab. Choose **Edit trust policy**. 1. Thes AWS DMS regional service principal has the following format: ``` dms.region-name.amazonaws.com ``` Replace `region-name` with the name of your Region, such as `us-east-1`: The following code example shows the principal for the `us-east-1` Region: ``` dms.us-east-1.amazonaws.com ``` The following code example shows a trust policy for accessing AWS DMS schema conversion: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "dms.us-east-1.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ **To create an IAM role that provides access to AWS Secrets Manager** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles**. 1. Choose **Create role**. 1. On the **Select trusted entity** page, choose **AWS service**. Choose **DMS**. 1. Choose **Next**. The **Add permissions** page opens. 1. For **Filter policies**, enter `s3`. Choose the **sc-secrets-manager-policy** that you created in the previous section. 1. Choose **Next**. The **Name, review, and create** page opens. 1. For **Role name**, enter a descriptive name. For example, enter **sc-secrets-manager-role**. Choose **Create role**. 1. On the **Roles** page, enter **sc-secrets-manager-role** for **Role name**. Choose **sc-secrets-manager-role**. 1. On the **sc-secrets-manager-role** page, choose the **Trust relationships tab**. Choose **Edit trust policy**. 1. On the **Edit trust policy** page, edit the trust relationships for the role to use `schema-conversion.dms.amazonaws.com` and your AWS DMS regional service principal as the trusted entities. This AWS DMS regional service principal has the following format: ``` dms.region-name.amazonaws.com ``` Replace `region-name` with the name of your Region, such as `us-east-1`: The following code example shows the principal for the `us-east-1` Region: ``` dms.us-east-1.amazonaws.com ``` The following code example shows a trust policy for accessing AWS DMS schema conversion: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "dms.us-east-1.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ **To create the `dms-vpc-role` IAM role for use with the AWS CLI or AWS DMS API** 1. Create a JSON file with the following IAM policy. Name the JSON file `dmsAssumeRolePolicyDocument.json`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "dms.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ Then, create the role using the AWS CLI using the following command: ``` aws iam create-role --role-name dms-vpc-role --assume-role-policy-document file://dmsAssumeRolePolicyDocument.json ``` 1. Attach the `AmazonDMSVPCManagementRole` policy to `dms-vpc-role` using the following command: ``` aws iam attach-role-policy --role-name dms-vpc-role --policy-arn arn:aws:iam::aws:policy/service-role/AmazonDMSVPCManagementRole ``` **To create the `dms-cloudwatch-logs-role` IAM role for use with the AWS CLI or AWS DMS API** 1. Create a JSON file with the following IAM policy. Name the JSON file `dmsAssumeRolePolicyDocument2.json`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "dms.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ Then, create the role using the AWS CLI using the following command: ``` aws iam create-role --role-name dms-cloudwatch-logs-role --assume-role-policy-document file://dmsAssumeRolePolicyDocument2.json ``` 1. Attach the `AmazonDMSCloudWatchLogsRole` policy to `dms-cloudwatch-logs-role` using the following command: ``` aws iam attach-role-policy --role-name dms-cloudwatch-logs-role --policy-arn arn:aws:iam::aws:policy/service-role/AmazonDMSCloudWatchLogsRole ``` # Create an instance profile for DMS Schema Conversion Before you create an instance profile, configure a subnet group for your instance profile. For more information about creating a subnet group for your AWS DMS migration project, see [Creating a subnet group](subnet-group.md). You can create an instance profile as described in the following procedure. In this instance profile, you specify network and security settings for your DMS Schema Conversion project. **To create an instance profile** 1. Sign in to the AWS Management Console and open the AWS DMS console at [https://console.aws.amazon.com/dms/v2/](https://console.aws.amazon.com/dms/v2/). 1. In the navigation pane, choose **Instance profiles**, and then choose **Create instance profile**. 1. For **Name**, enter a unique name for your instance profile. For example, enter **sc-instance**. 1. For **Network type**, choose **IPv4** to create an instance profile that supports only IPv4 addressing. To create an instance profile that supports IPv4 and IPv6 addressing, choose **Dual-stack mode**. 1. For **Virtual private cloud (VPC)**, choose the VPC that you created in the prerequisites step. 1. For **Subnet group**, choose the subnet group for your instance profile. To connect to Amazon RDS databases, use a subnet group that includes public subnets. To connect to on-premises databases, use a subnet group that includes private subnets. 1. Choose **Create instance profile**. To create a migration project, use this instance profile. # Configure your data providers for DMS Schema Conversion Next, you create data providers that describe your source and target databases. For each data provider, you specify a data store type and location information. You don't store your database credentials in a data provider. **To create a data provider for an on-premises database** 1. Sign in to the AWS Management Console, and open the AWS DMS console. 1. In the navigation pane, choose **Data providers**, and then choose **Create data provider**. 1. For **Name**, enter a unique name for your source data provider. For example, enter `sc-dp`. 1. For **Purpose**, select **Schema Conversion**. 1. For **Engine type**, choose the type of database engine for your data provider. 1. Turn on **Virtual mode** if you want to use schema conversion without connecting to a target database. For more information, see [Virtual data provider](virtual-data-provider.md). 1. If **Virtual Mode** is turned on, connection information will be preset automatically using defaults. Note that a virtual data provider can only be used as a target in a migration project or in schema conversion. For more information on virtual mode, see [Virtual data provider](virtual-data-provider.md). If **Virtual mode** is off, provide your connection information for the source database. The connection parameters depend on your database engine. For more information, see [ Creating data providers](data-providers-create.md). 1. Select **Engine configuration**. Then select **Enter manually**. Provide your connection information for the source database. The connection parameters depend on your source database engine. For more information, see [ Creating data providers](data-providers-create.md). 1. For **Secure Socket Layer (SSL) mode**, choose the type of SSL enforcement. 1. Choose **Create data provider**. **To create a data provider for an Amazon RDS database** 1. Sign in to the AWS Management Console, and open the AWS DMS console. 1. In the navigation pane, choose **Data providers**, and then choose **Create data provider**. 1. For **Name**, enter a unique name for your source data provider. For example, enter `sc-dp`. 1. For **Purpose**, select **Schema Conversion**. 1. For **Engine type**, choose the type of database engine for your data provider. 1. Turn **Virtual Mode** on, if you intend to use this data provider for schema conversion without connecting to a target database. For more information on virtual mode, see [Virtual data provider](virtual-data-provider.md). 1. Select **Engine configuration**. Select **Choose RDS database instance from list**. 1. For **Database from RDS**, choose **Browse**, and choose your database. DMS Schema Conversion automatically retrieves the information about the engine type, server name, and port. 1. For **Database name**, enter the name of your database. 1. For **Secure Socket Layer (SSL) mode**, choose the type of SSL enforcement. 1. Choose **Create data provider**. # Create a migration project in DMS Schema Conversion Now you can create a migration project. In the migration project, you specify your source and target data providers, and your instance profile. **To create a migration project** 1. Choose **Migration projects**, and then choose **Create migration project**. 1. For **Name**, enter a unique name for your migration project. For example, enter **sc-project**. 1. For **Instance profile**, choose **sc-instance**. 1. For **Source**, choose **Browse**, and then choose **sc-source**. 1. For **Secret ID**, choose **sc-source-secret**. 1. For **IAM role**, choose **sc-secrets-manager-role**. 1. For **Target**, choose **Browse**, and then choose **sc-target**. 1. For **Secret ID**, choose **sc-target-secret**. 1. For **IAM role**, choose **sc-secrets-manager-role**. 1. Choose **Create migration project**. # Create an assessment report in DMS Schema Conversion To assess the complexity of the migration, create the database migration assessment report. This report includes the list of all database objects that DMS Schema Conversion can't convert automatically. **To create an assessment report** 1. Choose **Migration projects**, and then choose **sc-project**. 1. Choose **Schema conversion**, and then choose **Launch schema conversion**. 1. In the source database pane, choose the database schema to assess. Also, select the check box for the name of this schema. 1. In the source database pane, choose **Assess** in the **Actions** menu. The **Assess** dialog box appears. 1. Choose **Assess** in the dialog box to confirm your choice. The **Summary** tab shows the number of items that DMS Schema Conversion can automatically convert for database storage objects and database code objects. 1. Choose **Action items** to see the list of all database objects that DMS Schema Conversion can't convert automatically. Review the recommended actions for each item. 1. To save a copy of your assessment report, choose **Export results**. Next, choose one of the following formats: **CSV** or **PDF**. The **Export** dialog box appears. 1. Choose **Export** to confirm your choice. 1. Choose **S3 bucket**. The Amazon S3 console opens. 1. Choose **Download** to save your assessment report. # Convert your source code in DMS Schema Conversion You can convert your source database schema using the following procedure. Then you can save the converted code as SQL scripts in a text file. **To convert your database schema** 1. In the source database pane, choose the database schema to convert. Also, select the check box for the name of this schema. 1. In the source database pane, choose **Convert** in the **Actions** menu. The **Convert** dialog box appears. 1. Choose **Convert** in the dialog box to confirm your choice. 1. Choose a database object in the source database pane. DMS Schema Conversion displays the source code and the converted code for this object. You can edit the converted SQL code for a database object using the Edit SQL feature. For more information, see [Editing and saving your converted SQL code](schema-conversion-convert.md#schema-conversion-convert-editsql). 1. In the target database pane, choose the converted database schema. Also, select the check box for the name of this schema. 1. For **Actions**, choose **Save as SQL**. The **Save** dialog box appears. 1. Choose **Save as SQL** to confirm your choice. 1. Choose **S3 bucket**. The Amazon S3 console opens. 1. Choose **Download** to save your SQL scripts. # Apply the converted code for DMS Schema Conversion DMS Schema Conversion doesn't immediately apply the converted code to your target database. To update your target database, you can use the SQL scripts that you created in the previous step. Alternatively, use the following procedure to apply the converted code from DMS Schema Conversion. **To apply the converted code** 1. In the target database pane, choose the converted database schema. Also, select the check box for the name of this schema. 1. For **Actions**, choose **Apply changes**. The **Apply changes** dialog box appears. 1. Choose **Apply** to confirm your choice. # Clean up and troubleshoot to work with DMS Schema Conversion You can use Amazon CloudWatch to review or share your DMS Schema Conversion logs. **To review DMS Schema Conversion logs** 1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Choose **Logs**, **Log groups**. The name of your DMS Schema Conversion log group starts with `dms-tasks-sct`. You can sort the log groups by **Creation time** to find DMS Schema Conversion log group. Also, the name of your log group includes the Amazon Resource Name (ARN) of your migration project. You can see the ARN of your project on the **Migration projects** page in DMS Schema Conversion. Make sure that you choose **ARN** in **Preferences**. 1. Choose the name of your log group, and then choose the name of your log stream. 1. For **Actions**, choose **Export results** to save your DMS Schema Conversion log. After you've finished your schema conversion in DMS Schema Conversion, clean up your resources. **To clean up your DMS Schema Conversion resources** 1. Sign in to the AWS Management Console and open the AWS DMS console. 1. In the navigation pane, choose **Migration projects**. 1. Choose **sc-project**. 1. Choose **Schema conversion**, and then choose **Close schema conversion**. 1. Choose **Delete** and confirm your choice. 1. In the navigation pane, choose **Instance profiles**. 1. Choose **sc-instance**. 1. Choose **Delete** and confirm your choice. 1. In the navigation pane, choose **Data providers**. 1. Select **sc-source** and **sc-target**. 1. Choose **Delete** and confirm your choice. Also, make sure that you clean up other AWS resources that you created, such as your Amazon S3 bucket, database secrets in AWS Secrets Manager, IAM roles, and virtual private cloud (VPC).