The part that hurts you later is not on that page.

The AWS Schema Conversion Tool for Oracle grades syntax. It tells you whether it could emit valid PostgreSQL for an object. It does not tell you whether that object will behave the same way at runtime. A trigger can convert with a green tick and fire in a different order. A column can convert with a green tick and silently drop the time component off every date in the table. A procedure can convert with a green tick and run twenty times slower because every string function call now goes through a wrapper.

This post sorts the tool’s output into four buckets: what converts cleanly, what converts while quietly changing meaning, what converts only through the extension pack, and what it refuses outright. Then the category nobody budgets for, which is everything it never looks at.

What the AWS Schema Conversion Tool for Oracle actually does

It is a Java desktop application. It connects over JDBC to source and target, reads the Oracle data dictionary, parses the DDL and PL/SQL it finds, and generates equivalent PostgreSQL objects and PL/pgSQL. The converted code stays inside the project until you explicitly apply it to the target or save it out as SQL files.

Three things follow from that description, and they matter more than any feature list.

• It only sees what is stored in the database. Code that lives in your application, your job scheduler, or a reporting tool is invisible to it unless you point the separate application SQL conversion feature at those files yourself.
• It only sees what the connecting user can see. Connect with a thin account and half the schema will not appear in the report at all.
• It moves structure and code. It does not move rows. That is AWS DMS, and it is a separate exercise with its own failure modes.

There is also a command line interface, which is the part most teams discover too late. It uses scenario files rather than flag-style arguments, and it needs Amazon Corretto 11 installed alongside the tool.

# Interactive mode, run from the AWS SCT app folder.
# End each command with a / on its own line.
java -jar AWSSchemaConversionToolBatch.jar -type interactive

# Script mode, running a saved .scts scenario end to end.
java -jar /opt/aws-schema-conversion-tool/lib/app/AWSSchemaConversionToolBatch.jar 
  -type scts -script /home/sct/project/convert.scts

Script mode turns a one-off conversion into something you can rerun, which matters because on a real migration you will convert the schema many times as you clean up the source. Re-clicking through the GUI each time is how mistakes creep in.

Tier one: converts cleanly, and you can trust it

Credit where it is due. For the bulk of an ordinary OLTP schema the tool is good, and hand-writing this would be miserable.

• Table definitions: names, columns, ordinary data types, NOT NULL, defaults, primary keys, unique constraints, foreign keys.
• Standard b-tree indexes, including most single-column functional indexes.
• Ordinary views. The basic CREATE VIEW syntax is close to identical between the two engines.
• Sequences and identity columns, despite the syntax looking nothing alike.
• ANSI-standard SQL, joins, subqueries, and almost all window and analytic functions.
• PL/SQL flow control: loops, blocks, conditionals, exception structure.
• The four standard transaction isolation levels, plus BEGIN, COMMIT, and ROLLBACK.

If your schema is mostly tables, views, and reporting SQL with modest procedural code, the automation figure in the report is roughly honest and you should believe it.

Tier two: converts green, behaves differently

This is the tier that costs money, because none of it shows up as a red action item. The object converted. The DDL applied. The application connected. Something is wrong three weeks later and nobody thinks to look back at the schema conversion.

Oracle DATE is not PostgreSQL date

Oracle’s DATE type carries a time component down to the second. PostgreSQL’s date is a calendar day and nothing more. Map an Oracle DATE to a PostgreSQL date and every timestamp in that column is truncated, permanently, without an error. The correct target is timestamp. Check the conversion settings and check the generated DDL before you apply, because this one is not recoverable after the data lands.

NUMBER without precision becomes numeric, and numeric is slow

An unqualified Oracle NUMBER is an extremely flexible container, so the default mapping to PostgreSQL numeric is technically correct. It is also arbitrary-precision arithmetic implemented in software. Put that on a surrogate key that participates in every join and index in your application and you have bought yourself a performance problem that no amount of index tuning will fix.

Find the candidates before conversion, not after:

-- Oracle: unqualified NUMBER columns, the ones that default to numeric.
SELECT table_name, column_name, data_precision, data_scale
FROM   user_tab_columns
WHERE  data_type = 'NUMBER'
AND    data_precision IS NULL
ORDER  BY table_name, column_name;

For each one, look at the actual minimum, maximum, and scale of the data, then decide whether it is really an integer, a bigint, or a genuine numeric(p,s). Surrogate keys and foreign keys are almost always integers pretending to be NUMBER. Money columns usually are not.

Empty string is NULL in Oracle and is not in PostgreSQL

This is the single most reliable source of post-cutover bugs, and it is not a conversion defect. Oracle treats an empty string as NULL. PostgreSQL treats it as a zero-length string, which is a real value. Every IS NULL check in your procedural code and your application was written under Oracle’s rule.

Concatenation flips too. In Oracle, concatenating a NULL is a no-op. In PostgreSQL, concatenating a NULL with the || operator yields NULL for the whole expression. A report that used to print a name with a missing middle initial now prints nothing at all.

After the data lands, count the divergence before you let users near it:

-- PostgreSQL: how many rows are empty string rather than NULL?
SELECT count(*) FILTER (WHERE middle_name = '')   AS empty_string,
       count(*) FILTER (WHERE middle_name IS NULL) AS real_null
FROM   app.customer;

If empty_string is non-zero anywhere, you have a decision to make: normalize the data on load, or audit every NULL check that touches those columns. Normalizing is usually cheaper and is far easier to verify.

The warnings the tool does raise, that people scroll past

Some of these semantic differences do appear in the action list, just not in red. They are worth reading individually rather than in aggregate.

• GREATEST and LEAST are flagged as potentially producing different results from the source, because of how each engine handles NULL arguments and type coercion.
• Timestamp handling inside converted partitioned tables is flagged as potentially divergent.
• Converted code is flagged as possibly incorrect where bind variable names, user-defined functions, or dynamic SQL are involved. That is the tool telling you it guessed.
• Trigger firing order is not carried over. Oracle’s FOLLOWS and PRECEDES clauses have no equivalent, and PostgreSQL fires triggers on the same event in alphabetical order by trigger name. If your Oracle triggers depended on sequencing, you now depend on naming.
• An empty exception block in the converted output is called out explicitly. Oracle code that swallowed errors will now swallow them differently.

One more that is not an action code at all: Oracle PL/SQL routinely issues COMMIT in the middle of a procedure. A PostgreSQL function cannot do that. Either the logic becomes a procedure invoked with CALL, or the transaction boundary moves out into the calling application. That is a design decision, not a find-and-replace.

Tier three: converts, but only through the extension pack

When there is no native PostgreSQL equivalent for something Oracle provides, the tool installs an extension pack: an additional schema on the target, named aws_oracle_ext for Oracle sources, containing wrapper functions, tables, and supporting objects that emulate the source behavior. For some capabilities like job scheduling and sending mail, the pack also deploys AWS Lambda functions.

So a call to INSTR in your PL/SQL comes out the other side as aws_oracle_ext.INSTR. Package variables, which have no PostgreSQL equivalent because PL/pgSQL has no packages, get routed through getter and setter functions in the pack.

The case for accepting this is real. If the goal is off Oracle licensing by a fixed date, the pack converts code that would otherwise need a developer per object. That is the difference between a migration that ships and one that stalls in refactoring, and nobody gets a bonus for elegant PL/pgSQL on a project that missed its window.

The case against is equally real:

• Wrapper functions sit between your code and the engine. In hot loops, that overhead is measurable, and the package-variable emulation in particular is not free.
• You have swapped one dependency for another. The pack is AWS-specific code living in your database, which is an awkward thing to explain if the stated goal was ending vendor lock-in.
• Every time the pack is applied, its components are overwritten. Anything you hand-tuned inside that schema is gone.
• Upgrades and target-version changes now have an extra moving part to validate.

There is a middle path. The tool can be configured to use the open-source orafce extension, which implements a subset of Oracle functions and packages natively in PostgreSQL, in place of some pack wrappers. My rule of thumb: use the pack to get the migration over the line, then treat the size of the aws_oracle_ext call graph as a debt register you burn down deliberately, starting with whatever appears in your slowest queries. Rewriting collections as native arrays or JSON, and package variables as parameters, buys back most of the performance.

Tier four: it stops and hands you the work

These are the red items: the honest part of the report, and paradoxically the least dangerous, because you can see them and plan around them. Not exhaustive, but this is what turns up on real Oracle schemas.

• Database links. No automation at all. The mechanism has to be rebuilt, usually on postgres_fdw, and foreign data wrappers do not support calling user-defined functions on the remote side. If your architecture leans on links, this is a workstream, not a task.
• Autonomous transactions. PostgreSQL has no direct equivalent. Logging patterns that relied on committing independently of the parent transaction need redesign, often with dblink back to the same instance or an out-of-band queue.
• ROWID and UROWID. No equivalent, and any code that reads ROWID from a table is flagged separately. Row-identity tricks in PL/SQL are a rewrite.
• Dynamic SQL and DBMS_SQL. Anything assembled at runtime the parser cannot resolve statically comes back untouched or with a health warning.
• Synonyms. Not supported, and neither is their usage, so every reference through a synonym has to be resolved by hand or mimicked with views and search paths.
• Global temporary tables, index-organized tables, external tables, clustered tables, object tables, nested tables, virtual columns, BFILE. Storage and type features with no target equivalent.
• Bitmap indexes, domain indexes, multi-column functional indexes. The first two have no counterpart; the third is a documented conversion gap.
• Associative arrays, VARRAY of VARRAY, multi-dimensional arrays, object type methods, member functions in user-defined types. Collection-heavy PL/SQL is where the automation percentage collapses.
• Compound triggers, system triggers, REFERENCING clauses, conditional predicates. The trigger model differs enough that anything beyond a plain row trigger needs attention.
• Java stored routines and table functions. Not converted.
• Query hints. Partially converted, and you should delete them all first anyway. Hints tuned for Oracle’s optimizer are noise to a different planner. Add them back only after schema, index, and query work have failed.
• Materialized view incremental refresh and DML on materialized views. The view itself may convert; the refresh strategy will not.

Some red items are more conservative than your actual target

Here is a detail that saves real budget. The action code index and the migration playbook were written against a baseline target, and PostgreSQL has moved since. MERGE is listed as unsupported, but PostgreSQL has had a native MERGE statement since version 15. FOR UPDATE SKIP LOCKED is listed as unsupported, and it has been in PostgreSQL for a long time. GROUPING SETS, CUBE, and ROLLUP are listed as unsupported and are also long-standing PostgreSQL features.

What this means practically: an action code tells you the converter will not emit the construct for you. It is not a statement about your target engine. Before you scope a rewrite for anything on that list, check the feature against the PostgreSQL version you are actually deploying. Some of those “rewrites” are a copy-paste with a syntax tweak.

What it never looks at

This is the category that wrecks timelines, because it is not in the report at all. Not green, not red. Out of scope, therefore invisible.

• Application code. There is a separate application SQL conversion feature that scans source files for embedded SQL, but it is opt-in, file-based, and you have to aim it. Nothing happens automatically.
• Scheduled work. DBMS_SCHEDULER jobs, cron entries calling SQL*Plus, shell wrappers, ETL controllers. The schema converts; the thing that runs it every night does not.
• Grants, roles, profiles, and proxy authentication. Your security model is a separate design exercise on the target.
• Oracle features with no schema footprint. Data Guard, RAC, ASM, RMAN, Oracle Text indexes, fine-grained access control policies. Each is its own replacement decision.
• Optimizer statistics and execution plans. Nothing about performance carries over. You are starting from zero on the target, and that is the right expectation to set with stakeholders early.
• Everything downstream. BI dashboards, reporting layers, and integration jobs that embed Oracle-flavored SQL will break on the day you cut over, and none of them appear in the assessment.

Inventory these before conversion, not after. A one-page list of every consumer of the schema is worth more than a week of tuning.

Desktop tool or DMS Schema Conversion?

DMS Schema Conversion is the managed, browser-based version built on the same engine. Instead of a laptop install you create an instance profile, register source and target data providers with credentials in Secrets Manager, and run the project from the console, with metadata staged in S3.

AWS now points standard OLTP conversions at the managed option, and generative AI assisted conversion is available there on supported paths. The desktop tool remains available and still covers ground the managed feature does not.

• Pick the desktop tool when you need scripting through the CLI, want to edit the SQL for source and target inside the project, need migration rules and tree filters, are converting a data warehouse target, or want the application SQL and ETL conversion features.
• Pick DMS Schema Conversion when your source is reachable from a VPC, you would rather not manage a workstation with database credentials on it, your conversion path and region are supported, and the generative AI assist is useful to you.

Check supported paths, versions, and regions before committing either way; they differ between the two. On the desktop side, note the supported operating systems are Windows, Fedora, and Ubuntu, all 64-bit. If your analysts are on Macs, plan for a Linux jump box. A small VPS from a provider like Contabo or InterServer, or an EC2 instance inside the VPC, is the usual answer, and it has the side benefit of keeping the JDBC connection close to the source rather than dragging a dictionary read across a home broadband link.

If the Oracle source is on-premises and the conversion box is not, you need a network path that a DBA will sign off on. That is normally a site-to-site VPN or Direct Connect. For an individual consultant working against a client’s staging environment, a commercial VPN such as NordVPN or Surfshark is sometimes what is on offer, but treat it as a stopgap: it gets you connectivity, not an audit trail.

Troubleshooting

The CLI jar refuses to open

A common failure is an unexpected error opening AWSSchemaConversionToolBatch.jar. Recent OpenJDK builds cap the size of jar signature files and the SCT jar exceeds the default. Raising that limit on the java invocation is the widely reported workaround:

java -Djdk.jar.maxSignatureFileSize=20000000 
  -jar AWSSchemaConversionToolBatch.jar -type interactive

Confirm you are on the Corretto 11 runtime the tool expects before chasing anything more exotic.

It hangs on a large schema, or will not connect at all

Thousands of objects in one schema puts the JVM under memory pressure; Global settings exposes JVM options, so raise the heap and retry on a machine with real memory. Separately, JDBC driver paths live in Global settings under Drivers, per engine. A driver sitting on disk but not registered there fails in a way that looks like a network problem and is not.

“The package body doesn’t include source code”

The source is wrapped. Obfuscated PL/SQL cannot be parsed, so it cannot be converted. Either find the original in version control or accept a from-scratch rewrite. Finding this on a critical package late in the project is a bad day, so check for wrapped objects on day one.

Objects will not apply, or the report is missing things

Failures on apply are usually dependency order: an object references a parent that was not converted or sits outside the schema mapping, and the action list says so explicitly. Convert the whole dependency closure, not just the objects you care about. A short report is usually privileges, since the tool reads through the connecting account’s visibility. Compare its object counts against a direct dictionary count before trusting any percentage in it.

Common mistakes

• Treating the automation percentage as a completion estimate. It measures objects, not effort, and one gnarly package can outweigh four hundred clean tables.
• Applying to the target before reviewing the generated DDL. Save to SQL, read it, diff it on the next run.
• Accepting default type mappings wholesale. DATE and unqualified NUMBER are the two that reliably hurt.
• Carrying Oracle hints across. Start with none and earn each one back.
• Scoping rewrites straight off the action codes without checking your target PostgreSQL version first.
• Leaving project files and scenario scripts containing database credentials sitting on a laptop after the engagement. They are plain files; when the work is done, wipe them properly with a tool like O&O SafeErase rather than dragging them to the trash.

Best practices

1. Connect with an account that can see the whole schema, then verify object counts against the dictionary before reading any percentage.
2. Profile your NUMBER and DATE columns first and set the type mappings deliberately. Do this before the first conversion, not after the first load.
3. Script the conversion with the CLI so every run is identical and reviewable.
4. Sort red action items by object criticality, not by count. Twenty flags on a nightly batch job matter more than two hundred on a deprecated reporting view.
5. Write the semantic test suite before cutover: empty string versus NULL, date boundaries, numeric rounding, trigger ordering, transaction behavior in converted routines.
6. Instrument the target from day one. Query-level metrics in Amazon CloudWatch, or a Grafana stack against pg_stat_statements, will show you which extension pack wrappers are actually costing you before users complain.

Frequently asked questions

Is the AWS Schema Conversion Tool free?

The tool itself is a free download from AWS. What you pay for is everything around it: the compute you run it on, the target database, DMS replication instances for the data move, and the engineering time on the objects it hands back to you. That last item is the whole budget on most migrations.

Does it migrate data as well as schema?

No. It converts structure and code. Moving rows is AWS DMS, which handles both a full load and ongoing change capture. They are designed to be used together, and each has its own set of behaviors worth understanding separately.

Can I skip the extension pack entirely?

You can, but you are then hand-writing PostgreSQL equivalents for every Oracle built-in the pack would have covered. Configuring the tool to prefer orafce where possible is the usual compromise: fewer AWS-specific wrappers, open-source implementation, still automated. Full independence is achievable and is a refactoring project, not a setting.

Why did my report say 95% automatic and the project still take months?

Because the percentage counts objects, ignores runtime semantics entirely, and excludes application code, scheduled jobs, security, and downstream consumers. Tier two and the out-of-scope list in this post are where the months go.

Should I clean up the Oracle schema before or after conversion?

Before, every time. Dropping dead objects, unwrapping code you own, and removing synonyms on the source reduces the surface the tool has to reason about and shrinks the red list. It is also the only cleanup you can do while you still have a working system to test against.

How do I verify the conversion actually worked?

Row counts and DDL comparison are the floor, not the ceiling. Run the same business queries against both engines and compare results, with deliberate coverage of NULL handling, date boundaries, sorting and collation, and numeric rounding. Anything that only shows up under concurrency needs a load test, not a smoke test.

The one thing worth remembering

The AWS Schema Conversion Tool for Oracle is a good parser and an honest one about the things it cannot parse. The red list is trustworthy. The trouble is that a green tick means “I emitted valid PostgreSQL,” not “this behaves the way it did.” Dates lose their time, unqualified NUMBER lands as slow arithmetic, empty strings stop being NULL, triggers reorder themselves alphabetically, and none of that appears as a problem in the report.

Use it for what it is good at, which is the tedium you should never do by hand. Then spend your review time on the objects that passed, because that is where the expensive surprises live. Treat the assessment report as an inventory, never as a schedule.

Need a second pair of eyes on an Oracle to PostgreSQL conversion?

Most of the value in this work is in the review, not the click. Things I help with:

• Reading an assessment report properly: separating object counts from real effort, and re-scoping red items against the PostgreSQL version you are actually deploying.
• Auditing type mappings before you apply, with a column-level profile of NUMBER and DATE usage and a concrete mapping decision for each.
• Building the semantic test suite that catches empty-string and NULL divergence, trigger ordering, and rounding differences before users find them.
• Scripting the conversion through the SCT CLI so it is repeatable, reviewable, and lives in version control alongside the generated DDL.
• Planning the extension pack burn-down: which aws_oracle_ext calls are costing you, and what the native PostgreSQL replacement looks like.
• Mapping the out-of-scope surface, meaning scheduled jobs, grants, downstream reports and integrations, so cutover day has no surprises in it.

Send me an assessment report, a converted DDL file, or the action item list, and I will tell you what I would actually worry about in it.

The post AWS Schema Conversion Tool for Oracle: What Converts and What Quietly Doesn’t appeared first on John Nessime.