6.6 Upgrading SQLcl When Using SQLcl Projects

With the SQLcl Projects feature, a structured approach is required to upgrade SQLcl so as to minimize disruption and ensure consistency across the team. This section describes the process for upgrading SQLcl when using SQLcl Projects, along with key considerations for timing and implementation.

6.6.1 When to Upgrade

The best approach for upgrading SQLcl 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 about the SQLcl upgrade and ensure that they stop working with SQLcl in the repository until the process is complete.

You can upgrade SQLcl even if there is work in progress that crosses sprint boundaries. However, you must modify the process described in the next section to suit your requirement.

6.6.2 Upgrade Process

To upgrade SQLcl, do the following:

1. Create a feature branch for the upgrade.

   Branch off from main (or the equivalent stable branch) and 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 the 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 that team members are using the intended version after the upgrade is complete.

3. Refresh src/database.

   SQLcl Projects is handled differently based on the version of SQLcl. This means you need to ensure that src/database is aligned with the new version.

   The recommended approach:

   • Delete src/database completely.

   • Re-export the project using the updated version of SQLcl.

   This is a significant step because it ensures all definitions and configurations are regenerated according to the new SQLcl behavior.

   Discuss with the team to find out if any project-specific considerations may affect this step. For example, if you are using a shared Development Database and there is a feature crossing sprint boundaries that is not ready for export, consider alternatives such as starting up a temporary database, running the installer there, and then exporting from that database.

4. Merge the branch to main.

   After the update is complete, merge the feature branch back into main.

   At this point:

   • The upgrade is officially complete.
   • The team must download the correct SQLcl version before starting new work.
   • New feature branches are created using the updated SQLcl version.