Automate conversion of Oracle SQL to PostgreSQL inside Java applications with AWS SCT

Migrating database backends is a major challenge for organizations with Java applications that contain thousands of Oracle-specific SQL statements. Manually converting these queries to work with PostgreSQL is time-consuming, costly, and error prone.

In this post, you learn how to use the AWS Schema Conversion Tool (AWS SCT) to automate embedded SQL conversion, reduce migration effort, and provide a smooth transition to Amazon Relational Database Service (Amazon RDS) or Amazon Aurora.

AWS SCT is a desktop application designed to automate and simplify the migration of database schemas, application SQL, and code objects from commercial engines such as Oracle to open source engines such as PostgreSQL. It supports multiple programming languages including Java, C#, and C++, and it can scan application source files to extract embedded SQL. For Java developers in particular, SCT converts Oracle-specific SQL statements into PostgreSQL-compatible syntax, minimizing the need for deep engine-specific expertise.

Solution overview

One of the primary advantages of AWS SCT is that it can convert both database schemas and application SQL with minimal manual intervention. This automation helps organizations significantly reduce the effort and time typically required for manual code conversion, depending on the size and complexity of the codebase.

This post demonstrates how to use AWS SCT to simplify and accelerate the migration of embedded Oracle SQL code within Java applications to PostgreSQL-compatible syntax. The solution focuses on a practical use case involving a source Oracle database coupled with a sample Java application containing numerous Oracle-specific SQL statements. By using AWS SCT, developers can automate much of the schema and SQL conversion process, reducing manual effort and minimizing errors during migration. This approach provides a smoother transition to PostgreSQL or Aurora PostgreSQL-Compatible while preserving application logic.

Prerequisites for using AWS SCT

Before starting your migration with AWS SCT, you need to meet the following prerequisites:

• AWS SCT version – Use version 1.0.677 or later for Java 17 compatibility and full Oracle-to-PostgreSQL support
• Database credentials – You must have valid user credentials (username and password) for both your source Oracle database and your target PostgreSQL database to allow AWS SCT to connect to and access each system during setup

You need to meet the following system requirements to use AWS SCT:

• OS – Windows 10 (64-bit), Fedora 36+, or Ubuntu 18+ (64-bit)
• JDBC drivers – Install JDBC drivers for Oracle and PostgreSQL
• Java – Java Runtime Environment (JRE) is bundled; ensure compatibility with Java 17.
• Network connectivity – The host running AWS SCT must have network connectivity to the source (and, if used, target) databases to read schemas and perform conversions.
• Download and install AWS SCT – Obtain the AWS SCT installer appropriate for your operating system from the official Amazon Web Services (AWS) documentation, then follow the installation instructions to set up AWS SCT on your host machine

The solution follows these high-level steps:

1. Prepare your Java source files
2. Create a new AWS SCT project
3. Configure the source database connection (Oracle)
4. Configure the target database connection (PostgreSQL)
5. Configure the migration project
6. Review and handle manual conversions
7. Export converted SQL and Java files

Solution walkthrough: Migrate embedded Oracle SQL in Java using AWS SCT

In this section, we walk through each step required to convert Oracle SQL statements in your Java files to PostgreSQL using AWS SCT, with practical guidance for every phase.

Prepare your Java source files

To prepare your Java source files, complete these steps:

1. Collect all Java files containing Oracle SQL queries
2. Save them in a dedicated directory for convenient access during the migration process, as shown in the following screenshot.
   

Create a new AWS SCT project

To create a new AWS SCT project, complete these steps:

1. Open the AWS Schema Conversion Tool.
2. On the AWS SCT console, choose File and in the dropdown list, choose New project, as shown in the following screenshot.
   
3. Enter a Project name (such as sct-java-sql-conversion) and specify a Location for project files , as shown in the following screenshot.
   

Configure source database connection (Oracle)

1. On the navigation bar, choose Add source, as shown in the following screenshot.
   
2. To connect to your source Oracle database, under ALL CATEGORIES, choose Oracle, as shown in the following screenshot.
   
3. Enter connection details for Connection name, Server name, Server port, Oracle SID, User name and Password.
4. To confirm it’s configured correctly, choose Test connection on the bottom left, as shown in the following screenshot. Then choose Connect.
   

Configure target database connection (PostgreSQL)

To configure the target database connection, complete these steps:

1. On the navigation bar, choose Add target, as shown in the following screenshot.
   
2. To connect your target PostgreSQL database, under ALL CATEGORIES, choose Amazon RDS for PostgreSQL, as shown in the following screenshot.
   
3. Enter the connection details for Connection name, Server name, Server port, Database name, User name, and Password.
4. To confirm it’s configured correctly, choose Test connection on the bottom left, as shown in the following screenshot. Then choose Connect, as shown in the following screenshot.
   

Configure the migration project

To configure the migration project, complete these steps:

1. To map source schemas to the target schemas, on the Main view tab, choose Mapping view, as shown in the following screenshot.
   
2. Create mappings between your source Oracle schemas and the corresponding target PostgreSQL schemas if they don’t already exist.
   
3. To return to the main screen, select Mapping view on the navigation bar and then choose Main view from the dropdown menu, as shown in the following screenshot.
   
4. To create a Java application conversion project, in the left navigation pane, select your Oracle source connection. On the Applications tab, choose New Java Application.
   
5. Name the application conversion project and choose the schema your Java code interacts with, then specify the path to your Java source files, as shown in the following screenshot.
   
   Your Java application project will now appear in the Applications menu under Java, as shown in the following screenshot.
   
6. To browse your Java files within the project, open (right-click) the project name (sct-java-sql), then choose Convert, as shown in the following screenshot.
   AWS SCT will analyze the files, extract SQL statements, and attempt to convert them to PostgreSQL syntax.
7. To review the assessment report, in AWS SCT on the Main view tab, choose Assessment Report view, as shown in the following screenshot.
   

In the assessment report, you can review the executive summary, shown in the following screenshot.

On the Action items tab of the Executive summary, AWS SCT highlights SQL statements that were converted automatically and statements that require manual review or conversion (such as dynamic SQL and connectivity code). You can find recommendations and documentation links for unsupported features.

Review and handle manual conversions

To review and handle manual conversions, complete these steps:

1. As shown in the following screenshot, in this example, Oracle-specific functions such as SYSDATE, NVL, DECODE, and ROWNUM have been translated to their PostgreSQL equivalents: CURRENT_DATE, COALESCE, CASE, and LIMIT. This highlights how AWS SCT handles syntax differences between Oracle and PostgreSQL while preserving the original query logic within Java code.
   
2. As shown in the following screenshot, in this example, AWS SCT raises Issue 103009 when encountering Oracle’s INSERT ALL clause within a Java application. This construct isn’t supported in PostgreSQL, and SCT explicitly recommends manual conversion. Developers must rewrite the logic using multiple INSERT statements or a PostgreSQL function to handle batch inserts.
   

Export converted SQL and Java files

To export the converted SQL and Java files, complete these steps:

1. In the target pane, open (right-click) your converted Java application project and choose Save, as shown in the following screenshot.
   
2. Choose a directory to export the PostgreSQL-compatible Java files, as shown in the following screenshot.
   
3. Verify the converted files are in the selected directory.
   

For SQL or code that AWS SCT highlighted as requiring manual conversion, follow the recommendations from AWS SCT. Common manual tasks include handling dynamic SQL, setting time zones, or adapting unsupported Oracle-specific functions.

To confirm correct database connectivity and query execution, test the exported Java files in a development environment.

Best practices and troubleshooting

For best results, follow these best practice tips:

• Organize source code – Keep Java files with embedded SQL in a single directory for efficient analysis.
• Iterative conversion – For large codebases, convert and review in small batches.
• Performance optimization – After migration, review PostgreSQL query plans and indexes to ensure optimal performance. For more information, refer to RDS Aurora PostgreSQL performance assessment benchmarking.
• Validation – Run end-to-end integration tests to validate application functionality after the migration and use query plan analysis to benchmark and optimize performance.

If you experience problems, try these troubleshooting tips:

• For connection errors, verify the JDBC driver versions and network access
• For SQL conversion issues, consult the AWS SCT troubleshooting guide

Cleanup

After completing your migration demo or test, follow these steps to avoid ongoing costs and resource sprawl:

• Delete test databases – Remove the temporary Oracle or PostgreSQL instances used for testing.
• Remove AWS SCT projects – Delete SCT project files and exported code directories if no longer needed.
• Revoke IAM permissions – Remove or limit AWS Identity and Access Management (IAM) roles that were granted for the migration process.
• Clean up S3 buckets – If you used Amazon Simple Storage Service (Amazon S3) for extension packs or logs, delete unused objects.

Conclusion

In this post, you learned how to use AWS SCT to streamline Oracle-to-PostgreSQL migrations, and you’re now equipped with resources and next steps to continue your migration journey with confidence.

To learn more and get started with AWS Schema Conversion Tool, refer to the official AWS SCT User Guide and Converting SQL code in Java applications with AWS Schema Conversion Tool in the AWS SCT User Guide, which provides a comprehensive guide from installation to advanced usage and best practices.

About the authors