Keeping your development tools up to date is essential for smooth collaboration and to take advantage of the latest features and fixes. When working with SQLcl Projects, upgrading SQLcl requires a structured approach to minimize disruption and ensure consistency across your team.
This post outlines a straightforward process for upgrading SQLcl while using SQLcl Projects, including key considerations for timing and implementation.
Timing: When to Upgrade SQLcl
Timing is crucial when upgrading SQLcl in a project. The best approach is to wait until the end of a sprint, when all work is completed. This ensures:
No active development is disrupted.
Team members are aware of the upgrade and can plan accordingly.
The transition to the new SQLcl version is smooth and consistent.
Before starting, notify the team that SQLcl is being upgraded and that they should pause work with SQLcl in the repo until the process is complete.
If you always have work in progress that crosses sprint boundaries, you can still upgrade SQLcl safely, but you’ll need to modify the process I outline below some depending on your situation.
Upgrade Process
Once the sprint has concluded and the team is prepared, follow these steps to upgrade SQLcl:
1. Create a Feature Branch for the Upgrade
Branching off from main (or the equivalent stable branch), create a feature branch dedicated to the SQLcl version update. This keeps the upgrade isolated from ongoing development and allows for review before merging.
2. Update Project Configuration
Modify the sqlcl.version property in the project configuration (found in .dbtools/project.config.json) to reflect the new version of SQLcl. This ensures all team members will be using the intended version once the upgrade is complete (note that the property isn’t enforced just yet, but it will be).
3. Refresh src/database
Different versions of SQLcl handle SQLcl Projects slightly differently, which means you need to ensure that src/database is aligned with the new version's expectations.
The recommended approach:
Delete
src/databaseentirely.Re-export the project using the updated version of SQLcl.
This is a significant step, as it ensures all definitions and configurations are regenerated according to the new SQLcl behavior.
Discuss with the team if any project-specific considerations might affect this step. For example, if you’re using a shared DEV DB and there’s in-flight work (a feature is crossing sprint boundaries), you wouldn’t want to export that work half-baked. You’ll need to consider alternatives in this situation, such as starting up a temporary DB, running the installer there, and then exporting from that DB.
4. Merge the Branch to main
Once the update is complete, merge the feature branch back into main. At this point:
The upgrade is officially complete.
The team should download the correct SQLcl version before starting new work.
New feature branches should be created using the updated SQLcl version.
Conclusion
Upgrading SQLcl in a SQLcl Projects setup is straightforward but requires careful planning. By timing the upgrade correctly and following a structured process, you can ensure a smooth transition with minimal disruption.
With the new version in place, the team can start the next sprint using the latest SQLcl features while maintaining a consistent development environment.