SQLcl Projects vs. Liquibase: A Comparison

For the past two years, I’ve been using Liquibase (open-source version) to manage database objects in my Oracle APEX projects. Since I work exclusively with the Oracle database, I never had to explore Liquibase’s support for other databases.

But in Oracle SQLcl 24.3, SQLcl Projects was introduced, and it could be a game-changer for CI/CD in APEX development. So, what exactly does SQLcl Projects do? And how does it compare to Liquibase?

Liquibase: The Open-Source Standard for Database Versioning

Liquibase is a widely used open-source database schema management tool that helps track, manage, and apply database changes. It supports many databases, including Oracle, and also offers a paid version, though the free version has been sufficient for my needs.

How Liquibase Works

Typically, you create a Liquibase project. After initializing the project, Liquibase generates the necessary configuration files into a folder. These files can be tracked with Git or SVN.

Database changes in Liquibase are defined in changesets—each representing a specific modification, such as creating or altering a table. Every changeset has a unique identifier, which Liquibase uses to track changes.

Changesets are usually organized within changelog files, and those changelogs can reference other changelogs for better organization.

Deploying Changes with Liquibase

Once your changesets are ready, you deploy them using the liquibase update command. The first time you do this, Liquibase creates two key tables in your database:

• databasechangelog – Stores a record of all executed changesets, including timestamps and checksums

• databasechangeloglock – Prevents multiple deployments from running at the same time

When deploying, Liquibase checks if a changeset has already been executed by looking at databasechangelog. If it hasn’t, Liquibase applies it in the order defined in the changelog file.

If an error occurs, Liquibase stops execution immediately.

You can deploy changes directly to a database (liquibase update) or generate a SQL script (liquibase update-sql), which can be useful in a CI/CD pipeline.

For my APEX projects, I used Liquibase in this way: Whenever a change was needed, we manually created new changesets or updated existing ones. Then, we deployed the changes to the development database using Liquibase, and afterward, the changes were committed to Git. The changesets were written in SQL, making them easy to read and review.

---

SQLcl Projects: A new way for Oracle Databases

SQLcl Projects takes a different approach. Compared to Liquibase, it’s more structured and more automated.

Getting Started with SQLcl Projects

When you initialize a SQLcl Project, a specific folder structure is created.

To use SQLcl Projects, you need:

1. SQLcl (version 24.3 or higher)

2. A Git repository (must be Git—SVN is not supported) with at least two branches (e.g., dev and prod)

3. An Oracle database

Development Workflow

Unlike Liquibase, where changesets are manually written or generated as XML, SQLcl Projects begins with making changes directly in the database.

You develop using SQL Developer or another tool, then run in SQLcl: project export

This exports your schema objects into the src folder of your SQLcl Project. You can exclude specific objects in the filters/project.filters file.

Once your changes are committed to Git, you run: project stage

This compares the current Git branch (e.g., dev) with the default target branch (e.g., prod). If differences exist, SQLcl automatically generates Liquibase-style changesets and organizes them in the dist/releases/next folder.

Deploying Changes with SQLcl Projects

When you’re ready to release, you:

1. Run project release – Moves changesets from next to releases/versionXXX

2. Run project generate-artifact – Bundles all changesets into a deployment package

3. Run project deploy – Applies the deployment package to the target database

SQLcl uses the same Liquibase databasechangelog table to track deployments, meaning it deploys only new changesets.

---

Key Similarities Between Liquibase and SQLcl Projects

Since SQLcl Projects internally uses the same logic as Liquibase, both tools share some key features:

✔ Changesets & changelogs – Database changes are tracked using changesets, organized in changelogs
✔ Deployment tracking – Both use the databasechangelog table to determine what changes have been applied
✔ Error handling – If a deployment fails, it stops at the point of failure

---

Key Differences Between Liquibase and SQLcl Projects

---

Rollback: A Key Difference

Liquibase Rollback

Liquibase can auto-generate rollback scripts, if XML-Changesets are used. Manually created SQL-Rollback scripts are also possible.

• If you drop a table, rollback can recreate it, but data will be lost.

• Some statements cannot be rolled back properly.

Because of these risks, Liquibase recommends a "go-forward" approach, meaning you fix mistakes with new changes rather than rolling back.

SQLcl Projects: No Rollback

SQLcl Projects does not support rollback at all. If a deployment has issues, you must apply a new release with the necessary fixes. This enforces the "go-forward" approach by default.

---

Support for Multiple Databases

• Liquibase can manage many databases (Oracle, PostgreSQL, MySQL, etc.), but changesets must be XML-based for cross-database support.

• SQLcl Projects only supports Oracle, making it a great choice if you’re committed to the Oracle ecosystem.

---

SQLcl Projects & APEX: A Major Advantage

One huge benefit of SQLcl Projects for APEX developers is its built-in support for APEX applications.

• APEX apps can be exported as YAML files for better version control and easier review.

• APEX export settings (like original IDs or translations) can be included in the config file, reducing the risk of accidentally missing them.

• When you create a release, the APEX app is automatically bundled and deployed along with database changes.

For APEX teams, this is a major advantage over Liquibase, which does not handle APEX deployments natively.

---

Conclusion

SQLcl Projects is an exciting new tool for Oracle database and APEX development. It automates many of the steps that need to be manually handled in Liquibase, making it easier for beginners.

While Liquibase offers more flexibility (especially with multi-database support and rollback options), SQLcl Projects simplifies database versioning with a structured workflow and built-in Git integration.

Since SQLcl Projects is still evolving, I expect even more features in future releases. The development team has been very helpful, so if you need a feature from Liquibase that’s missing, they might offer a workaround or even implement it in a future update.

For APEX developers, SQLcl Projects is a clear winner due to its seamless APEX integration. If you're working purely with Oracle, it's definitely worth trying out!