Running a transformation on the command line with Amazon Q Developer - Amazon Q Developer
PrerequisitesStep 1: Install the toolStep 2: Configure and authenticateStep 3: Run a transformation

Running a transformation on the command line with Amazon Q Developer

Complete these steps to transform your code on the command line with the Amazon Q Developer command line tool.

Prerequisites

Before you begin a transformation on the command line, the following prerequisites must be met:

Step 1: Install the tool

  1. Download the Amazon Q command line tool for transformations.

    To download a previous version of the command line tool, see Version history.

  2. We recommend that you set up a virtual environment in Python to install the tool. To create a virtual environment, open a terminal window and run:

    python -m venv qct-cli

  3. To activate the virtual environment, run: 

    source qct-cli/bin/activate

  4. To install the tool on your command line, run:

    pip install amzn_qct_cli-0.4.1-py3-none-any.whl
    Note

    If you are using an older version of the command line tool for transformations, replace 0.4.1 with the version you downloaded.

  5. To verify that the tool was installed, run:

    which qct

Step 2: Configure and authenticate

Before you can begin a transformation, you must provide configuration details and authenticate to your Amazon Q Developer Pro subscription with IAM Identity Center.

  1. To start the configuration process, run the following command:

    qct configure

  2. First, your Maven version is verified. If you have at least the minimum supported version, you will see the following output: 

    Running command: mvn --version at: path/to/current/directory 
Your Maven version is supported for transformations.

    If you don’t have a supported version of Maven, you must update it to continue. For more information, see the Prerequisites.

  3. You are then be prompted to enter a JDK path for each supported Java version. You only need to specify the path to the JDK of the Java version you are upgrading.

  4. Next, you are prompted to provide the Start URL to authenticate to Amazon Q Developer Pro through OpenID Connect identity provider. For more information, see the Prerequisites.

  5. Enter the AWS Region where your Amazon Q Developer subscription profile is configured, in the following format: us-east-1. For a list of supported Regions, see Supported Regions. For a list of Region codes, see Regional endpoints in the AWS General Reference guide.

  6. If you're upgrading your code's Java version, you have the option to receive your code suggestions from Amazon Q in one commit or multiple commits. Amazon Q will split the upgraded code into multiple commits by default. If you want all your code changes to appear in one commit, enter the letter 'O' for one commit when prompted.

    For more information on how Amazon Q splits up the code changes, see Reviewing the transformation summary and accepting changes.

  7. Your configuration preferences are saved to a configuration.ini file.

Step 3: Run a transformation

Choose the type of transformation you're performing to see the required configuration and commands.

For information on running custom transformations, see Customizing transformations.

Java upgrade

  1. Run the following command to start a transformation for a Java upgrade. Replace <path-to-folder> with the path to the folder with the code you're transforming and <your-target-java-version> with either JAVA_17 or JAVA_21.

    qct transform --source_folder <path-to-folder>
    --target_version <your-target-java-version>

  2. Amazon Q begins the transformation. It will output status updates throughout the transformation. When it’s complete, Amazon Q provides the path where the transformation results, logs, and configuration files are outputted.

    Your upgraded code will be committed to the new branch Amazon Q created. Amazon Q will commit the code in one or multiple commits, depending on the selection you made when you ran qct configure.

SQL conversion

Before you begin, make you sure you've read Converting embedded SQL in Java applications with Amazon Q Developer to understand the prerequisites for this type of transformation.

  1. To convert embedded SQL, you must first create a YAML file that contains the path to the schema metadata file from your AWS DMS Schema Conversion.

    Following is the required format of the file: 

    schema_conv_metadata_path: <path-to-metadata-zip-file>

  2. Run the following command to start a transformation for a SQL conversion. Replace <path-to-folder> with the path to the folder with the code you're transforming and <path-to-sql-config-file> with the path to the YAML file you created in step 1.

    qct transform --source_folder <path-to-folder>
    --sql_conversion_config_file <path-to-sql-config-file>

  3. If Amazon Q finds multiple schemas in your schema metadata file, it will stop the transformation and provide a list of the detected schemas. Choose which schema to use for the SQL conversion, and then add a new field schema: <schema-name> to the YAML file.

  4. Amazon Q begins the transformation. It will output status updates throughout the transformation. When it’s complete, Amazon Q provides the path where the transformation results, logs, and configuration files are outputted.

    Your upgraded code will be committed to the new branch Amazon Q created.