This is a short post announcing a small but important change in the way you install SQLcl in GitHub Actions. The latest release allows you to install a specific SQLcl release in addition to the latest one.

The most straightforward approach to using SQLcl in GitHub Actions is via Gerald Venzl’s setup-oracle-sql GitHub Action. Since SQLcl is the backbone of my CI/CD workflows, I include it in every pipeline, like so:

name: Demo CI pipeline
on:
  push:
  pull_request:
jobs:
  unit-tests-and-build:
    runs-on: ubuntu-latest
    services:
      oracle:
        image: gvenzl/oracle-free:23.26.1
        env:
          ORACLE_PASSWORD: ${{ secrets.ORACLE_PASSWORD }}
          APP_USER: ${{ secrets.APP_USER_NAME }}
          APP_USER_PASSWORD: ${{ secrets.APP_USER_PASSWORD }}
        ports:
          - 1521:1521
        options: >-
          --health-cmd healthcheck.sh
          --health-interval 10s
          --health-timeout 5s
          --health-retries 10
      ords:
        image: container-registry.oracle.com/database/ords:25.4.0
        env:
          DBSERVICENAME: FREEPDB1
          DBHOST: oracle
          DBPORT: 1521
          ORACLE_PWD: ${{ secrets.ORACLE_PASSWORD }}
        ports:
          - 8080:8080
          - 8443:8443
        
    steps:
      - uses: actions/checkout@v6
      - name: setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
      - name: install test dependencies
        run: npm ci
      - name: setup SQLcl
        uses: gvenzl/setup-oracle-sqlcl@v1
        with:
          version: 25.4.2.044.1837

Have a look at lines 46-49: this is the part of the YAML file where SQLcl and the Java Runtime are installed.

Your Options

Compared to the previous action’s release you have more control over the version that’s deployed. You can either:

1. Feel lucky and simply get the latest SQLcl by not specifying any version at all, or
2. Pin the version you need in the form nn.n.n.nnn.nnnn

The second option should appeal to anyone working with SQLcl Projects. The Oracle SQLcl Projects feature allows users to manage the creation and administration of a database application. It is targeted towards enterprise-level applications that require structured release processes.

SQLcl Projects

As you may know, the SQLcl version is directly tied to the SQLcl project and listed in .dbtools/project.config.json:

{
  "project" : "myproject",
  "sqlcl" : {
    "connectionName" : "localhost_emily_1521",
    "autoConnect" : false,
    "version" : "25.4.2.0"
  },
  "schemas" : [ "EMILY" ],
  ...
}

The SQLcl release is listed in line 6. You should find the matching SQLcl release in its full form (25.4.2.044.1837 in my case), and specify it in your CI pipeline. Job done.

Summary

With the latest release of the setup-oracle-sqlcl action, you can either install the newest SQLcl or pin a specific version to match your SQLcl Projects configuration. Pinning helps avoid unexpected behavior during deployments (for example, when running project deploy).

The upgrade is seamless, the new release still flies under the gvenzl/setup-oracle-sqlcl@v1 flag. The next time your pipeline runs you can take benefit of the new feature.

Happy Coding!