11.9 DIFF

Use this command to compare two Oracle Database schemas and generate an artifact file containing the necessary changes to synchronize them. This is especially useful for CI/CD workflows, and the final output can be deployed anywhere as needed.

Syntax

diff|di -source <source> [-target <target>] [-artifact-out <artifact-out>] [-verbose] [-debug]

Options

Option	Description
Required
-source <source>	Specify the saved connection name for the source database to be compared.
Optional
-target <target>	Specify the saved connection name for the target database. If omitted, the current connection is used as the target.
-artifact-out <artifact-out>	Specify directory path where the generated artifact is saved. Defaults to the current directory if not specified.
-verbose	Specify to output additional details, such as detailed steps, during execution.
-debug	Specify to show debug information in the output.

DIFF Command Usage Workflow

• Execute the DIFF command with the required -source option, and optionally specify other options to control comparison and output.
• The command compares schemas and generates an artifact (zip file) containing scripts to synchronize the source with the target. Each artifact generated by the Diff command is structured so that you can easily audit, review and understand the changes it will apply. The artifact zip file contains:

  ├── env
  │   ├── defaultProperties.sql
  │   └── undefineDefaultProperties.sql
  ├── install.sql
  ├── releases
  │   ├── main.changelog.sql
  │   └── next
  │       ├── changes
  │       │   └── target_<schema_name>
  │       │       └── stage.changelog.sql
  │       │       └── <object_type>
  │       │           └── <object_name> 
  │       └── release.changelog.sql
  └── utils
      ├── prechecks.sql
      └── recompile.sql

  install.sql

  Main entry point for deploying the artifact. By default, it references the changelog and can include optional scripts (prechecks.sql, recompile.sql), which are commented out by default. Edit this file to enable if needed

  releases/main.changelog.sql

  Orchestrates all object changes needed to synchronise the source schema with the target.

  releases/next/changes/target_<schema_name>

  Contains categorized changes grouped by object type. Each change is related to an object from the file objectname.sql (for example, TABLE/EMPLOYEE.sql).

  Note:

  The artifact includes env/defaultProperties.sql and env/undefineDefaultProperties.sql, which manage environment properties dynamically during deployment and clean them up afterward. These files are always present by default, but are not used by the DIFF command itself.
• Audit or review the changes before deployment by performing the following steps.
  1. Locate the artifacts zip file generated by the Diff command in the specified output directory.
  2. Extract the contents if you want to browse files directly.
  3. Navigate to /releases/next/changes/target_<schema_name>/ to find categorized folders (For example, TABLE, VIEW, PROCEDURE).
  4. Examine object-level change files (for example, TABLE/EMPLOYEES.sql) for SQL changes to be applied.
  5. Compare these scripts with current schema definitions as needed to verify or understand the differences.

  This review helps minimizing the risk of unexpected changes in production environments.

• Deploy the artifacts to execute the provided scripts to align the source schema with the target:

  project deploy -file Path/To/Diff/Generated/Artifact

Examples

DIFF -source Named1 -target Named2

DIFF -source Named1 -verbose -artifact-out /Path/to/artifact

DIFF -source Named1 -target Named2