- 2. Enhancement Requests
- 🟥 P0 — Critical (workflow or correctness impact)
- 🟧 P1 — High (major workflow pain, manual workarounds exist)
- 🟨 P2 — Medium (quality-of-life / developer productivity)
Importance: Critical
Rationale: Currently, multiple DDL statements for the same object (for example, a table ALTER script) are often grouped under a single changeset.
This prevents Liquibase from properly tracking execution progress and makes failed deployments non-restartable.
Each distinct DDL operation (drop, add column, add constraint, etc.) should have its own changeset.
-- liquibase formatted sql
-- sqlcl_snapshot src/database/cla_apex/tables/cla_aircraft.sql:08bee489420289da19c387e5b924e0e21acc0faa:f6b3abb88fff315ad9e845989ec24ed6b54d31a3:alter
-- changeset CLA_APEX:1761764378736.1 stripComments:false logicalFilePath:dev-02\cla_apex\tables\cla_aircraft.sql
alter table cla_apex.cla_aircraft
drop (fl3xx_live);
-- changeset CLA_APEX:1761764378736.2 stripComments:false logicalFilePath:dev-02\cla_apex\tables\cla_aircraft.sql
alter table cla_apex.cla_aircraft add (
adult_critical_care number(1, 0),
aviapages_aircraft_id number,
aviapages_aircraft_type_id number,
year_of_production number
);
-- changeset CLA_APEX:1761764378736.3 stripComments:false logicalFilePath:dev-02\cla_apex\tables\cla_aircraft.sql
alter table cla_apex.cla_aircraft
add constraint make_model_serial_uk2 unique (aviapages_aircraft_type_id, serial_number)
using index enable;
-- changeset CLA_APEX:1761764378736.4 stripComments:false logicalFilePath:dev-02\cla_apex\tables\cla_aircraft.sql
alter table cla_apex.cla_aircraft
add constraint registration_uk1 unique (registration)
using index enable;- Restartability: If one DDL fails, Liquibase can resume from the next changeset instead of re-running everything.
- Traceability: Each schema change is clearly recorded as a separate step, improving review and rollback.
- Consistency: Matches Liquibase best practices — one logical change per changeset.
Importance: High
Rationale: It is very difficult to manage dozens of incremental changes within a single stage.changelog.xml file when all changes share the same branch name. Allowing users to define a custom change name would make each stage more isolated and easier to track.
Currently, the project stage command always uses the branch name as the “change” name, and all incremental changes are grouped under that single context.
This makes it hard to work with large or long-lived branches containing many separate features or database updates.
-
Add a parameter to the
project stagecommand
Allow users to explicitly set a change name, for example:project stage -change-name my_changeThis would generate changes under a clearly identifiable context rather than reusing the branch name.
-
Optionally support configuration commands for fine-grained control:
project config -set-change-name my_change project config -increase-change-number project config -reset-change-number project config -set-change-number
Allow change files to follow a predictable and unique naming convention such as:
branch_name#change_number
or
custom_name#change_number
This would dramatically improve readability, traceability, and parallel development within the same branch.
Importance: High
Rationale: When project stage is called multiple times for the same change, it completely rewrites the stage.changelog.xml file instead of simply appending new entries.
This behavior becomes very time-consuming in real projects, because the tool does not always put files in a logical order.
Developers often spend hours manually re-ordering dozens or even hundreds of changesets.
If just a few new objects are later added to the change, running project stage again will resort all files instead of appending only the new ones — effectively undoing the manual ordering work.
Re-running project stage should append only newly detected changesets to the end of stage.changelog.xml, leaving the existing order untouched.
- Do not regenerate or reorder the entire file when only new objects are added.
- Append new or modified changesets to the bottom.
- Optionally, remove (or comment out) obsolete entries.
This would allow developers to maintain a stable and meaningful order of objects in the changelog and prevent unnecessary manual re-sorting every time the file is regenerated.
Importance: High
Rationale: lb changelog-sync does not accept a “changeset ID” parameter, but it does support filtering by contexts.
When a deployment fails and you can’t use lb mark-next-changeset-ran (e.g., there are runAlways:true changesets before the failing one), you need a reliable, direct way to target the specific failed changeset.
Right now the Project does not generate a context tag per changeset, so there’s no precise selector you can use.
Automatically generate a unique context for every changeset.
A practical approach is to include the numeric changeset ID as a context value (and optionally a semantic one), so you can aim changelog-sync precisely.
Example (proposed output):
-- changeset CLA_APEX:1761764378736
stripComments:false
logicalFilePath:dev-02\cla_apex\tables\cla_aircraft.sql
context:1761764378736, dev-02, CLA_APEXTo manually sync that exact changeset:
lb changelog-sync -changelog-file releases/main.changelog.xml -contexts 1761764378736If there are runAlways:true changesets before the failing one, lb mark-next-changeset-ran will never reach your target; it keeps re-marking the earlier runAlways items.
A per-changeset context provides a direct line to the failing changeset without walking the chain.
| Aspect | Expected | Actual |
|---|---|---|
| Per-changeset selector | A unique context is generated for every changeset |
No context generated by Project |
| Manual sync | changelog-sync -contexts <that_one_changeset> |
Only coarse-grained options; no precise target |
Handling runAlways:true before failure |
Directly sync only the failed changeset | mark-next-changeset-ran can’t reach it |
- Generate
contextfor each changeset automatically. - Include both a stable unique context (e.g., the numeric changeset ID) and an optional semantic context (branch, schema, change name).
- Document the workflow for manual recovery.
Importance: Medium
Rationale: When exporting an APEX application, the existing directory under
src/database/<schema>/apex_apps/<app_id>/
is not cleared before a new export.
If components are deleted or renamed in APEX, the old files remain, producing stale or misleading content in Git.
This results in diffs that don’t accurately reflect the current state of the application.
Before exporting, the tool should automatically clear the directory:
rm -fR src/database/<schema>/apex_apps/<app_id>/*Then write the fresh export files.
- Incorrect Git state: Deleted components remain visible.
- Review noise: Old files persist, confusing reviewers.
- Deployment clutter: Obsolete objects may be unintentionally deployed.
Before every APEX app export, SQLcl Project should:
- Automatically remove the old export directory.
- Optionally log the cleanup (e.g., “Cleaning previous export for app 100”).
- Support an opt-out flag, e.g.,
--no-clean.
This guarantees that each export reflects the true current APEX state while maintaining clean version control.
Importance: Medium
Rationale: The project stage command currently compares the main branch only against the committed state of the current branch.
Any staged or untracked files are ignored, which forces developers to create unnecessary commits just to preview changes.
project stage should include all files in the current working directory (HEAD + staged + untracked).
- Compare main branch against working directory, not only committed state.
- Include staged and untracked files in diffs.
- No commit should be required before running
project stage.
This would align with standard Git workflows and reduce unnecessary commit churn.
✅ End of Enhancement Requests Section