Thus, I decided to test it out. This worked fine on my Always Free ADB, as it has been automatically upgraded to 23.26.1, the required version for this new feature.

Rather than create example assertions, I turned to Codex to do it for me based on data in the EMP table.

Using the following prompt:

using data in emp, create a group of SQL assertions. SQL assertions are new in Oracle, have a look here for how to create them: https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/create-assertion.html

Codex generated the following:

create assertion if not exists emp_ename_not_blank check (not exists (select 1 from emp where ename is null or trim(ename) is null)) enable validate;

create assertion if not exists emp_job_not_blank check (not exists (select 1 from emp where job is null or trim(job) is null)) enable validate;

create assertion if not exists emp_empno_nn check (not exists (select 1 from emp where empno is null)) enable validate;

create assertion if not exists emp_mgr_not_self check (not exists (select 1 from emp where mgr = empno)) enable validate;

create assertion if not exists emp_mgr_exists check (not exists (select 1 from emp where mgr is not null and mgr not in (select empno from emp))) enable validate;

create assertion if not exists emp_dept_exists check (not exists (select 1 from emp where deptno is not null and deptno not in (select deptno from dept))) enable validate;

create assertion if not exists emp_deptno_nn check (not exists (select 1 from emp where deptno is null)) enable validate;

create assertion if not exists emp_sal_positive check (not exists (select 1 from emp where sal is not null and sal <= 0)) enable validate;

create assertion if not exists emp_comm_nonnegative check (not exists (select 1 from emp where comm is not null and comm < 0)) enable validate;

create assertion if not exists emp_sal_upper_bound check (not exists (select 1 from emp where sal is not null and sal > 1000000)) enable validate;

While some of these are interesting (salary upper bound, commission not negative), most of them are duplicative of not null, PK and FK constraints already in place.

Not a problem. I just refined my prompt slightly:

create some assertions that are not copies of things like PK, FK, etc. look at the business rules embedded in the data and create some based on those

This time, I got a much better set of assertions:

create assertion if not exists emp_br_president_rules check ( not exists ( select 1 from emp where job = 'PRESIDENT' and (mgr is not null or comm is not null or deptno <> 10) ) ) enable validate;

create assertion if not exists emp_br_non_sales_no_comm check ( not exists ( select 1 from emp where job <> 'SALESMAN' and comm is not null ) ) enable validate;

create assertion if not exists emp_br_sales_in_dept30 check ( not exists ( select 1 from emp where job = 'SALESMAN' and deptno <> 30 ) ) enable validate;

create assertion if not exists emp_br_salary_band_clerk check ( not exists ( select 1 from emp where job = 'CLERK' and sal is not null and (sal < 800 or sal > 1300) ) ) enable validate;

create assertion if not exists emp_br_salary_band_salesman check ( not exists ( select 1 from emp where job = 'SALESMAN' and sal is not null and (sal < 1250 or sal > 1600) ) ) enable validate;

create assertion if not exists emp_br_salary_band_analyst check ( not exists ( select 1 from emp where job = 'ANALYST' and sal is not null and sal <> 3000 ) ) enable validate;

create assertion if not exists emp_br_required_core_fields check ( not exists ( select 1 from emp where ename is null or job is null or hiredate is null or sal is null ) ) enable novalidate;

Some examples include:

• PRESIDENT must have no manager, no commission, and belong to department 10

• only SALESMAN can have commission

• SALESMAN must be in department 30

• salary bands by job (CLERK, SALESMAN, ANALYST)

All of these rules were not obvious to me, and I was doing literally nothing to enforce them otherwise. Thus, it was possible to have a SALESMAN in OPERATIONS, a PRESIDENT with a manager or an out-of-band salary.

Now, with these new assertions in place, I'm able to better enforce my business rules without having to make any changes to my applications - APEX or otherwise.

Even if you don't have Oracle 26ai or want to use SQL Assertions, it may be worth letting an LLM inspect your data and provide some insights as to which patterns exist. Then, you can pick and choose which ones can be converted to a business rule either the traditional way or via SQL Assertions.

Notice: I should mention that in order to generate these insights, I had to share my data with the LLM - specifically, GPT-5.3-Codex. While this approach can surface valuable and unexpected business rules, it’s important to recognize the potential risks involved. To achieve similar results, you’d need to follow the same process, meaning that your organization's data would also have to be shared with an LLM. Many organizations have strict policies that prohibit sharing sensitive or proprietary data with public LLMs, so always exercise caution and ensure compliance with your company’s data-sharing guidelines.

Title photo by Markus Spiske on Unsplash

Fast forward 20 years: starting today, I am happy to announce that I am returning to where it all started for me and re-joining the Oracle Database Tools team as an Architect.

This move is bittersweet. For the past five years, I’ve had the privilege of building and leading an incredible team in the GIUs, collaborating daily with people I deeply respect and admire. Walking away from that isn’t easy. But, just like 20 years ago, the opportunity in front of me was one I couldn’t pass up.

In this new role, I’ll be working with all of the Database Tools teams to help advance things like APEXLang as well as enabling Oracle Database developers to embrace AI for both themselves and their users. I also hope to make it out to a few more conferences and engage with the community on a more regular basis via social media and in person.

As I get settled in over the next few days, I’ll be blogging about what I’ve been up to. If there’s a topic that you’d like to hear more about or just want to re-connect, please don’t hesitate to reach out to me in the comments or on my socials: BlueSky, X & LinkedIn.

#LetsWreckThisTogether

Bonus points for anyone who can 1) identify the building in the heading and 2) identify its significance.

Assume that you’re developing an employee management application. At the core of this system is a table called EMP:

SQL> desc emp;

Name        Null?       Type             
___________ ___________ ________________ 
EMPNO       NOT NULL    NUMBER(4)        
ENAME                   VARCHAR2(10)     
JOB                     VARCHAR2(9)      
MGR                     NUMBER(4)        
HIREDATE                DATE             
SAL                     NUMBER(7,2)      
COMM                    NUMBER(7,2)      
DEPTNO                  NUMBER(2)

To deploy your application, you can create a script called emp.sql and simply run it in production. And that’s exactly what you do.

Before you know it, your table has a bunch of data about the employees of the organization and people love using it. The next week, you get an enhancement request to add a column to track employee’s email addresses. Sounds simple enough, right?

Just run the following script:

SQL> alter table emp add (email varchar2(100));

Simple, right?

What happens if you scale up your development? Now, instead of one table and one developer, you have hundreds of tables, packages and views and ten or more developers.

And what happens if you also add multiple target systems to the mix? Or want to ensure that changes are properly tested? Or want to incorporate a CI/CD pipeline for automation?

Things will get really complicated really quickly if you’re going to rely on manual processes. It’s a matter of time before the wrong script is run on the wrong environment.

The good news is that there are modern tools & methodologies available that were designed to help alleviate this complexity. This blog will dive into the details of one of them - SQLcl Projects & Liquibase.

About Liquibase

Before we dive into SQLcl Projects, let’s talk Liquibase for a minute. Liquibase is an open source utility that helps promote database schema-level changes. SQLcl ships with a fork of Liquibase embedded in it, so if you have SQLcl, you have Liquibase and there’s no need to download anything else.

At a high level, Liquibase creates a “ledger” of sorts to track all DDL called changelogs. These changelogs can be pointed at any schema and “replayed” to install a set of database objects. The changelogs also prevent Liquibase from running the same script twice, ensuring database object integrity.

Explain it Like I’m 5 Years Old

Sure! Let’s walk through a simple example and how Liquibase helps manage your development lifecycle.

Let’s stick with our simple example that contains a single table called EMP. You can easily script out the DDL for these tables and even the INSERT statements to populate them. Traditionally, when you’re ready to deploy, you would hand those scripts to a DBA who would then run them in the next tier - QA, TEST, PROD, etc.

With Liquibase, things are similar - but different. Think of Liquibase as a ledger. This ledger - or in Liquibase terms, changelog - will keep track of all scripts that are run for a specific target. This way, it will only ever execute each script once as well as keep an running audit of which was run.

In our example, our script to create the EMP table will be deployed by Liquibase to the target. Given that we have a brand new schema with nothing in it, Liquibase runs the script, creates the table and adds an entry to it’s changelog. So far, so good.

Let’s say that we need to add a new column to EMP. Clearly, we can’t re-create the entire table, as we would lose all of our data. Instead, we create and deploy a script that only adds the new column. Liquibase will then run the single script, which adds the column to the table and adds another entry to the changelog.

So far, this is not unlike how you would do things without Liquibase.

So, what’s the difference?

It’s easy to mentally manage two changes to a single system. It’s not as easy to manage hundreds of changes to many systems, especially across many developers and many target systems.

If you have multiple target databases or have the need to frequently generate test databases automatically to confirm your changes as you develop, you’ll wonder how you lived without Liquibase. Using Liquibase, each target gets its own changelog of which releases have been applied. Releases are also inclusive, meaning that you can start with any release you like and not have to manually apply previous ones.

Or, if you’re building a packaged solution that multiple users will download and use, Liquibase makes it easy for them to keep up with changes. They can choose how often to upgrade and be assured that with no additional effort, they will always be able to patch to the latest version.

Liquibase is also completely scriptable and can easily fit into any CI/CD process. This enables developers to automate the deployment of their code to any number of targets across development and deployment pipelines.

And finally - and perhaps most importantly - the Liquibase changelog serves as an audit table as to who made what change when. In many organizations, auditing these type of actions are not just important, it’s the law.

SQLcl Projects

Last year, SQLcl introduced a new feature called Projects. From the SQlcl Projects documentation:

The project command in Oracle SQLcl is a powerful tool designed to standardize database software versioning and create releasable artifacts, including APEX elements. This command supports a consistent model of development and operations, enabling repeatable builds that can be applied in a specific order.

While SQLcl has had Liquibase support for some time now - this new Projects feature makes using Liquibase even easier and more intuitive than before. Think of it as a set of commands that act as a wrapper to Liquibase that make managing development easier. SQLcl Projects syntax is simple and easy to learn, and the tool itself automates a number of the requirements found when working with Liquibase.

SQlcl Projects Workflow

SQLcl Projects has a prescribed workflow when it comes to building deployable releases:

Here’s a breakdown of each phase.

Build

Build is where you as a developer build your application. This involves creating database objects of all sorts, as well as APEX applications. In many cases, you will “over-create” and end up with some objects that just don’t need to get deployed.

Stage

As you complete your work, you “stage” it. Stage is where your release will be built from. SQLcl Projects can automatically generate and stage DDL scripts based on what you create in the database, or you can manually do this on your own. Thus, you can simply issue DDL commands from any tool and either stage the scripts or let SQLcl do it for you.

Release

Once you have staged all of your scripts, it’s time to cut a release. A release is a collection of your scripts blended in with the required files for SQLcl to be able to properly deploy it. Again, this process is as simple as issuing a command; SQLcl again does the heavy lifting or you.

Deploy

Once you have a release artifact, deploying it is also as simple as a single-line command. Release artifacts - which are really just ZIP files - can be deployed manually or as part of a CI/CD release process.

My First Project

Let’s get to the fun part and build our first SQLcl Project. To keep things simple, we’re going to stick with the use case I just described. We’ll build an “application” that consists of just EMP & DEPT and deploy it with SQLcl Projects.

Prerequisites

In order to follow along, you’ll need to have access to the following resources:

• SQLcl version 25.2+ installed on your machine

• VS Code

• SQL Developer for VS Code

• An instance of Git; github.com will work just fine and is used in this example

• Access to two Oracle database instances or two PDBs that are the same or at least similar versions

  • You will need to create a new schema called DEMO in each database, so DBA-level access is required

  • In reality, these should be the exact same version; for our use case, something close should be fine

Create & Seed the Repository

Let's start by creating a new repository and then using SQLcl Projects to seed it with your schema objects.

Create a Repository

First things first, create a new, clean repository. This can be anywhere; we'll use GitHub for this example.

1. Navigate to github.com and sign in.

2. Click New.

   

3. Choose an Owner and enter a Repository name. We’ll use sqlcl-projects-demo for this demonstration.

   

4. Click Create repository.

You now have a new, blank repository that we can use with SQLcl Projects.

Clone the Repository

Next, clone the repository to your local machine and change to the new directory. Be sure to update the username of the repo with yours!

git clone git@github.com:[your-github-user]/sqlcl-projects-demo.git
cd sqlcl-projects-demo

Create the main Branch

We'll need to create the main branch in the repository. These steps will create a basic "README" file and then commit and push it to a new branch called main.

echo "# sqlcl-projects-demo" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git push -u origin main

Create the Schema & Objects

Next, we need to create our development schema and seed it with a couple tables.

Create the DEMO Schema on the Source Database

For this example, we’ll create & deploy our objects from and to a schema called DEMO. Thus, we will need to create this schema on both databases that we’re going to use.

1. Connect to the source database as a DBA-level user, such as SYSTEM or ADMIN (ADB).

2. Run the following commands, ensuring to adjust the password and tablespace name, if needed.

create user demo identified by "StrongPassword1$";
alter user demo quota unlimited on users;
grant connect, resource, create view to demo;

3. Next, create a connection in SQL Developer for VS Code for this schema. Name that connection demo. If using ADB, please be sure to select the _LOW connection; using others can cause issues with Liquibase.

Connect as the DEMO Schema

Next, we’ll connect to the owner of the source code. We can re-used a SQL Developer for VS Code connection string here, making it a lot easier. In our case, we’ve pre-configured a connection called demo to point to the database schema where we have our source code and database objects.

Let’s connect to it with SQLcl:

sql -name demo

Create the EMP & DEPT Tables

For this example, let’s keep things simple and use the standard EMP & DEPT tables.

As the demo user, run the following:

create table dept(
  deptno number(2,0),
  dname  varchar2(14),
  loc    varchar2(13),
  constraint pk_dept primary key (deptno)
);

create table emp(
  empno    number(4,0),
  ename    varchar2(10),
  job      varchar2(9),
  mgr      number(4,0),
  hiredate date,
  sal      number(7,2),
  comm     number(7,2),
  deptno   number(2,0),
  constraint pk_emp primary key (empno),
  constraint fk_deptno foreign key (deptno) references demo.dept (deptno)
);

Populate the EMP & DEPT Tables

Now that we have a pair of tables, let’s throw some data in them.

begin
insert into demo.dept values(10, 'ACCOUNTING', 'NEW YORK');
insert into demo.dept values(20, 'RESEARCH', 'DALLAS');
insert into demo.dept values(30, 'SALES', 'CHICAGO');
insert into demo.dept values(40, 'OPERATIONS', 'BOSTON');
insert into demo.emp values(7839, 'KING', 'PRESIDENT', null, to_date('17-11-1981','dd-mm-yyyy'),5000, null, 10);
insert into demo.emp values(7698, 'BLAKE', 'MANAGER', 7839, to_date('1-5-1981','dd-mm-yyyy'),2850, null, 30);
insert into demo.emp values(7782, 'CLARK', 'MANAGER', 7839, to_date('9-6-1981','dd-mm-yyyy'),2450, null, 10);
insert into demo.emp values(7566, 'JONES', 'MANAGER', 7839, to_date('2-4-1981','dd-mm-yyyy'),2975, null, 20);
insert into demo.emp values(7788, 'SCOTT', 'ANALYST', 7566, to_date('13-JUL-87','dd-mm-rr') - 85,3000, null, 20);
insert into demo.emp values(7902, 'FORD', 'ANALYST', 7566, to_date('3-12-1981','dd-mm-yyyy'),3000, null, 20);
insert into demo.emp values(7369, 'SMITH', 'CLERK', 7902, to_date('17-12-1980','dd-mm-yyyy'),800, null, 20);
insert into demo.emp values(7499, 'ALLEN', 'SALESMAN', 7698, to_date('20-2-1981','dd-mm-yyyy'),1600, 300, 30);
insert into demo.emp values(7521, 'WARD', 'SALESMAN', 7698, to_date('22-2-1981','dd-mm-yyyy'),1250, 500, 30);
insert into demo.emp values(7654, 'MARTIN', 'SALESMAN', 7698, to_date('28-9-1981','dd-mm-yyyy'),1250, 1400, 30);
insert into demo.emp values(7844, 'TURNER', 'SALESMAN', 7698, to_date('8-9-1981','dd-mm-yyyy'),1500, 0, 30);
insert into demo.emp values(7876, 'ADAMS', 'CLERK', 7788, to_date('13-JUL-87', 'dd-mm-rr') - 51,1100, null, 20);
insert into demo.emp values(7900, 'JAMES', 'CLERK', 7698, to_date('3-12-1981','dd-mm-yyyy'),950, null, 30);
insert into demo.emp values(7934, 'MILLER', 'CLERK', 7782, to_date('23-1-1982','dd-mm-yyyy'),1300, null, 10);
commit;
end;
/

SQLcl Projects

Let’s turn our attention to configuring our first project with SQLcl. A project in SQLcl consists of a number of files:

• Liquibase changelogs

• Schema objects

• Deployment scripts

• Configuration files

These files act in concert to assist with the development and deployment of your code. Using SQLcl Project commands, developers can more easily manage their code without having to manually edit configuration files.

Initialize Project

While still logged into the DEMO schema, let’s create a new project called DEMO. Run the following command from SQLcl:

project init -name demo -schemas demo

You should see the following, or something similar:

—-------------------
PROJECT DETAILS
—-------------------
Project name: demo 
Schema(s): DEMO 
Directory: /Users/scspend/Github/demo 
Connection name: faegans_demo 
Project root: demo 
Your project has been successfully created

You should also see some files & folders appear in your local working copy directory:

Let’s take a second to run through the purpose of these files.

Create the Initial Release Branch

Next, we need to create our initial release, which we will call 1.0. This represents the initial set of objects that we will include in our application.

From the command line, run the following:

git checkout -b release-1.0

We can validate that we’ve successfully switched to that branch by running the following command:

git branch --show-current

You should see release-1.0 if successful.

Export, Commit & Stage Schema Objects

Next, we’ll use SQLcl Project’s export command to create scripts for our database objects.

Export Schema Objects

The export command is one of the coolest part of SQLcl Projects. With a single command, I can generate all of the scripts I need for my schema objects. I no longer need to maintain a separate of SQL scripts for my database objects, as I can simply generate them. I can also run export more discretely and export a single, specific object.

Of course, if you want to maintain scripts or already have them that’s also supported.

Let’s use the export command to generate ours from SQLcl:

project export

The results will look like this:

The current connection FAEGANS_TP DEMO will be used for all operations
*** TABLES ***
*** REF_CONSTRAINTS ***
-------------------------------
REF_CONSTRAINT                1
TABLE                         2
-------------------------------
Exported 3 objects
Elapsed 11 sec

Let’s take another look at the local working copy files now:

Notice that there’s three new files in src/database/demo. These are the three schema objects that were in our source schema. If we take a look at one - for instance, emp.sql - we see mostly what we’d expect to see:

create table demo.emp (
    empno    number(4, 0),
    ename    varchar2(10 byte),
    job      varchar2(9 byte),
    mgr      number(4, 0),
    hiredate date,
    sal      number(7, 2),
    comm     number(7, 2),
    deptno   number(2, 0)
);

alter table demo.emp
    add constraint pk_emp primary key ( empno )
        using index enable;


-- sqlcl_snapshot {"hash":"22c6c8ad205e23dd589af01b8cfdd5e06a2b6add","type":"TABLE","name":"EMP","schemaName":"DEMO","sxml":"\n  <TABLE xmlns=\"http://xmlns.oracle.com/ku\" version=\"1.0\">\n   <SCHEMA>DEMO</SCHEMA>\n   <NAME>EMP</NAME>\n   <RELATIONAL_TABLE>\n      <COL_LIST>\n         <COL_LIST_ITEM>\n            <NAME>EMPNO</NAME>\n            <DATATYPE>NUMBER</DATATYPE>\n            <PRECISION>4</PRECISION>\n            <SCALE>0</SCALE>\n            \n         </COL_LIST_ITEM>\n         <COL_LIST_ITEM>\n            <NAME>ENAME</NAME>\n            <DATATYPE>VARCHAR2</DATATYPE>\n            <LENGTH>10</LENGTH>\n            <COLLATE_NAME>USING_NLS_COMP</COLLATE_NAME>\n            \n         </COL_LIST_ITEM>\n         <COL_LIST_ITEM>\n            <NAME>JOB</NAME>\n            <DATATYPE>VARCHAR2</DATATYPE>\n            <LENGTH>9</LENGTH>\n            <COLLATE_NAME>USING_NLS_COMP</COLLATE_NAME>\n            \n         </COL_LIST_ITEM>\n         <COL_LIST_ITEM>\n            <NAME>MGR</NAME>\n            <DATATYPE>NUMBER</DATATYPE>\n            <PRECISION>4</PRECISION>\n            <SCALE>0</SCALE>\n            \n         </COL_LIST_ITEM>\n         <COL_LIST_ITEM>\n            <NAME>HIREDATE</NAME>\n            <DATATYPE>DATE</DATATYPE>\n            \n         </COL_LIST_ITEM>\n         <COL_LIST_ITEM>\n            <NAME>SAL</NAME>\n            <DATATYPE>NUMBER</DATATYPE>\n            <PRECISION>7</PRECISION>\n            <SCALE>2</SCALE>\n            \n         </COL_LIST_ITEM>\n         <COL_LIST_ITEM>\n            <NAME>COMM</NAME>\n            <DATATYPE>NUMBER</DATATYPE>\n            <PRECISION>7</PRECISION>\n            <SCALE>2</SCALE>\n            \n         </COL_LIST_ITEM>\n         <COL_LIST_ITEM>\n            <NAME>DEPTNO</NAME>\n            <DATATYPE>NUMBER</DATATYPE>\n            <PRECISION>2</PRECISION>\n            <SCALE>0</SCALE>\n            \n         </COL_LIST_ITEM>\n      </COL_LIST>\n      <PRIMARY_KEY_CONSTRAINT_LIST>\n         <PRIMARY_KEY_CONSTRAINT_LIST_ITEM>\n            <NAME>PK_EMP</NAME>\n            <COL_LIST>\n               <COL_LIST_ITEM>\n                  <NAME>EMPNO</NAME>\n               </COL_LIST_ITEM>\n            </COL_LIST>\n            <USING_INDEX></USING_INDEX>\n         </PRIMARY_KEY_CONSTRAINT_LIST_ITEM>\n      </PRIMARY_KEY_CONSTRAINT_LIST>\n      <DEFAULT_COLLATION>USING_NLS_COMP</DEFAULT_COLLATION>\n      <PHYSICAL_PROPERTIES>\n         <HEAP_TABLE></HEAP_TABLE>\n      </PHYSICAL_PROPERTIES>\n      \n   </RELATIONAL_TABLE>\n</TABLE>"}

There is one notable difference - the last line that is commented out. This line was automatically added by SQLcl when we ran the export command. Essentially, this is a JSON document that contains metadata about the SQL script. If we format the XML portion of the JSON document, we get a much clearer picture of what it is:

<TABLE xmlns="http://xmlns.oracle.com/ku" version="1.0">
   <SCHEMA>DEMO</SCHEMA>
   <NAME>EMP</NAME>
   <RELATIONAL_TABLE>
      <COL_LIST>
         <COL_LIST_ITEM>
            <NAME>EMPNO</NAME>
            <DATATYPE>NUMBER</DATATYPE>
            <PRECISION>4</PRECISION>
            <SCALE>0</SCALE>
         </COL_LIST_ITEM>
         <COL_LIST_ITEM>
            <NAME>ENAME</NAME>
            <DATATYPE>VARCHAR2</DATATYPE>
            <LENGTH>10</LENGTH>
            <COLLATE_NAME>USING_NLS_COMP</COLLATE_NAME>
         </COL_LIST_ITEM>
         <COL_LIST_ITEM>
            <NAME>JOB</NAME>
            <DATATYPE>VARCHAR2</DATATYPE>
            <LENGTH>9</LENGTH>
            <COLLATE_NAME>USING_NLS_COMP</COLLATE_NAME>
         </COL_LIST_ITEM>
         <COL_LIST_ITEM>
            <NAME>MGR</NAME>
            <DATATYPE>NUMBER</DATATYPE>
            <PRECISION>4</PRECISION>
            <SCALE>0</SCALE>
         </COL_LIST_ITEM>
         <COL_LIST_ITEM>
            <NAME>HIREDATE</NAME>
            <DATATYPE>DATE</DATATYPE>
         </COL_LIST_ITEM>
         <COL_LIST_ITEM>
            <NAME>SAL</NAME>
            <DATATYPE>NUMBER</DATATYPE>
            <PRECISION>7</PRECISION>
            <SCALE>2</SCALE>
         </COL_LIST_ITEM>
         <COL_LIST_ITEM>
            <NAME>COMM</NAME>
            <DATATYPE>NUMBER</DATATYPE>
            <PRECISION>7</PRECISION>
            <SCALE>2</SCALE>
         </COL_LIST_ITEM>
         <COL_LIST_ITEM>
            <NAME>DEPTNO</NAME>
            <DATATYPE>NUMBER</DATATYPE>
            <PRECISION>2</PRECISION>
            <SCALE>0</SCALE>
         </COL_LIST_ITEM>
      </COL_LIST>
      <PRIMARY_KEY_CONSTRAINT_LIST>
         <PRIMARY_KEY_CONSTRAINT_LIST_ITEM>
            <NAME>PK_EMP</NAME>
            <COL_LIST>
               <COL_LIST_ITEM>
                  <NAME>EMPNO</NAME>
               </COL_LIST_ITEM>
            </COL_LIST>
            <USING_INDEX></USING_INDEX>
         </PRIMARY_KEY_CONSTRAINT_LIST_ITEM>
      </PRIMARY_KEY_CONSTRAINT_LIST>
      <DEFAULT_COLLATION>USING_NLS_COMP</DEFAULT_COLLATION>
      <PHYSICAL_PROPERTIES>
         <HEAP_TABLE></HEAP_TABLE>
      </PHYSICAL_PROPERTIES>
   </RELATIONAL_TABLE>
</TABLE>

It’s a lot more obvious that the XML portion of this defines our table and associated constraint.

The point of this JSON document is a “snapshot” or sorts that SQLcl will use when managing changelogs. It’s best to leave it alone, as changing it can likely cause more harm than good.

Commit to Git

Now that we have our initial scripts, let’s commit those to Git. This is necessary because in the next step - staging - it will only stage files that are committed.

Let’s add and commit the new files that were created as part of the project creation and export. Run the following commands from the command line:

git add -A
git commit -m "Initial commit"

After the commit, you will see something similar to this:

[release-1.0 0005da5] Initial commit
 9 files changed, 254 insertions(+)
 create mode 100644 .dbtools/filters/project.filters
 create mode 100644 .dbtools/project.config.json
 create mode 100644 .dbtools/project.sqlformat.xml
 create mode 100644 .gitignore
 create mode 100644 dist/install.sql
 create mode 100644 src/database/demo/ref_constraints/fk_deptno.sql
 create mode 100644 src/database/demo/tables/dept.sql
 create mode 100644 src/database/demo/tables/emp.sql

Staging the Project

Now that we’ve committed our changes, we can stage the project. Staging is a process where SQLcl will create a set of files that will eventually become a release. Think of staged files as a temporary place that we can add and remove files from during our development process before we create a release. Files that are staged will eventually become released.

To stage your project, enter the following from SQLcl:

project stage

If we look at the local working copy now, notice that there’s a whole new set of files & folders, highlighted in green:

Everything under the dist/releases/next folder is the staging area. It’s extremely similar to the src/database/demo folder, as it’s literally a copy of those files with one notable difference. Here’s the emp.sql file under dist/releases/next/changes/release-1.0/demo/tables:

-- liquibase formatted sql
-- changeset DEMO:1756306177836 stripComments:false  logicalFilePath:release-1.0/demo/tables/emp.sql runAlways:false runOnChange:false replaceIfExists:true failOnError:true
-- sqlcl_snapshot src/database/demo/tables/emp.sql:null:3fb1c8da8567805e174f2feea15ffb986a37c120:create

create table demo.emp (
    empno    number(4, 0),
    ename    varchar2(10 byte),
    job      varchar2(9 byte),
    mgr      number(4, 0),
    hiredate date,
    sal      number(7, 2),
    comm     number(7, 2),
    deptno   number(2, 0)
);

alter table demo.emp
    add constraint pk_emp primary key ( empno )
        using index enable;

Notice that we now have Liquibase-related comments added to the top of the file and the SQLcl-generated JSON document at the bottoms of the file is gone. This is the standard way of marking up a file so that Liquibase can process it.

Changelogs

There’s now three “changelog” files that were added to the local working copy. Let’s dig into each one of them.

Utilities

There’s also a pair of files in the utilities - or utils - directory:

Add Custom Files

Before we can create our release, it would be nice to also automatically populate the EMP & DEPT tables with their respective datasets. SQLcl Projects allows us to also add custom files - those that are not automatically generated based on database objects to our project. Let’s do that.

In a SQLcl session, enter the following:

project stage add-custom -file-name seed.sql

Once this command is run, have a close look at your local working copy. A new file - seed.sql - has been added at releases/next/changes/release-1.0/_custom. If we take a look at that file, it’s blank aside from the three lines of Liquibase control information:

-- liquibase formatted sql
-- changeset  SqlCl:1756384780690 stripComments:false logicalFilePath:release-1.0/_custom/seed.sql
-- sqlcl_snapshot dist/releases/next/changes/release-1.0/_custom/seed.sql:null:null:custom

We will need to add our SQL script to this file, starting at line 4. The end result of seed.sql should look like this:

-- liquibase formatted sql
-- changeset  SqlCl:1756384780690 stripComments:false logicalFilePath:release-1.0/_custom/seed.sql
-- sqlcl_snapshot dist/releases/next/changes/release-1.0/_custom/seed.sql:null:null:custom
begin
insert into demo.dept values(10, 'ACCOUNTING', 'NEW YORK');
insert into demo.dept values(20, 'RESEARCH', 'DALLAS');
insert into demo.dept values(30, 'SALES', 'CHICAGO');
insert into demo.dept values(40, 'OPERATIONS', 'BOSTON');
insert into demo.emp values(7839, 'KING', 'PRESIDENT', null, to_date('17-11-1981','dd-mm-yyyy'),5000, null, 10);
insert into demo.emp values(7698, 'BLAKE', 'MANAGER', 7839, to_date('1-5-1981','dd-mm-yyyy'),2850, null, 30);
insert into demo.emp values(7782, 'CLARK', 'MANAGER', 7839, to_date('9-6-1981','dd-mm-yyyy'),2450, null, 10);
insert into demo.emp values(7566, 'JONES', 'MANAGER', 7839, to_date('2-4-1981','dd-mm-yyyy'),2975, null, 20);
insert into demo.emp values(7788, 'SCOTT', 'ANALYST', 7566, to_date('13-JUL-87','dd-mm-rr') - 85,3000, null, 20);
insert into demo.emp values(7902, 'FORD', 'ANALYST', 7566, to_date('3-12-1981','dd-mm-yyyy'),3000, null, 20);
insert into demo.emp values(7369, 'SMITH', 'CLERK', 7902, to_date('17-12-1980','dd-mm-yyyy'),800, null, 20);
insert into demo.emp values(7499, 'ALLEN', 'SALESMAN', 7698, to_date('20-2-1981','dd-mm-yyyy'),1600, 300, 30);
insert into demo.emp values(7521, 'WARD', 'SALESMAN', 7698, to_date('22-2-1981','dd-mm-yyyy'),1250, 500, 30);
insert into demo.emp values(7654, 'MARTIN', 'SALESMAN', 7698, to_date('28-9-1981','dd-mm-yyyy'),1250, 1400, 30);
insert into demo.emp values(7844, 'TURNER', 'SALESMAN', 7698, to_date('8-9-1981','dd-mm-yyyy'),1500, 0, 30);
insert into demo.emp values(7876, 'ADAMS', 'CLERK', 7788, to_date('13-JUL-87', 'dd-mm-rr') - 51,1100, null, 20);
insert into demo.emp values(7900, 'JAMES', 'CLERK', 7698, to_date('3-12-1981','dd-mm-yyyy'),950, null, 30);
insert into demo.emp values(7934, 'MILLER', 'CLERK', 7782, to_date('23-1-1982','dd-mm-yyyy'),1300, null, 10);
commit;
end;
/

Make sure that you save seed.sql before continuing.

Before we generate a release, have a look at the stage.changelog.xml file one more time:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.3.xsd">
<include file="demo/tables/dept.sql" relativeToChangelogFile="true"/>
<include file="demo/tables/emp.sql" relativeToChangelogFile="true"/>
<include file="demo/ref_constraints/fk_deptno.sql" relativeToChangelogFile="true"/>
<include file="_custom/seed.sql" relativeToChangelogFile="true"/>
</databaseChangeLog>

Notice that there is a new reference for our seed.sql file. This was automatically added when we staged the file a moment ago.

Creating & Deploying a Release

Once we have finished a phase of development and are ready to ship our code, we need to create a release and deploy it. SQLcl Projects makes this as easy as running a couple of commands. Let’s get started.

Commit

Before creating a release, we need to be sure that we commit our code into Git. SQLcl will ignore any code that is not committed when building releases, so while this step is small, it’s critical.

As we have done in the past, from a terminal session, issue the following two commands:

git add -A
git commit -m "Release 1.0"

You should see something similar to the following:

[release-1.0 a78c91c] Release 1.0
 9 files changed, 402 insertions(+)
 create mode 100644 dist/releases/main.changelog.xml
 create mode 100644 dist/releases/next/changes/release-1.0/_custom/seed.sql
 create mode 100644 dist/releases/next/changes/release-1.0/demo/ref_constraints/fk_deptno.sql
 create mode 100644 dist/releases/next/changes/release-1.0/demo/tables/dept.sql
 create mode 100644 dist/releases/next/changes/release-1.0/demo/tables/emp.sql
 create mode 100644 dist/releases/next/changes/release-1.0/stage.changelog.xml
 create mode 100644 dist/releases/next/release.changelog.xml
 create mode 100644 dist/utils/prechecks.sql
 create mode 100644 dist/utils/recompile.sql

Verify the Project

It’s a good idea to verify that your project is ready to be released. The verify step looks at your changelog files, as well as other Liquibase-specific configurations to ensure that it can build a functional release. Adding the -verbose tag is not necessary, but when used, will highlight the specifics of any error or warning.

project verify -verbose

You should see something similar:

-------- Results Summary ----------
Errors:     0
Warnings:   0
Info:       6
---------------------------------

Level     Group Name     Test Name                     Message
-----     ----------     -----------                   -------------------------
INFO      settings       verifynonpublicsettings       No unsupported internal settings found
INFO      init           verifyprojectname             The final project name will be "demo"
INFO      examples       exampletest                   a message
INFO      stage          stagechangelogcomplete        Stage Changelog validation found no issues.
INFO      project        sqlclversion                  SQLcl Version check passed
INFO      snapshot       verifysnapshot                Snapshot validation found no issues.

Create the Release

Now that we have exported our objects as scripts and added a custom one to populate them with data, staged our changes and verified that they will run, it’s time to create out first release.

project release -version 1.0 -verbose

Creating a release does a few of things to our files & folders:

• Moves the contents of the folder dist/releases/next to dist/releases/1.0

• Creates a fresh dist/releases/next directory ready for the next release

• Updates the main.changelog.xml file to include a reference to the new release

• Updates the project.config.json file with the latest release number

Generate the Artifact

While it’s possible to manually take the source and run it against our target environment, that’s not the best approach at all. SQLcl Projects can automatically generate an artifact that consists of all necessary files to deploy this release.

This artifact will be inclusive. In other words, if you have release 1.0 and the artifact contains release 1.1, running it will only apply changes in 1.1. With a clean installation, the artifact will install 1.0 as well as 1.1. We’ll demonstrate an “upgrade” flow next, but before we do that, let’s generate the artifact.

In a SQLcl session, run the following command:

project gen-artifact -version 1.0

This command will generate an artifact in the form of a ZIP file. There should also now be a new folder in your local directory called artifact. Inside that folder will be a file called demo-1.0.zip - a combination of the project name and release.

Feel free to unzip the file and explore the contents. It will be very similar to what the dist/releases/1.0 directory in the working copy looks like.

One important thing to note - any file in the artifact directory will NOT be checked into your repository. This is due to the fact that that in the .gitignore file, there is a line that tells Git to ignore the artifact directory altogether.

You will need to manually move these artifacts to the system where they will be deployed.

Deploying a Release

Now that we have an artifact, we’re ready to deploy. Before we do, let’s review how Liquibase deploys artifacts. When deployed, SQLcl Projects will issue a command to run the install.sql file that is found in the ZIP. The install.sql file will, in turn run the contents of the main.changelog.xml file. That file will, in turn, run release.changelog.xml. That file will, in turn, execute all of the discrete scripts to create table, constraints and populate the tables with data.

All of the discrete scripts that SQLcl Projects creates will refer to database objects in the schema.object format. Because of this, there’s two ways we can deploy our application:

• From the DEMO schema

• From a more privileged schema

Which one you use will depend on your needs. If all of your database objects will be in a single schema, and that schema has the required privileges to run the installation scripts, then you can connect directly to that schema and deploy. However, if your application is spread across multiple schemas, you may want to connect as a more privileged schema and deploy from there.

Keep in mind that when SQLcl Projects deploys an application, it will need to create a couple of tables to track which release is installed. If you change your mind, it gets tricky reconciling the data in these tables, so when in doubt, err on the side of the more privileged schema to give yourself room to grow.

To keep things simple, we will use the DEMO schema on the target database for our deployment.

Create a Privileged Installation User

Should you need to create a privileged user for installations, take a look at how we do this for APEX-SERT. We use a schema called ACDC to run all of our Liquibase deployments. This is a much safer way to do things vs. using something like SYSTEM or ADMIN (ADB), as we only grant the privileges needed to get the job done.

Details about how to create the ACDC schema can be found here - specifically in section 2.2.1.

Create the DEMO Schema on the Source Database

Since we’re going to deploy with the DEMO user, let’s create that on the target database.

1. Connect to the target database as a DBA-level user, such as SYSTEM or ADMIN (Autonomous).

2. Run the following commands, ensuring to adjust the password and tablespace name, if needed.

create user demo identified by "StrongPassword1$";
alter user demo quota unlimited on users;
grant connect, resource, create view to demo;

3. Next, create a connection in SQL Developer for VS Code for this schema. Name that connection demo_target. If using ADB, please be sure to select the _LOW connection; using others can cause issues with Liquibase.

Deploy the Artifact

Now that we have a new schema ready to go on the target database, let’s connect to it and kick off the deployment.

1. Quit SQLcl and then re-connect to the target database as the DEMO schema.

sql -name demo_target

You should now be connected to a fresh schema with no objects. Let’s deploy our schema.

2. Enter the following command:

project deploy -file artifact/demo-1.0.zip -verbose

3. After a few seconds, you will see something like the following:

Check database connection...
Extract the file name: demo-1.0
Artifact decompression in progress...
Artifact decompressed: /var/folders/0_/nwtj13qx4bv2gzs667vs3h3w0000gn/T/23c6cc92-35ce-4f9f-9e2e-0ffb00f6e2d712784159437265393156
Starting the migration...
Running Changeset: release-1.0/demo/tables/dept.sql::1756346516693::DEMO
Table DEMO.DEPT created.


Table DEMO.DEPT altered.
Running Changeset: release-1.0/demo/tables/emp.sql::1756346516709::DEMO
Table DEMO.EMP created.


Table DEMO.EMP altered.
Running Changeset: release-1.0/demo/ref_constraints/fk_deptno.sql::1756346516684::DEMO
Table DEMO.EMP altered.
Running Changeset: release-1.0/_custom/seed.sql::1756384780690::SqlCl

Liquibase: Update has been successful. Rows affected: 4
Installing/updating schemas
--Starting Liquibase at 2025-08-29T06:41:26.162524 using Java 21.0.8 (version 4.30.0 #0 built at 2025-04-01 10:24+0000)
Table DEMO.DEPT created.


Table DEMO.DEPT altered.
Table DEMO.EMP created.


Table DEMO.EMP altered.
Table DEMO.EMP altered.


UPDATE SUMMARY
Run:                          4
Previously run:               0
Filtered out:                 0
-------------------------------
Total change sets:            4


Produced logfile: sqlcl-lb-1756467685000.log

Operation completed successfully.
Migration has been completed
Removing the decompressed artifact: /var/folders/0_/nwtj13qx4bv2gzs667vs3h3w0000gn/T/23c6cc92-35ce-4f9f-9e2e-0ffb00f6e2d712784159437265393156...

We can easily verify that the release was deployed by querying the EMP table, like so:

SQL> select * from emp;

   EMPNO ENAME     JOB              MGR HIREDATE         SAL    COMM    DEPTNO 
________ _________ ____________ _______ ____________ _______ _______ _________ 
    7839 KING      PRESIDENT            17-NOV-81       5000                10 
    7698 BLAKE     MANAGER         7839 01-MAY-81       2850                30 
    7782 CLARK     MANAGER         7839 09-JUN-81       2450                10 
    7566 JONES     MANAGER         7839 02-APR-81       2975                20 
    7788 SCOTT     ANALYST         7566 19-APR-87       3000                20 
    7902 FORD      ANALYST         7566 03-DEC-81       3000                20 
    7369 SMITH     CLERK           7902 17-DEC-80        800                20 
    7499 ALLEN     SALESMAN        7698 20-FEB-81       1600     300        30 
    7521 WARD      SALESMAN        7698 22-FEB-81       1250     500        30 
    7654 MARTIN    SALESMAN        7698 28-SEP-81       1250    1400        30 
    7844 TURNER    SALESMAN        7698 08-SEP-81       1500       0        30 
    7876 ADAMS     CLERK           7788 23-MAY-87       1100                20 
    7900 JAMES     CLERK           7698 03-DEC-81        950                30 
    7934 MILLER    CLERK           7782 23-JAN-82       1300                10 

14 rows selected.

If you see 14 rows - congratulations - your release was successfully deployed!

Liquibase Tables

If you look closely at the DEMO schema, you will see an additional three tables were created. These are used by Liquibase to track deployments. Data in these tables should never be modified, as Liquibase will make changes as additional releases are deployed.

For the curious, here’s the names of them and their purpose:

I always feel a little uneasy mingling Liquibase tables with my application tables. Hence, I typically will opt to manage my deployments with a separate schema, as mentioned earlier.

Merge Your Changes

Now is a good time to merge your changes to the repository. This way, the next branch that we pull will have the most up-to-date code. Let’s run through the steps.

Another Commit

First, let’s add & commit all of the files as we’ve done before. From a terminal, run the following:

git add -A
git commit -m "Release 1.0"

Push to Github

Next, we need to push our committed changes back to the repository.

git push -u origin release-1.0

You should see something similar to this:

[release-1.0 d13db64] Release 1.0
 10 files changed, 35 insertions(+), 8 deletions(-)
 create mode 100644 dist/releases/1.0/changes/release-1.0/_custom/seed.sql
 rename dist/releases/{next => 1.0}/changes/release-1.0/demo/ref_constraints/fk_deptno.sql (100%)
 rename dist/releases/{next => 1.0}/changes/release-1.0/demo/tables/dept.sql (100%)
 rename dist/releases/{next => 1.0}/changes/release-1.0/demo/tables/emp.sql (100%)
 rename dist/releases/{next => 1.0}/changes/release-1.0/stage.changelog.xml (100%)
 create mode 100644 dist/releases/1.0/release.changelog.xml
 delete mode 100644 dist/releases/next/changes/release-1.0/_custom/seed.sql
sspendol@Scotts-MacBook-Air sqlcl-projects-demo % git push -u origin release-1.0
Enumerating objects: 56, done.
Counting objects: 100% (56/56), done.
Delta compression using up to 10 threads
Compressing objects: 100% (43/43), done.
Writing objects: 100% (54/54), 11.20 KiB | 3.73 MiB/s, done.
Total 54 (delta 10), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (10/10), done.
remote: 
remote: Create a pull request for 'release-1.0' on GitHub by visiting:
remote:      https://github.com/sspendol/sqlcl-projects-demo/pull/new/release-1.0
remote: 
To github.com:sspendol/sqlcl-projects-demo.git
 * [new branch]      release-1.0 -> release-1.0
branch 'release-1.0' set up to track 'origin/release-1.0'.

Confirm & Merge Pull Request

Pushing the changes will trigger a pull request on Github. If we switch back to our browser, we should see that pull request:

Go ahead and click the Compare & pull request button. Enter any comments that you’d like to track and click Create pull request.

Github will check to ensure that there are no conflicts with your pull request, and if so, allow you to merge it into the main branch. Click Merge pull request to do so.

One more step - enter a commit message, select a user and then click Confirm merge to complete the merge process.

Once your changes are merged, you can safely delete the release-1.0 branch if you want to.

If you click the Code tab, you should see your committed source code from the local working copy now in the main branch.

Keep in mind that a merge will usually trigger a code review process, and developers don’t usually approve their own merges.

Changing the Project

If you’ve been a developer for more than 15 minutes, you’re well aware of the fact that end users sometimes don’t know what they want. For example, with our simple EMP & DEPT tables, how would we add an additional column to EMP - say something like EMAIL - and deploy that change on top of release 1.0? This is where SQLcl Projects & Liquibase shine.

Modifying EMP

We clearly can’t recreate EMP from scratch, as there is data in there that we don’t want to use. Thus, we will need to issue an ALTER TABLE command as part of our next release so that the new column is added without interfering with the data. Or do we…

Create a New Branch

Let’s start out by creating a new branch in our repository:

git checkout -b release-1.1

Alter the Table

One of the benefits of SQLcl Projects is that it doesn’t care how the DDL changes are made. While we could create a file that contains the ALTER TABLE statement, we can also just run the ALTER TABLE and let SQLcl Projects do all the work. Let’s opt for that route.

Connect to your source database as the DEMO user.

sql -name demo

Issue the ALTER TABLE command to add the email column. Don’t worry about saving this script anywhere, as Liquibase will automatically generate it later.

alter table emp add (email varchar2(100));

Export the Project

Next, we need to export the project again. Again, you can do this discretely for a single database object, or just run the command naked to get any objects that have changed.

project export

Once you’ve exported the project, notice that the file src/database/demo/tables/emp.sql has changed. It now includes our new EMAIL column.

“We can’t run this script!” you might be thinking. And you’re right and wrong at the same time.

You’re right in that we can’t run this script, as it would fail. But this is not the script we’re going to run. SQLcl Projects will take care of that when we stage our changes.

Add a Custom File

Let’s add a custom file that when run, will populate the new EMAIL column.

project stage add-custom -file-name seed_email.sql

Notice that the new file should be visible in the dist/releases/next/changes/release-1.1/_custom directory of our local working copy:

This concept of “next” release is important. As you start to stage files, they will be placed under the releases/next directory. They will remain here until a new release is created. At that point, they will be moved to a folder named after the release version, and a new releases/next directory will be created.

Edit the seed_email.sql file and add the following after the comments:

-- liquibase formatted sql
-- changeset  SqlCl:1756471732399 stripComments:false logicalFilePath:version-1.1/_custom/seed_email.sql
-- sqlcl_snapshot dist/releases/next/changes/version-1.1/_custom/seed_email.sql:null:null:custom
begin
update demo.emp set email = lower(ename) || '@example.com';
commit;
end;
/

Don’t forget to save your changes.

Add & Commit Your Files

Remember - before we can stage the project, we will need to add & commit our changes.

From a terminal, enter the following commands:

git add -A
git commit -m "Release 1.1"

Stage the Project

Now, from SQLcl, stage the project with the following command:

project stage

You should now see a new version of emp.sql file in your local working copy under dist/releases/next/changes/release-1.1:

Inspecting this file will reveal that SQLcl Projects was able to compare the baseline version of EMP with the current version of EMP and generate the following DDL to synchronize them:

-- liquibase formatted sql
-- changeset DEMO:1756472006274 stripComments:false  logicalFilePath:version-1.1/demo/tables/emp.sql runAlways:false runOnChange:false replaceIfExists:true failOnError:true
-- sqlcl_snapshot src/database/demo/tables/emp.sql:22c6c8ad205e23dd589af01b8cfdd5e06a2b6add:594f20e09b4dafdc75d54f0f6a617fda9fba7bdd:alter

alter table demo.emp add (
    email varchar2(100)
)
/

Here’s a curveball.

Have a look at the stage.changelog.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.3.xsd">
<include file="_custom/seed_email.sql" relativeToChangelogFile="true"/>
<include file="demo/tables/emp.sql" relativeToChangelogFile="true"/>
</databaseChangeLog>

See it? Our seed_email.sql script will run BEFORE the new EMAIL column is added to EMP. That’s because we staged the custom file before we staged the changes to EMP. Sometimes this happens with Liquibase, and we need to modify the order of the files in the changelog.

Fortunately, there’s a quick fix - just change the order of when the scripts are called:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.3.xsd">
<include file="demo/tables/emp.sql" relativeToChangelogFile="true"/>
<include file="_custom/seed_email.sql" relativeToChangelogFile="true"/>
</databaseChangeLog>

One thing that you’ll learn to appreciate when working with Liquibase is that order really matters, and it doesn’t always get it right. In this case, we had to swap two files. You will likely run into similar matters with your own projects.

Create a Release

Now that we have that sorted, let’s create and deploy the release. From SQLcl, run the following:

project release -version 1.1 -verbose

After running this command, have a look at your local working copy. You should see an additional folder called 1.1 under the dist/releases folder. If you expand change/version-1.1/demo/tables and inspect emp.sql, it should only contain the ALTER statement; not the full CREATE TABLE one.

This is the magic of Liquibase: if a user was applying 1.1 on top of 1.0, only the ALTER statement will be run. If a user was doing a clean installation of 1.1, it would run both the CREATE TABLE and ALTER TABLE statements sequentially.

Generate the Artifact

As we did before, let’s create a new artifact based on the new release we just created.

project gen-artifact -version 1.1

Deploy the Release

Let’s switch to our target database and deploy the release. Connect to SQLcl as the DEMO user on the target database:

sql -name demo_target

Once connected, all that’s left is to run the deployment.

project deploy -file artifact/demo-1.1.zip -verbose

When complete, we should see something like this:

Check database connection...
Extract the file name: demo-1.1
Artifact decompression in progress...
Artifact decompressed: /var/folders/0_/nwtj13qx4bv2gzs667vs3h3w0000gn/T/39ec72ef-8073-4483-81c4-1fbd34e9a10315832945422908414459
Starting the migration...
Running Changeset: version-1.1/demo/tables/emp.sql::1756472006274::DEMO
Table DEMO.EMP altered.
Running Changeset: version-1.1/_custom/seed_email.sql::1756471732399::SqlCl
PL/SQL procedure successfully completed.
Liquibase: Update has been successful. Rows affected: 2
Installing/updating schemas
--Starting Liquibase at 2025-08-29T08:31:46.608397 using Java 21.0.8 (version 4.30.0 #0 built at 2025-04-01 10:24+0000)
Table DEMO.EMP altered.
PL/SQL procedure successfully completed.

UPDATE SUMMARY
Run:                          2
Previously run:               4
Filtered out:                 0
-------------------------------
Total change sets:            6


Produced logfile: sqlcl-lb-1756474305795.log

Operation completed successfully.
Migration has been completed
Removing the decompressed artifact: /var/folders/0_/nwtj13qx4bv2gzs667vs3h3w0000gn/T/39ec72ef-8073-4483-81c4-1fbd34e9a10315832945422908414459...

To prove that it did, in fact, work, run this SQL:

select * from emp;

   EMPNO ENAME     JOB              MGR HIREDATE         SAL    COMM    DEPTNO EMAIL                 
________ _________ ____________ _______ ____________ _______ _______ _________ _____________________ 
    7839 KING      PRESIDENT            17-NOV-81       5000                10 king@example.com      
    7698 BLAKE     MANAGER         7839 01-MAY-81       2850                30 blake@example.com     
    7782 CLARK     MANAGER         7839 09-JUN-81       2450                10 clark@example.com     
    7566 JONES     MANAGER         7839 02-APR-81       2975                20 jones@example.com     
    7788 SCOTT     ANALYST         7566 19-APR-87       3000                20 scott@example.com     
    7902 FORD      ANALYST         7566 03-DEC-81       3000                20 ford@example.com      
    7369 SMITH     CLERK           7902 17-DEC-80        800                20 smith@example.com     
    7499 ALLEN     SALESMAN        7698 20-FEB-81       1600     300        30 allen@example.com     
    7521 WARD      SALESMAN        7698 22-FEB-81       1250     500        30 ward@example.com      
    7654 MARTIN    SALESMAN        7698 28-SEP-81       1250    1400        30 martin@example.com    
    7844 TURNER    SALESMAN        7698 08-SEP-81       1500       0        30 turner@example.com    
    7876 ADAMS     CLERK           7788 23-MAY-87       1100                20 adams@example.com     
    7900 JAMES     CLERK           7698 03-DEC-81        950                30 james@example.com     
    7934 MILLER    CLERK           7782 23-JAN-82       1300                10 miller@example.com    

14 rows selected.

There’s our 14 rows, complete with a new, populated column for email address.

Add, Commit & Push to Github

As we did with the initial release, we want to be sure to push our changes back to Github and merge them into the main branch.

git add -A
git commit -m "Release 1.1"
git push -u origin release-1.1

Flip back over to your browser and complete the merge. Use the same sequence as you did to merge the release-1.0 in the previous section. Here’s the high-level steps:

• Click the Compare & pull request button

• Enter any comments that you’d like to track and click Create pull request

• Click Merge pull request

• Enter a commit message, select a user and then click Confirm merge

• Delete the version-1.1 branch

• Click the Code tab to confirm your changes were merged

Don’t forget to remove your working copy and/or switch back to the main branch, as the release-1.1 branch was deleted from the repository.

Conclusion

Managing database changes might seem straightforward when you’re working alone on a single table, but as soon as your application and team grow, the cracks start to show. Ad-hoc scripts quickly become messy, inconsistent, and risky to deploy. That’s where structured approaches like SQLcl Projects and Liquibase come in. They provide a repeatable, controlled way to evolve your schema with confidence, while still keeping the flexibility developers need.

By treating database changes like source code, you not only reduce errors but also improve collaboration, traceability, and long-term maintainability. SQLcl Projects helps developers of all experience levels easily adapt into the world of automated deployments. It’s a great first step to get into the world of CI/CD pipelines, as the barrier to entry is low and benefit is high.

And yes, APEX is supported with SQLcl Projects. Look for another blog about how to do that in the coming days.

Additional Reading

Still want to learn more about SQLcl Projects or want to hear about how others use it? Look no further than these articles - some of which I referred to while writing this post:

• https://pretius.com/blog/sqlcl-project-reference

• https://rafal.hashnode.dev/part5-sqlcl-project-it-will-forever-change-your-database-apex-deployments

• https://rafal.hashnode.dev/part-51-oracle-sqlcl-project-the-only-cicd-tool-for-apex-you-will-ever-need

Title photo by Chris Ried on Unsplash

Claude Desktop is a self-contained, simple interface. You interact with it outside of the scope of your IDE and code in a more general manner. While it can still generate some powerful solutions, Claude Desktop seems to be closer to an alternative to ChatGPT vs. a true AI coding assistant.

Cline is the better choice if you’re looking for an AI assistant that lives in your IDE. It’s there to help you write, review, and comment on code. It was designed for that single purpose from the ground up.

Another difference between Cline and Claude Desktop is how LLMs are integrated. Cline allows you to pick almost any LLM and use that. Thus, as Oracle, we have access to a handful, and can use any of them with Cline at no additional cost. Claude Desktop takes a different approach. You can use it for free for a limited number of questions per day, or you can sign up for one of the paid tiers.

Put another way - If I wanted to give an AI tool to my non-technical staff so that they could query an Oracle Database via MCP Server, it would be Claude Desktop without hesitation. Its simple, easy to understand interface and robust rendering capabilities make it an easy choice for the non-technical crowd.

Getting Started

Before we can use Claude Desktop, we need to configure it with the MCP Server and then connect to it. These steps take just minutes each.

Configuring Claude Desktop

Configuring Claude Desktop is as simple as configuring Cline. Simply follow the instructions in the SQLcl MCP Server documentation.

Once configured, you can validate that the MCP Server is running by navigating to Settings > Developer. You should see something like this:

Connecting to the MCP Server

Once configured, connecting to Oracle is done the same way that connecting to Cline is: just ask.

The SQL Developer connection apex_admin_user was created as a part of my last blog entry. Please have a look there if you missed it.

Creating Dashboards

Now that we’re connected, let’s skip the easy stuff and jump right into asking Claude to build us some dashboards.

Page Views

For our first dashboard, let’s use the data found in APEX_WORKSPACE_ACTIVITY_LOG - or page views. APEX will automatically track all page views - full and partial - in this view. Since our user has the APEX_ADMINISTRATOR_ROLE role, it will be able to see data across all of the workspaces. Keep in mind APEX will automatically purge data from the underlying table, so at best, you’ll have roughly two weeks of data.

Let’s start with the following prompt:

please create an analytics dashboard that summarizes page views for application 10000. include things like most popular page, avg render time, etc. make it look very slick and allow me to drill into details from the charts.

Like Cline, it required some back-and-forth to find the right view. Once it found it, it ran four queries to compute the data points that would ultimately end up in the dashboard. Remember - this dashboard is nothing more than static HTML with some Javascript.

Speaking of the dashboard it created, let’s have a look at it:

It’s pretty amazing that with just a couple of sentences, Claude was able to generate a professional looking dashboard that contains a variety of insights as to the page view data, including a combination of metrics, charts and a searchable report.

You can also drill into most of the data points. Since that’s harder to illustrate, feel free to try the dashboard for yourself here: https://claude.ai/public/artifacts/c022f815-7e81-4a16-b6f3-3cae15e82fd2

User Behaviors

Next, let’s create a dashboard that reports on data that APEX doesn’t: user behavior. It would be interesting to analyze the same data set to see how users actually use the applications - specifically, which page flows are the most popular, which pages get used the most, etc.

Thus, let’s use this prompt to create it:

using the same page view data, come up with an assessment of common usage patterns based on session id. provide this data in a dashboard that provides insights as to what users do and what could be done to make the application better

This time, Claude didn’t need to think as much, as the source of the data was still in context from the previous dashboard. It got right to work and instantly created another dashboard that looks like this:

Wow! This one really impressed me, as not only did it provide a comprehensive dashboard with actionable data, but it also picked out some of the common user flows and trends in my applications and identified them.

Keep in mind that the dataset here is from an instance of APEX that I build and test things on. Thus, the usage patterns are more indicative of that versus actual usage across many users. Some of the recommendations reflect this.

Have a look at this one in action here: https://claude.ai/public/artifacts/5baab2fb-f0fe-4065-85d9-0d3844bae3bc

Where does APEX fit in?

You may be thinking, “I thought this was an APEX blog, why are we creating Javascript applications all of a sudden?

Short answer - we can’t yet have AI generate APEX applications since there is not a published API to do so. Yet.

APEX Lang - not the existing APEX_LANG API, but the upcoming domain specific language with a similar name - will change that once it’s released. APEX Lang exposes all facets of an APEX application via APIs, allowing either users or AIs to call APIs to build and modify applications. Once it’s released, it will fundamentally change how we build and maintain APEX applications.

Summary

Claude Desktop enables anyone to generate content-rich, interactive dashboards without writing a single line of code. With minimal guidance, it even added insights and metrics to the dashboards, making them more than a bunch of reports & charts. Even if I simply harvested the SQL that Claude generated and used that in an APEX application, that’s a win.

I’m going to keep playing around with Claude Desktop and see what else I can come up with. Next, I’m going to dive into hooking up these dashboards to a RESTful endpoint hosted by ORDS so that they will always be accurate. Then I’ll look at how to secure the endpoint and perhaps allow for some updates to RESTful APIs.

Title photo by Mykhailo Amirdzhanian on Unsplash.

Fast-forward a bunch of years, and that three-letter acronym - MCP - is making its way around the AI crowd again. But this time, it stands for Model Context Protocol. This modern version of MCP is not trying to kill you as much as it provides a critical link between your private data and any LLM. The MCP protocol was designed by Anthropic in November 2024 and was quickly adopted as an open source standard by all of the major players in AI shortly thereafter, making it one of the fastest growing areas of AI. It’s often compared to a USB hub, as it connects one type of service (AI) with another (data).

Why All the Hype?

MCP servers are getting a lot of hype these days, and rightly so. To understand why, let’s take a step back and think about how we interact with LLMs today. The LLMs that we use today - ChatGPT, Grok, Anthropic, etc. - are all hosted on the public internet. Anything we send to them is received, stored and processed on their hardware.

LLMs are great at answering questions based on the data that they were trained on. This includes almost all facets of programming in almost any modern language. Need a regular expression written? LLM’s got you. Want to validate a JSON document? Just throw it at ChatGPT. How about a quick check of my code for security issues? Done and done.

Where LLMs quickly fall apart is when you need to know about YOUR data. Since your data - or your organization’s data - is private, LLMs were never trained on it and don’t know anything about it. Sure, you can use things like RAG to give LLMs a small sample of your data, but in many cases, that’s just no where near enough.

Before MCP, you really only had a single choice if you wanted to use your data with an LLM: train it. Training an LLM is a significant investment, as it means that you’ll have to procure the processors, servers and disk to load all of your data onto and let the LLM go to town learning about it. Even training small datasets can easily rack up bills in the 6 or 7 digit range.

This is where MCP changes the game.

MCP Server for Oracle Database

Oracle’s new MCP Server for the Oracle Database is an MCP server that serves a specific purpose - act as a broker between an LLM and your data in an Oracle Database. One “end” of the MCP server connects to your database while the other “end” plugs into the LLM of your choice.

The MCP server acts as an intermediary of sorts. In the case of MCP for Oracle Database, the MCP server has specific set of tasks that it can be asked to perform. From the Oracle SQLcl Documentation:

• list-connections: Discovers and lists all saved Oracle Database connections on your machine.

• connect: Establishes a connection to one of your specified named connections.

• disconnect: Terminates the current, active Oracle Database connection.

• run-sql: Executes standard SQL queries and PL/SQL code blocks against the connected database.

• run-sqlcl: Executes SQLcl-specific commands and extensions.

The key task here is run-sql. This allows the MCP to interact with the LLM and then run the SQL that the LLM requests. Again, the LLM never has direct access to the database - it can only talk to and receive input from the MCP server directly. In many cases, the LLM will want to run SQL to get bits of data so that it can complete the task it was asked. An example of this is it may need to know which columns are in the EMP table so that it can write a query. Or, if you asked something like “provide a summary of all orders for product A”, the LLM will need to see your data in order to provide the summary. Tools like Cline will allow the end user to see what is about to be sent to the LLM and either approve or reject it.

Get More Information on MCP Server for Oracle Database

Before diving into the rest of this article, it may be helpful to take a look at some other content about the MCP Server for Oracle Database. These are some great places to start:

• Introducing MCP Server for Oracle Database by Jeff Smith & Kris Rice

• Getting Started with our MCP Server for Oracle Database by Jeff Smith

• Using the Oracle MCP Server - Oracle SQLcl Documentation

Install & Configure MCP for Oracle Database

OK, enough background. Let’s get MCP Server for Oracle Database installed & configured so that we can play with it!

Before we go much further, I have to issue the following security warning:

Create the Database User

The MCP server will be able to do anything that the schema which it connects can. Thus, one way to limit the blast area is to create a limited privilege schema and connect through that. That schema can be set to only see a limited set of views & APIs, for example. If MCP tried to access another schema object, it will be blocked by the database security. This same principle can be applied to the parse-as schema in an APEX application; see Chapter 13 in a book I wrote many years ago for more details…

In order to both read APEX metadata and call APEX APIs, we’ll want to create a new schema and associate a role to it. It’s much safer this way vs. letting MCP connect to something like SYS, SYSTEM or ADMIN.

This new schema - called APEX_ADMIN_USER - will be granted the APEX_ADMINISTRATOR_ROLE role so that it can see any application in any workspace as well as call APEX administration APIs.

To create the APEX_ADMIN_USER schema:

1. Connect to your database as SYS, SYSTEM or ADMIN - essentially a user that has DBA privileges.

2. Run the following commands to create the APEX_ADMIN_USER:

-- create the new user
create user apex_admin_user identified by oracle;

-- add quota to the new users tablespace
alter user apex_admin_user quota unlimited on users;

-- grant connect to the new user
grant connect to apex_admin_user;

-- grant the apex_administrator_read_role to the user
grant APEX_ADMINISTRATOR_ROLE to apex_admin_user;

-- allow the user to create a table & sequence
grant create table, create sequence to apex_admin_user;

Create the Database Connection

Next, we need to create a database connection for our new user in SQL Developer. There’s nothing special about this step at all; you just need to create a uniquely named connection so that the MCP server can use it to connect to the database. I’ve found that it’s easier to use simple words to name the connection - something like apex_admin_user works great.

1. In SQL Developer for VS Code, click on the “+” in the Connections panel.

2. Complete the connection details with your specifics. For my example, here’s what I used:

   

3. Optionally, click Test to be sure that the connection is valid.

4. Click Save to save the connection.

Installing and Configuring Cline

Cline is “an AI development assistant which integrates with Microsoft Visual Studio Code. It provides an interface between your IDE and LLMs facilitating code development, increasing productivity and lowering the barrier to entry for new coders…”

In other words, Cline can help analyze and generate code via VS Code. It integrates with practically any LLM and provides a chat-like interface accessible from VS Code.

The documentation for SQLcl MCP Server is quite good, and the steps to install & configure Cline are quick & easy.

1. Navigate to the Oracle MCP Server Documentation.

2. Follow the section labeled 3.5.2 Configuring Cline in VS Code.

Connecting with Cline

Now that Cline is installed and configured with an LLM, all we need to do is connect to our new schema.

To do this:

1. Select Cline in the sidebar.

2. You should see a screen that looks like this:

   

3. Enter the following into the prompt and hit enter: connect to apex_admin_user

Cline will then attempt to connect to the database using the connection properties defined in apex_admin_user. As it attempts to connect, it may ask you for permission to execute certain commands. You can approve this each time, or set auto-approve to automatically approve any request to run the same portion of the MCP server - in this case, connect.

Here’s the output from my session - yours may vary depending on the LLM model you’re using as well as how many times you’ve connected in the past.

At this point, we’re ready to roll.

Optional Cleanup

Before we start, there’s an optional step that you may want to perform. The first time Cline connects, the MCP server will create a table called DBTOOLS$MCP_LOG in your schema. This table will be used to log all of the actions that MCP performs. MCP will also add comments to other common log & trace tables such as v$sql, v$session, ASH, AWR, etc. This makes it crystal clear which transactions were performed by the MCP server.

When we created the APEX_ADMIN_USER schema, we granted create table and create sequence so that MCP could create the table and corresponding sequence. If you want to revoke this pair of privileges, you can do so by running the following command:

-- once we have connected via Cline, optionally revoke create table & sequence
revoke create table, create sequence from apex_admin_user;

Using MCP with APEX

Now that we’re connected, we can literally use plain English to query the database about our APEX environment. For this section, I am using my Free Tier Cloud database, which has a decent amount of workspaces & applications. Your results will vary.

Number of Workspaces

Let’s start off simple. Enter the following into the prompt and press enter: how many workspaces are there?

What Just Happened?

Once we connected to the database, we asked Cline a simple question: how many workspaces are there? Workspaces are used in several software applications, so how did it know that I meant APEX workspaces?

That’s because my request was sent to the LLM with a prompt. That prompt provided additional context to the LLM so that it could choose the correct definition of workspace. Since the prompt likely stated that we’re connected to an Oracle Database, the LLM was able to return the correct SQL to run to answer the question.

It’s no different than if I were to open up a new ChatGPT window and ask the same question with a similar prompt:

Keep in mind that at no time at all does the LLM connect to the database or see any of the data. It’s simply taking the question that I sent as well as the prompt that’s embedded into the MCP Server and querying the LLM with that. The results are then returned to the MCP server, where it then turns around and runs them in the database connection that we established.

Mechanics

The LLM actually wraps the results in JSON and returns them to the MCP Server. If we take a look at the JSON, it’s pretty basic and very obvious which SQL is about to be run:

{
  "sql": "SELECT /* LLM in use is claude-sonnet-4 */ COUNT(*) AS workspace_count FROM apex_workspaces;",
  "mcp_client": "cline",
  "model": "claude-sonnet-4"
}

Notice the snippet /* LLM in use is claude-sonnet-4 */ embedded in the SQL. This is how the MCP Server ensures that SQL in log tables are properly instrumented as having been run by an LLM.

Omitting that snippet, we’re left with a fairly simple SQL statement: SELECT COUNT(*) AS workspace_count FROM apex_workspaces

The MCP server will then run that query and return the results, which in my case is 15. Running the same SQL via SQLcl confirms that the answer is correct.

Number of Applications

Sticking with simple, let’s ask this question: how many applications are there?

In this example, it functioned exactly as the last one, with the only difference being the specifics of the question.

Applications per Workspace

So far, while this is cool, the complexity of the SQL and maybe even level of effort required is somewhat negligible. I could probably type the SQL in the same time it takes for me to type the question. Let’s take it up a notch.

This time, we’ll ask the following question: list all applications by workspace; sort workspaces alphabetically and applications by the number of pages from most to least

This is where things get wild and the power of the MCP approach start to become clear. It’s clear that the results are correct; we have a dataset with all applications sorted by workspace name and then by page count high to low.

If we look at the full log, it looks like it stumbled a little bit. When it tried to run the following SQL:

SELECT 
  a.workspace,
  a.application_id,
  a.application_name,
  COUNT(p.page_id) AS page_count
FROM 
  apex_applications a
  LEFT JOIN apex_application_pages p
    ON a.application_id = p.application_id 
    AND a.workspace_id = p.workspace_id
  GROUP BY 
    a.workspace, 
    a.application_id, 
    a.application_name
  ORDER BY 
    a.workspace ASC, 
    page_count DESC

It failed, as the column WORKSPACE_ID does not exist in the table APEX_APPLICATION_PAGES. Since Oracle returned an error code to the MCP Server, it took the entire error stack and sent that to the LLM and likely prompted that with something like “Help me fix this error”. The LLM was then able to realize that column did not exist - nor was it necessary - so it removed it from the join statement and sent another JSON document with the updated SQL statement.

Neat.

Create a Workspace

Querying the APEX views is not the only thing we can do. Since we have the APEX_ADMINISTRATOR_ROLE, we can call any of the APEX APIs to do things like create and delete workspaces, users and alter instance settings.

Let’s try this: create a new workspace called blog. that workspace should parse as a new schema called blog. the blog schema should have a strong password.

This time, Cline performed two, distinct actions:

• created the Database Schema BLOG

• created the APEX Workspace BLOG and associated the BLOG schema with it

We can confirm the schema and workspace creation by logging into the APEX Instance Administration console:

Create an APEX User

Lastly, we’ll need a user created in that workspace so that we can login. Let’s create one now: create a user in the blog workspace called admin. use a strong password and set the email address to noreply@oracle.com.

The first thing it did was try to call APEX_UTIL.CREATE_USER, but it used the wrong parameters. Here’s what it tried to call:

begin
  apex_util.create_user
    (
    p_user_name     => 'admin',    
    p_web_password  => 'Cg6^zpP4nWq2Xt#5',    
    p_email_address => 'noreply@oracle.com',
    p_workspace     => 'blog'  
    );
end;
/

Unfortunately, there is no p_workspace parameter in APEX_UTIL.CREATE_USER. Thus, it failed and sent the error stack back to the MCP Server.

begin
  apex_util.set_workspace(p_workspace => 'BLOG');
  apex_util.create_user
   (
    p_user_name     => 'admin',    
    p_web_password  => 'Cg6^zpP4nWq2Xt#5',    
    p_email_address => 'noreply@oracle.com'
    );
  commit;
end;
/

Here’s where things went wrong.

When it sent the error stack back to the LLM, the LLM replied with the following:

The call to APEX_UTIL.CREATE_USER failed due to a wrong number or types of arguments. This strongly suggests either the API signature has changed or the arguments are not correct for the current APEX version.

In modern APEX (20.x+), workspace user creation is best performed via APEX_UTIL.CREATE_WORKSPACE_USER, which requires these parameters (with many as optional)…

This is simply not true. There is no such API as APEX_UTIL.CREATE_WORKSPACE_USER whatsoever, as confirmed by this search in the APEX API Documentation:

This is the infamous AI hallucination that you’ve heard about. The fact remains that sometimes, the AI just makes stuff up, and this is one of those times.

My experience is that AI for APEX administrative tasks works better with Lllama 4 or Grok 4 vs. GPT 4.1. Your results may vary, but if and when you hit one of these hallucinations, swapping out a different model - or even re-phrasing the question with more context - is all you need to do. It’s not a reason to give up on MCPs all together, as the quality of the LLMs gets better and better with each iteration.

Create an APEX User: Take Two

Lets switch models to Grok 4 and see if we can get it to work with the exact same prompt.

This time, the LLM was aware that either the workspace or security group ID had to be set before creating a new APEX user. The SQL that it ran was this:

  BEGIN
    APEX_UTIL.SET_SECURITY_GROUP_ID(48876018747798056); 
    APEX_UTIL.CREATE_USER
      ( 
      p_user_name => 'ADMIN', 
      p_email_address => 'noreply@oracle.com', 
      p_web_password => 'Adm1n$ecure2025!', 
      p_developer_privs => 'ADMIN' 
      ); 
    COMMIT;
  END;

It even added a COMMIT - something that is also needed to complete any transaction.

Models matter. They are all trained on different data sets, and one may be missing critical details that cause it to send back false information, while another is perfectly aware on how to perform a task.

It would be interesting to have a “bake off” of sorts across the popular LLMs to see which performed the best in the context of MCP Server & APEX…

Analyze PL/SQL Processes

Let’s kick things up a notch to demonstrate just how powerful the MCP Server really is.

This time, we’re going to ask the MCP to do a number of things at once:

• Search all applications for processes of type PL/SQL

• Return all of the corresponding PL/SQL code

• Provide an analysis of that code with advice as to how to optimize it

To make things even more fun, let’s just post this list as a single, condensed prompt. Something like this: show me any page process that uses plsql and provide suggestions as to how to optimize the code. return results in a JSON document

Wow, there’s a lot to unpack here. Let’s walk through all of the steps that the MCP Server took to get to the answer.

Trust the Process

First of all, the it struggled to get the right column name & table name - failing first on PROCESS_SOURCE_TYPE_CODE (it should be PROCESS_TYPE_CODE) and then failing on APEX_APPLICATION_PAGE_PROCESSES (it should be APEX_APPLICATION_PAGE_PROC). Not wanting to admit it was wrong, it then looked for APEX_APPLICATION_PAGE_PROCESSES in ALL_OBJECTS. Again, it was nowhere to be found, since it simply doesn’t exist.

Next - and maybe as a sanity check - it wanted to verify which user it was connected to Oracle as. It then wanted to see which schema contained APEX%. Looks like it was trying to get its bearings to ensure that 1) APEX was installed and 2) it had privileges to see the views.

Still not 100% satisfied, it ran yet another query to see if APEX_240200 owned a table named APEX_APPLICATION_PAGE_PROCESSES. To be fair, I’ve also struggled with this view over the years, as I would expect it to be called APEX_APPLICATION_PAGE_PROCESSES or even APEX_APPLICATION_PAGE_PROCS. Is it possible to feel bad for an LLM?

Next, it widened the search by querying all APEX views that start with APEX_APPLICATION_PAGE. And there it is - APEX_APPLICATION_PAGE_PROC.

Now that it has the correct view, it inspects all of the columns. Remember - the initial error was that the column PROCESS_TYPE_SOURCE_CODE was invalid. Having seen the full list, it is able to construct and run another query with the correct column names. While the query now runs successfully, we now have a data error. It’s looking for rows that have a PROCESS_TYPE_CODE of NATIVE_PLSQL and finds none, since APEX now uses just PLSQL to identify PL/SQL processes.

Persistent as ever, it now asks for a list of distinct values of PROCESS_TYPE_CODE, hoping that will shed some light on what the value really is. And once again, it finds what it’s looking for.

Now that all of the pieces are in place, the last query needed can be executed. Once it has the results, it sends them to the LLM with the initial ask (provide advice for optimization and return it in JSON) and returns the results back to us.

Failing Forward

What amazed me most is the MCP Server & LLM behaved strikingly similar to how I would have, had I been asked a similar question and did not have a deep understanding of how APEX works.

Basically, it employed the following workflow:

• Make an assumption and try something

• If it fails, alter your assumption with another assumption or more facts

• Try again

• Repeat as needed

In this case, the MCP Server & LLM were eventually successful, as the results where precisely what I was asking for.

This last example is what I find to be the most fascinating thing about using MCP Servers with LLMs. It was given a plain English prompt and using the power of the LLM, was able to navigate through the database to find what it needed and deliver the correct result.

Summary

MCP Servers are evolving extremely fast, and there’s no sign of them slowing down. They represent a critical link that extends the power of AI to your internal data without the compromise of having to share the data with the LLM directly.

While MCP Servers can perform simple tasks, their true strength is when you challenge them with multi-step, complex tasks that would take a significant amount of time without automation. In the context of APEX, I can see multiple use cases for MCP Servers from both a developer’s point of view as well as the end user. People are already starting to kick the tires and sharing their experiences on social media, and the initial results are amazing.

MCP Servers aren’t magic - but paired with an LLM, they can feel like they are. Give them a simple request in plain English and they’ll reason, guess, retry, and adapt until they get it right with the tenacity of a person looking for a solution.

That’s the real shift that MCP servers represent: you’re not just running queries, you’re collaborating with a system that can navigate and interpret your data in all kinds of ways. And once you see that in action, it’s hard to go back to the old way.

End of line.

APEX-SERT works well largely due to APEX’s declarative architecture. Rules can be configured to inspect a column in a view: if the value meets a specific criterion, the rule passes; otherwise, it fails. There’s literally no room for ambiguity when it comes to deriving the value of the rule and determining whether or not that value meets a pre-determined criteria.

Offloading this task to AI introduces the potential for less than 100% precision, which is unacceptable for our needs. And given that our current rules engine works 100% of the time, why would we make any changes to it and potentially decrease the accuracy?

Thus, given the following:

• APEX-SERT is a security tool

• Security tools - by nature of their design and purpose - need to be precise

• AI regularly hallucinates and makes stuff up

At first glance, using AI with APEX-SERT might seem inadvisable.

But is it?

Make it Make Sense

AI is here to stay and is one of the most transformative events to occur in IT. Thus, blindly stiff-arming it - even with APEX-SERT - is not the right answer. In fact, it’s not even the right question. Put more succinctly, the right question is: how do we make AI work with APEX-SERT, not should we.

Using it to replace the rules engine still doesn’t make sense yet, as there’s still too many drawbacks. First, if we were to rewrite APEX-SERT to work exclusively with AI, we would likely price out a segment of our users. AI is not free, and adding that cost as mandatory is also a non-starter.

Second, many organizations have strict rules as to where and how AI can be used. Going “all in” on an AI-only version of APEX-SERT would also shrink its potential user base, as some organizations may not be allowed to use it on their applications anymore.

After some thought, it finally hit me where AI and APEX-SERT could meet: Evaluating the quality of exceptions.

Exception Quality

Exceptions are, by and large, one of my favorite features of APEX-SERT. They enable developers to provide a rationale when they believe an attribute was incorrectly flagged - a fairly common occurrence. Exceptions also need to be approved by another developer, establishing segregation of duties and making APEX-SERT more compliant with regulations.

When creating an exception, the only requirement is to enter a value. Thus, developers can enter any value they wish, from something comprehensive and detailed to simply the letter “x”. APEX-SERT treats both of these examples as valid and advances the workflow to the next level.

It is not uncommon to have several exceptions per application, creating a significant amount of work for any approver to do, as they will need to evaluate and either approve or reject each of them. We’ve added the ability to bulk add and bulk approve/reject exceptions to make this task easier, but those features do not consider the quality of the exception itself.

This is where AI can and does make a difference.

The code to evaluate the quality of exceptions is amazingly simple. If you look at the procedure below, this is called each time an exception is created. To save cost, if an exception is created for multiple items at the same time, the score & reason is only computed once.

procedure get_exception_score
  (
   p_rule_id                in number
  ,p_exception              in varchar2
  ,p_exception_score        out number
  ,p_exception_score_reason out varchar2
  )
is
  l_valid_exceptions        varchar2(4000);
  l_summary                 clob;
 begin

-- determine score of exception using AI
if reports_pkg.get_pref_value(p_pref_key => 'AI_ENABLED') = 'Y' then

  -- get the list of valid exceptions
  select valid_exceptions into l_valid_exceptions from rules where rule_id = p_rule_id;

  -- prepare the prompt and send to AI
  if l_valid_exceptions is not null then

    l_summary := apex_ai.generate
      (
       p_prompt            => 'Evaluate the quality of the following exception: ' || p_exception
      ,p_system_prompt     => replace(reports_pkg.get_pref_value(p_pref_key => 'AI_EXCEPTION_PROMPT'), '{VALID_EXCEPTIONS}', l_valid_exceptions)
      ,p_service_static_id => reports_pkg.get_pref_value(p_pref_key => 'AI_STATIC_ID')
       );

    -- log the results
    apex_debug.message(l_summary);

    -- parse the AI response to get the score and reason
    select
       json_value(l_summary, '$.score')  as score
      ,json_value(l_summary, '$.reason') as reason
    into
       p_exception_score
      ,p_exception_score_reason
    from
      dual;

  end if;

end if;

end get_exception_score;

Basically, the code will call the LLM using apex_ai.generate. The LLM will then return only a JSON document that is parsed out via SQL and returned to the OUT parameters. That’s it!

With AI, it’s less about the code and more about the prompt. Writing a clear, concise prompt will go a long way when working with LLMs. In fact, I typically ask AI to get me started by creating a prompt for me, and then I edit and modify it as needed. Here’s the one that is used to evaluate the exceptions in APEX-SERT:

You are an Oracle IT security expert reviewing an exception provided by a user in 
response to a flagged vulnerability from the APEX-SERT tool. The user believes 
the flag is a false positive.

You are provided with a list of acceptable exceptions for this rule:

{VALID_EXCEPTIONS}

Evaluate how well the user's exception aligns with the acceptable exceptions. 

Assign a score from 1 to 5, where:

 1 = Poorly written or irrelevant exception 
 3 = Partially acceptable, needs improvement or clarification 
 5 = Clearly aligns with acceptable exceptions and is well-justified

Return only a JSON document in the following format:

{ "score": <integer from 1 to 5>, "reason": "" }

Keep the explanation concise (1–2 sentences) and do not return any additional 
commentary outside the JSON.

This prompt tells the LLM to compare each exception to a set of probable exceptions for a given rule and produce a score from 1 to 5, with 1 indicating that the exception is of poor quality and no where near a match to the anticipated ones and a 5 indicating that the exception is of high quality and a very close match to the anticipated ones. The {VALID_EXCEPTIONS} token will be replaced with valid exceptions for the specific rule in question each time. Based on the instructions, the prompt will return a simple JSON document that can easily be parsed out.

Using this score, a reviewer can readily identify which exceptions likely need to be rejected as well as those that are likely valid. This reduces the amount of time it will take a reviewer to approve or reject a batch of exceptions considerably, as they can use the score and reason that AI provides as guidance.

The exception scoring has been added to the Exceptions Report, which has be relocated under the Exceptions button on the main evaluation page. Here’s a preview of what it will look like:

We stopped short of allowing AI to refuse poorly written exceptions, as we want to be sure that we gradually and pragmatically apply AI to APEX-SERT. I can see adding this feature in at some point, with the option to disable it if desired.

Next Steps

Once the AI-enabled version of APEX-SERT is released - which should be soon - enabling the AI portion will be a 100% optional and opt-in process. You will not be forced to use the AI feature at all and the rest of APEX-SERT will continue to function without it for the foreseeable future.

You will need to provide your own LLM to use the AI features. As you know, AI calls are not free, so each user will be responsible for the associated costs.

We will continue to explore other ways to augment APEX-SERT with additional AI capabilities. One area we are likely to explore is deeper analysis of PL/SQL code, including both code embedded in APEX and named packages, procedures, and functions. Using an LLM and a well-defined prompt should produce better results than writing PL/SQL code to evaluate other PL/SQL code. The AI is just better at detecting string patterns and can do a much more comprehensive job with tasks like this.

Let me know if there’s another area of APEX-SERT that you think AI would be a good fit for.

Title photo by Lianhao Qu on Unsplash

The feature set has not changed much since my last post about it, so if you need a refresher, have a look here: https://spendolini.blog/apex-sert-the-sql

I can’t thank Michael Potter and his team in Australia enough for their help in getting this project released. He specifically helped navigate the several processes & procedures required by our employer, as well as helped to tune and squash some bugs.

SQLcl & Liquibase

One difference that you may notice is that we used SQLcl & Liquibase to build the installer. This gives us a lot more flexibility when releasing updates, as the installer will always know where to start, regardless of the version. There’s nothing different about the installation process - just run install.sql as SYSTEM or ADMIN and you’ll be up and running in no time at all!

Printing

APEX-SERT allows for either AOP or OCI DocGen to be integrated for printing of reports. In either case, you must procure your own instance & license and configure APEX-SERT accordingly.

Builder Extension

APEX-SERT makes use of one of the newer features of APEX: Builder Extensions. As a Builder Extension, you can run APEX-SERT as the same user you develop APEX applications with. This enhances the security posture of APEX-SERT itself, as previous releases needed to make a small adjustment to the APEX core schema - something that is no longer possible on ADB.

Feedback

Find a bug? Have an idea you’d like to see added? Please use GitHub issues, which can be found here: https://github.com/oracle-samples/apex-sert/issues

Download

Ready to get started? You can download it here: https://github.com/oracle-samples/apex-sert

Title photo by Tasha Kostyuk on Unsplash.

As I’ve said before, if you’ve learned how to work with one platform’s API, you’ve learned just that - a single platform’s API. Unfortunately, they are all different, and there’s no real shortcut that you can take here. You simply have to put in the work.

API Documentation

Finding the API documentation page should be your first step. In most cases, large SaaS platforms will have plenty of resources regarding their API, what it does, how to connect, etc. Jira Cloud is no exception. Their API page is loaded with good information and can be found here: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#about

Taking a look at their page, it’s broken out into a number of sections. Let’s walk through most of them, since regardless of the platform, these are the main things you’ll need to consider.

Version

APIs, like most software, have versions. Each version will add or remove parameters, results or both. Typically, the version of the API is included in the URL. Jira takes this approach, and in their documentation note the difference between version 2 & 3. For our purposes, either should work.

Authentication & Authorization

This can be one of the trickier parts of calling an API, as there’s a number of ways to handle authentication (authN) and authorization (authZ). It is important to understand how your SaaS provider does this, and ensure that you adhere to their guidelines and best practices.

For our purposes, we’re going to stick with the Ad-hoc API calls option. This is the simplest of the batch, and uses Basic Authentication, or a username and password combination.

Permissions

Jira manages permissions at the user level. Thus, if your user has a specific permission mapped to them, they will be able to call APIs that require that permission. In the example APEX application, the Jira user was an administrator, and thus could call pretty much any API. In a real-world scenario, different users would have different permissions, and you would need to account for which API they would be able to call at the APEX level - likely by querying an API to determine which permissions they had and using APEX authorization schemes to hide & show corresponding APEX components.

Expansion

For efficiency, Jira APIs use “resource expansion”. All this means is that if you call the plain API, you’ll get a small number of values returned in the JSON file. If you specify values in the “expand” option, you’ll get additional values in the JSON. Thus, if you don’t need lots of data, don’t specify values in the “expand” option and vice versa.

Pagination

Perhaps the most important part of the Jira API is pagination, as it provides some of the core mechanical support for how APEX navigates data found in reports.

When you build a report on a local table or view, APEX can handle all of the pagination services natively, as it knows how to augment the local SQL query to determine how many rows there are, which set it’s looking at currently, and all of the other parameters required to allow users to paginate through the results. This is native, no-code functionality of APEX and has been present since essentially day one.

However, when you put the data sources behind a web service, APEX becomes “blind”, since it can no longer get pagination values by augmenting SQL calls. Additionally - and perhaps one of the most important concepts - is that web services will only send back a portion of the full dataset per request. Imagine asking for a million rows of data. It’s just not practical to send all million rows over in a JSON file, as it would take too long to transmit and then parse that file all at once.

Thus, web services typically send results in much smaller chunks, typically 25 or 50 rows of data. As users click “next set”, the web service is called again, and the next set of rows are sent back and displayed. But in order for APEX - or any client - to know where it is in the dataset, there needs to be a way to manage the pagination.

Thus, web services typically provide a mechanism as to how they manage pagination. They do this by providing bits of information as part of the JSON document that they send back. These results can be anywhere in the result set - it varies by web service.

For example, the Jira API gives the following example of how they handle pagination:

{
    "startAt" : 0,
    "maxResults" : 10,
    "total": 200,
    "isLast": false,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
    ]
}

Each parameter is also defined on their site. Here’s those definitions:

• startAt is the index of the first item returned in the page.

• maxResults is the maximum number of items that a page can return. Each operation can have a different limit for the number of items returned, and these limits may change without notice. To find the maximum number of items that an operation could return, set maxResults to a large number—for example, over 1000—and if the returned value of maxResults is less than the requested value, the returned value is the maximum.

• total is the total number of items contained in all pages. This number may change as the client requests the subsequent pages, therefore the client should always assume that the requested page can be empty. Note that this property is not returned for all operations.

• isLast indicates whether the page returned is the last one. Note that this property is not returned for all operations.

By reading these values, developers can augment their code so that they can request data from a web service, keep track of where they are, and then request the next or even previous set of rows and display those to the user. Developers will also want to know when they reach the end of a result set; hence the isLast parameter. When that is true, developers will need to disable or hide the “next set” button, since there is no such thing.

If building this from scratch, there’s a fair amount of work required to consume, manage and react to the pagination metadata. Fortunately for us, when using APEX’s REST data sources, we don’t have to write any code at all to manage pagination. All we need to do is provide some guidance to APEX by way of pagination details and it will handle the rest. This benefit alone - APEX being able to automatically handle pagination of data received from a web service - cannot be understated.

Now that we know how Jira handles pagination, we can adjust one of our REST data sources accordingly. Below is what the pagination section of the Projects REST data source looks like:

We’ll dive into the specifics of these setting in a future post. For now, you should be able to see the values specified in the Jira API mapped to their corresponding attributes in APEX.

Ordering

Another important concept is ordering the results. Again, consider that million-row dataset. If we wanted to sort by Issue Number, and only have 50 rows, we simply can’t. Thus, most web services will do their sorting on the server and send back pre-sorted data.

Jira allows us to pass a column name to the URL parameter orderBy to perform sorting. It will then sort the data accordingly and return the dataset in a pre-sorted format. Adding a + or - before the column name will sort the data ascending or descending, respectively.

Timestamps

When working with APIs, dates are sent as strings, typically in a timestamp format. There is no “date” datatype, as it’s all just text. Many web services - including Jira - will use the ISO 8601 format for timestamps. And in Jira’s case, the timezone used is the one mapped to the user’s account that the API key is associated with.

API Endpoints

Now that we have a good idea as to the basics of how Jira’s APIs work, let’s dig into some of the specifics of what it actually does. Most SaaS APIs will provide not only documentation on each endpoint, but also either a Postman Collection, an OpenAPI specification or both. Jira provides both, and they can be found at the top-right of this page: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#about

Postman Collection

Postman is a popular API development tool that many organizations use. It basically allows you to set up a test harness and make RESTful calls to API endpoints. I’m not going to get into the specifics on how to use it here; have a look at their site to get started if it’s new to you.

Using Postman to explore and become familiar with an API is almost always the best first step. Use the APIs documentation & samples to get a jump on how to use it, paying specific attention to how to paginate, sort and pass parameters to it, as well as the requisite security attributes.

Using Postman to do this allows me to focus on the parameters and functionality of the APIs in an easy to use tool. I find this approach a lot easier and faster than wrapping these calls in SQL or PL/SQL. Postman also provides a fair bit of debug information if and when you get stuck.

Let’s fire up Postman and hit our first endpoint!

1. Navigate to the Jira Cloud API page here: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#about

2. Click the icon labeled Postman Collection and save the file to your desktop.

3. In Postman, click Import.

4. Locate the collection file that you just downloaded and drag it to the Postman window.

5. The collection should automatically load and you’ll see the following screen:

Now that we have a collection, let’s create an environment. An environment is a set of variables that are automatically passed to a collection. It’s used when you have different sets of APIs across different servers - such as dev, test, QA & production. While not required, it’s a lot easier to use environments to set and store variables, as they will impact any endpoint that makes use of the variable syntax in Postman.

To create an environment:

1. Click on the Environment tab in the left side of the page.

2. Click the “+” icon to crate a new environment.

3. Rename your environment to something descriptive. I’ll use spendoliniblog for mine.

Next, we need to add the three main variables that are required to call the Jira API: host, username and apiToken.

4. Enter host as the Variable, set Type to default and enter your Atlassian hostname for the Initial Value. This was the hostname that you specified when creating your Atlassian account in the previous blog post.

5. On the next line, enter username as the Variable, set Type to default and enter the email that you used to sign up for your Atlassian account as the Initial Value.

6. On the next line, enter apiToken as the Variable, set Type to secret and paste in the API Key that you generated when you signed up for your Atlassian account as the Initial Value.

7. Click Save.

The screen should look similar to this:

Let’s use these freshly defined credentials to call one of the APIs to make sure that it all works.

1. Click on the Collections icon on the left side of the screen.

2. Scroll down and locate and expand the Projects folder.

3. Select Get All Projects.

Notice that many of the variables are highlighted in pink - indicating that they do not have a current value. You can hover over the blue ones to see what the value is set to.

To apply our environment to this endpoint:

4. Select the environment we created from the Environments menu in the upper right.

5. Click Send to call the endpoint using the variables defined in our environment.

If configured correctly, you should see something similar to the following:

Feel free to play with any of the other endpoints - but understand that changes will be immediately made to your Jira projects and may be irrevocable. It’s a good idea to make sure that the Jira environment that you’re interacting is not production.

OpenAPI

According to their website, OpenAPI “provides a consistent means to carry information through each stage of the API lifecycle. It is a specification language for HTTP APIs that defines structure and syntax in a way that is not wedded to the programming language the API is created in.”

In other words, OpenAPI is a standard way to define RESTful endpoints. This allows developers to quickly discover what an API does, how it works and what operations are available. This standard is language agnostic - developers need to know nothing about the language that the API is written in, only about the language from which they will call it.

There’s a number of tools out there that can read OpenAPI specifications - Postman being one of them. Let’s stick with that and import the OpenAPI document.

1. Navigate to the Jira Cloud API page here: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#about

2. Click the icon labeled OpenAPI.

3. Your browser will open a new tab and you should see the following:

This is intentional; the browser is displaying the OpenAPI document, which is in YAML format. Let’s save the contents to our machine so that we can import it into Postman.

4. From the File menu, select Save Page As or a similar option depending on your browser.

5. Save the file to your desktop.

6. Switch to Postman, select Collections on the left side of the screen and then click Import.

7. Drag the file you just downloaded to the Postman window. You should see something similar to this:

8. Leave the default option selected and click Import. Once loaded, you should now have two collections:

Unfortunately, I could not get the OpenAPI to import properly. Many of the endpoints had redundant variables and some of the initial values caused calls to the endpoint to fail. To give you an example, here’s the projects/search endpoint from the Postman Collection:

And here’s the same endpoint from the OpenAPI import:

At least for Jira, I’ll stick with the Postman collection.

Conclusion

Using a tool like Postman to explore an API is almost a requirement. Vendor’s APIs will vary widely from API to API, so even if you have experience with a few APIs, the next one can throw you off. Get used to using the tool’s more advanced capabilities like environments, variables and the vault to make it even more impactful. Only once you’ve mastered the basics of any API are you ready to start calling it from APEX.

The key skill that you’ll want to take away from all of this is learning how to apply a change in Postman to an APEX REST Data Source. Once you’ve mastered this skill, there won’t be an API you can’t conquer.

Coming up next - we’ll dive into the implementation of the APIs inside APEX and cover the steps and through processes that I went through to get that working.

Title Photo by Mick Haupt on Unsplash

As cool as they are, REST Data Sources do take some getting used to. Some features are fairly obvious and easy to learn, while others are not.

Rather than walk through all of the specifics of REST Data Sources, I thought it would make more sense to do it in the context of a real integration - something that we can all relate to. Thus, I selected to use Jira for this for several reasons.

First of all, Jira has a massive API set that’s actually somewhat easy to understand and fairly well documented. This will make it easy for anyone who wants to expand on the work that I outline in my posts.

Second, Jira also has a “free forever” tier. You can create a cloud account with up to 10 users for free. This will make it easy for people to follow along, as there’s no cost at all.

Third - and perhaps most importantly - Jira has complex logic that sits behind the APIs that we don’t have to re-write in PL/SQL. If this were a real project, this would be absolutely critical, as all transactions from either APEX or Jira is fed to the same API layer, ensuring that we only have a single code base to maintain. And in the case of a SaaS application like Jira Cloud, we don’t even need to maintain it.

For example - if I want to assign a different project code to a Jira Project, all I need to do is submit the update. Jira’s APIs take care of updating the title of all of the issues. Same thing if I delete an Epic - all related issues are updated automatically. Even cooler - any automation that is configured will still fire if it’s triggered by the APIs.

Most SaaS platforms fall into this category - API-first platforms that work regardless where the transaction is originated. APEX can easily adapt and also fit into this architecture as you’ll see as soon as you have your application up & running.

The APEX application that I built only does a fraction of what Jira is capable of. It can create bugs, tasks and epics, assign them to different workflows, add labels to any of them and capture notes. It also has a project-level summary dashboard with charts & reports. Keep in mind here my goal was to create a real-world, practical example to highlight what’s possible with REST Data Services, not build a feature-for-feature implementation of Jira.

Getting Started

Rather than create a series of blogs that have all of the steps outlined to build the solution (there’s just too many), I’m going to take a different approach: I’ll provide the application for download and then blog about what I did, referencing what’s in the application. I believe that this approach will make it easier to follow along, as I probably spent too much time making incremental changes to the UI to get it just the way I wanted it.

You will, however, need your own Atlassian account if you want to test the integration. Fortunately, they are free and take just seconds to set up.

Create a Free Atlassian Account

Like Oracle, Atlassian has a free tier which limits what you can & can’t do, how many users you can have, etc. Basically, you can have up to 10 users and 2GB of data across their platform. For testing and learning, that’s more than enough.

You can read about the specifics here: https://www.atlassian.com/software/free

Let’s walk through the process of crating a new account:

1. Navigate to the following URL: https://www.atlassian.com/try/cloud/signup?bundle=jira-software&edition=free

2. Enter your email address and click Sign Up.

3. A six-character code will be sent to the email that you used to sign up. Open that email and enter the code on the next screen and click Verify.

4. Next, add your Full Name and a Password for your account; click Continue when done.

5. Enter the name of the site. You’ll want to remember this full URL for later when we add the Jira endpoint to APEX. In my case, it’s spendoliniblog.atlassian.net.

6. Next, answer a couple of questions about how you’ll use Jira.

7. When you’re done, you’ll see the Welcome Page, where you can name your first project. Name it anything you like; I took the default “My Scrum Project”.

Take a few minutes to explore Jira Cloud. There’s plenty of documentation and a helpful community on Atlassian’s site that you can refer to, should you get stuck.

Downgrade to Free Edition

You’ll need to make an adjustment to the account that you just created. Technically, you’re in a 30 day free trial for the Premium Tier, which at the time I’m writing this post, is $17/user/month. From what I remember, once the 30 days are up, you can also make this adjustment, but here’s the steps if you don’t want to wait.

To downgrade:

1. Click the gear icon in the upper-right and select Atlassian account settings.

2. Click on the Billing tab.

3. Click Change Plan. On the next screen, click Select Free.

5. Click Downgrade to free.

6. You’ll see the following confirmation message:

Of course, if you want to pay for Jira to unlock more features, have at it. This blog series makes use of only those available with the Free Edition.

Create an Atlassian API Key

In order to call the Jira APIs, you’ll need to create an API key. API keys in Jira are mapped to the user. Thus, if you have 5 users calling the APIs, they will each need their own API key. Makes sense when you have a platform that charges by the user and don’t want the API layer to become a back door that skirts around licensing!

To create an API Key:

1. Navigate back to the home page of your Atlassian account with the following link: https://home.atlassian.com/

2. Click the gear icon in the upper-right and select User management.

3. Click on Account Settings.

4. Click on the Security tab.

5. Click Create and manage API tokens.

6. Click Create API Token.

7. Enter APEX Integration for the Name and set the Expires on to a far-out date. Atlassian lets you set the date up to a year out, so that’s what I chose.

8. Click Create. When the token is displayed, be sure to copy it and store it somewhere safe. We will need this later when installing the APEX application, and this is the only time it will be displayed.

You should now have three pieces of information that we will need later:

1. Your Atlassian hostname

2. Your email address that you used to sign up for Atlassian with

3. Your API Key

Choose Where to Host the APEX Application

You can host the APEX application anywhere that has access to Jira Cloud. I’ve tested it on both apex.oracle.com and APEX on ADB in OCI. It will even work on a local container instance of APEX! If you’re running your own instance behind a VPN, you may run into issues where calls from the database to Atlassian are blocked.

If you’re going to install this application on either ADB-S or apex.oracle.com, you can skip the following step. If you’re installing this on a local container or DBaaS or on-prem APEX, you’ll likely need to execute the following as ADMIN (ADB-D) or SYSTEM (non-ADB) and run the following:

begin
  dbms_network_acl_admin.append_host_ace (
    host       => '[server name].atlassian.net',
    lower_port => 443,
    upper_port => 443,
    ace        => xs$ace_type(privilege_list => xs$name_list('connect'),
                              principal_name => 'APEX_240100',
                              principal_type => xs_acl.ptype_db));
end;
/

Make sure to adjust the value for principal_name if you’re not running APEX 24.1 and change [server name] to the name that you used.

Download and Install the APEX Application

Once you have a place to put the application and have opened up the respective URL for your Atlassian site, all that’s left is to download and install the APEX application.

You will need at least APEX 24.1 for this to work.

1. Download the APEX application by clicking here.

• 💡

  Warning: This APEX application calls the Jira Cloud REST APIs and has not been thoroughly tested. There is a risk that it will make updates that cause issues with your Jira data. Use it at your own risk.

2. Login to your APEX workspace as at least a developer.

3. Click on the App Builder icon.

4. Click on Import.

5. Drag the application export file that you downloaded (apex_and_jira.sql) to the Drag and Drop region and click Next.

6. Click Install Application. No need to select any specific Application ID.

On the next screen, we’ll provide the Remote Server information. Credentials also need to be provided, but we’ll do that after, since not all of the values we need to provide are available here.

7. In the Remote Servers section, change the hostname in the Base URL to what you specified when you created your Atlassian account. The full URL should look like this: https://[servername].atlassian.net/rest/api/

7. Click Next.

8. Click Edit Application.

9. Click Shared Components.

10. Click Credentials.

11. Click Credentials for Jira Projects.

12. Set the values to the following and click Apply Changes.

13. Navigate back to the application builder and run the application. If all was configured correctly, you should see an APEX application with a link to the starter Jira project that you created earlier.

14. Click on the tile for My Scrum Project to see the details. It should be blank at this point unless you added an issue earlier.

At this point, the integration is up and running. You should be able to create issues in either APEX or Jira, reload, and see them on either side.

Caveats

I tried to keep things as generic as possible so that it’s easy to get to a working application. In doing that, there’s a few items in the APEX application that are disabled by associating them with a Build Option and setting that to exclude.

Backlog

While default Jira projects have a Backlog, the default workflow does not. Thus, the “swim lane” on page 10 for Backlog is disabled. If you add another step to your workflow and name it Backlog, you can re-enable this region.

Sprints

Additionally, you won’t likely see your issue on the Kanban Board until you add it to a sprint and start it. Make sure to perform those actions in Jira so that both Jira and APEX display the same content.

Additional rules could be built into APEX to manage sprints as well, but that was out of scope for this blog series.

Priorities

Default Jira projects do not enable the ability to manage the Priority of issues. Thus, the page item for Priority on page 10 has also been disabled. If you add Priority to your issues screen, you can enable it in APEX and it should work, as it is mapped in the REST Data Source.

Next Steps

This post is just the beginning. I’m going to create several more posts over the next few days that walk through how this integration works, tools that you’ll want to have to build similar things, and tips on how to debug issues when they occur. Stay tuned!

Title Photo by Eden Constantino on Unsplash

Thus, if we wanted to quickly spin up a new, fresh database that looks like the one we have, we’d be out of luck. While upgrading APEX & adding DBMS_CLOUD only take minutes, it could get repetitive if we need to do this regularly. And that’s just all that’s different today - things will change as we add more features & applications over time.

To solve this issue, we can create a new image from our container. That image can then be used to create new containers - just like we’ve used the images provided by Oracle.

To wrap up this series, let’s walk through how we can create an image based on our container so that we can spin up new containers that have DBMS_CLOUD, APEX and anything else we want pre-installed.

Creating a New Image

We’ll start by creating a new image.

1. From Podman Desktop, locate and stop the oracle container.

It is important to stop the container before committing it, otherwise you risk saving a corrupt container.

2. Open a new terminal window and enter and run the following command:

podman commit oracle

This will take a few minutes to complete. You should see something similar to the screenshot below as this is running:

Next, let’s get a list of all images on our local repository.

3. Enter and run the following command:

podman images

You should see something similar to the screenshot below:

4. Take note of the IMAGE ID of the REPOSITORY named <none>.

5. Run the following command, replacing [IMAGE ID] with the IMAGE ID from the previous step.

podman tag [IMAGE ID] oracle-new

6. Switch back to Podman Desktop and select the Images tab. Notice that there should be a new entry called localhost/oracle-new. This is the image that was just created and tagged.

7. Create a new container from the new image by clicking on the Play button.

8. Optionally enter a Container Name and click Start Container and you should be up and running right where you left off!

Ideally, you would destroy your original Oracle Database container first and then use the command line to create a new one based off of the new image. You can do that by running this code:

podman run --name oracle --ip 10.88.0.2 -p 1521:1521 localhost/oracle-new

Summary

Creating a new image based on a changed container is a helpful way to preserve your work, should you need to start over from a specific place. Keep in mind that if a new Oracle 23ai image was posted by Oracle, you would need to pull that down and re-apply all of the infrastructure changes there. Thus, it’s a good idea to try to keep any of these changes scripted so that they can be applied quickly and in a single script.

This post will likely wrap up the series Containerized, Local Oracle 23ai Environment - at least for now. I’m sure that I’ll find additional things that I want to add to my local development environment, and when I do, I’ll be sure to add them to this series.

If you haven’t already, be sure to start at the first post and go through all of them. I’ve tried to be as specific as possible and provided detailed steps, code snippets and screen shots. Having said that, there’s likely issues and/or typos that make things less than perfect. Please let me know if you find one of those, as I can quickly correct it if and when necessary.

References

• https://www.techrepublic.com/article/create-custom-images-podman/

Photo by Samsung Memory on Unsplash

Connor McDonald provides the details here on his blog.

Thus, I’ve removed that entire section from that post, as it’s just not needed. If you already went through the exercise and added a wallet, that’s fine, too. Simply remove the last three lines of the sqlnet.ora file and everything should still work.

This is just another small but significant and time-saving feature of Oracle 23ai designed to make development faster and easier.

DBMS_CLOUD is a package provides a layer so that the database can manage files and directories in OCI’s object storage service. Typically found only in ADB environments, DBMS_CLOUD can also be installed on non-ADB instances. Here’s how:

Installing DBMS_CLOUD

There’s a couple of existing resources that will step through installing DBMS_CLOUD:

• Oracle-Base’s DBMS_CLOUD Guide

• Oracle Support Note 2748362.1

You’ll of course need a valid Oracle Support account to see the later one.

Either of these guides should provide the steps required, but for consistency’s sake - and to address some of the nuances of doing this in an Oracle 23ai Database container - I’ll walk through the steps here as well.

Podman Terminal

Since we’re running the database in a container, and we can’t SSH to that container, we will need to use Podman’s terminal. This terminal give us a basic shell where we can run standard commands from. It’s a little feature-starved, but it will work for what we need.

To access Prodman’s terminal:

1. Open up Podman.

2. Select the Containers icon (2nd from the top).

3. Click on the three dots and select Open Terminal.

From here, we’ll kick off the database installation.

Database Installation

First, let’s create a new directory.

1. In the Terminal, enter and run the following command:

mkdir -p /home/oracle/dbc/

Next, we will create a script that when run, will install DBMS_CLOUD.

2. To create the script, run the following command:

vi /home/oracle/dbc/dbms_cloud_install.sql

If you’re not familiar with the vi editor, shame on you. Seriously. If that is the case, there’s tons of other resources that will familiarize you with basic commands. I’ll outline precisely what you need to do here, just in case.

3. Once the previous command is run, hit the I key to place vi into INSERT mode. You should see —- INSERT -— along the bottom of the window.

4. Copy the following script:

@$ORACLE_HOME/rdbms/admin/sqlsessstart.sql

set verify off
-- you must not change the owner of the functionality to avoid future issues
define username='C##CLOUD$SERVICE'

create user &username no authentication account lock;

REM Grant Common User Privileges
grant INHERIT PRIVILEGES on user &username to sys;
grant INHERIT PRIVILEGES on user sys to &username;
grant RESOURCE, UNLIMITED TABLESPACE, SELECT_CATALOG_ROLE to &username;
grant CREATE ANY TABLE, DROP ANY TABLE, INSERT ANY TABLE, SELECT ANY TABLE,
CREATE ANY CREDENTIAL, CREATE PUBLIC SYNONYM, CREATE PROCEDURE, ALTER SESSION, CREATE JOB to &username;
grant CREATE SESSION, SET CONTAINER to &username;
grant SELECT on SYS.V_$MYSTAT to &username;
grant SELECT on SYS.SERVICE$ to &username;
grant SELECT on SYS.V_$ENCRYPTION_WALLET to &username;
grant read, write on directory DATA_PUMP_DIR to &username;
grant EXECUTE on SYS.DBMS_PRIV_CAPTURE to &username;
grant EXECUTE on SYS.DBMS_PDB_LIB to &username;
grant EXECUTE on SYS.DBMS_CRYPTO to &username;
grant EXECUTE on SYS.DBMS_SYS_ERROR to &username;
grant EXECUTE ON SYS.DBMS_ISCHED to &username;
grant EXECUTE ON SYS.DBMS_PDB_LIB to &username;
grant EXECUTE on SYS.DBMS_PDB to &username;
grant EXECUTE on SYS.DBMS_SERVICE to &username;
grant EXECUTE on SYS.DBMS_PDB to &username;
grant EXECUTE on SYS.CONFIGURE_DV to &username;
grant EXECUTE on SYS.DBMS_SYS_ERROR to &username;
grant EXECUTE on SYS.DBMS_CREDENTIAL to &username;
grant EXECUTE on SYS.DBMS_RANDOM to &username;
grant EXECUTE on SYS.DBMS_SYS_SQL to &username;
grant EXECUTE on SYS.DBMS_LOCK to &username;
grant EXECUTE on SYS.DBMS_AQADM to &username;
grant EXECUTE on SYS.DBMS_AQ to &username;
grant EXECUTE on SYS.DBMS_SYSTEM to &username;
grant EXECUTE on SYS.SCHED$_LOG_ON_ERRORS_CLASS to &username;
grant SELECT on SYS.DBA_DATA_FILES to &username;
grant SELECT on SYS.DBA_EXTENTS to &username;
grant SELECT on SYS.DBA_CREDENTIALS to &username;
grant SELECT on SYS.AUDIT_UNIFIED_ENABLED_POLICIES to &username;
grant SELECT on SYS.DBA_ROLES to &username;
grant SELECT on SYS.V_$ENCRYPTION_KEYS to &username;
grant SELECT on SYS.DBA_DIRECTORIES to &username;
grant SELECT on SYS.DBA_USERS to &username;
grant SELECT on SYS.DBA_OBJECTS to &username;
grant SELECT on SYS.V_$PDBS to &username;
grant SELECT on SYS.V_$SESSION to &username;
grant SELECT on SYS.GV_$SESSION to &username;
grant SELECT on SYS.DBA_REGISTRY to &username;
grant SELECT on SYS.DBA_DV_STATUS to &username;

alter session set current_schema=&username;
REM Create the Catalog objects
@$ORACLE_HOME/rdbms/admin/dbms_cloud_task_catalog.sql
@$ORACLE_HOME/rdbms/admin/dbms_cloud_task_views.sql
@$ORACLE_HOME/rdbms/admin/dbms_cloud_catalog.sql
@$ORACLE_HOME/rdbms/admin/dbms_cloud_types.sql

REM Create the Package Spec
@$ORACLE_HOME/rdbms/admin/prvt_cloud_core.plb
@$ORACLE_HOME/rdbms/admin/prvt_cloud_task.plb
@$ORACLE_HOME/rdbms/admin/dbms_cloud_capability.sql
@$ORACLE_HOME/rdbms/admin/prvt_cloud_request.plb
@$ORACLE_HOME/rdbms/admin/prvt_cloud_internal.plb
@$ORACLE_HOME/rdbms/admin/dbms_cloud.sql
@$ORACLE_HOME/rdbms/admin/prvt_cloud_admin_int.plb

REM Create the Package Body
@$ORACLE_HOME/rdbms/admin/prvt_cloud_core_body.plb
@$ORACLE_HOME/rdbms/admin/prvt_cloud_task_body.plb
@$ORACLE_HOME/rdbms/admin/prvt_cloud_capability_body.plb
@$ORACLE_HOME/rdbms/admin/prvt_cloud_request_body.plb
@$ORACLE_HOME/rdbms/admin/prvt_cloud_internal_body.plb
@$ORACLE_HOME/rdbms/admin/prvt_cloud_body.plb
@$ORACLE_HOME/rdbms/admin/prvt_cloud_admin_int_body.plb

-- Create the metadata
@$ORACLE_HOME/rdbms/admin/dbms_cloud_metadata.sql

alter session set current_schema=sys;

@$ORACLE_HOME/rdbms/admin/sqlsessend.sql

5. Select the Podman Terminal window.

6. Paste in the script with CTRL-V (PC) or Command-V (Mac).

7. Hit the Esc key.

8. Type the following: :wq and hit return.

Congrats, you’re a vi expert now!

Next, we’re going to run the script via catcon.pl. This perl script will install DBMS_CLOUD into all PDBs as well as the CDB. We’ll pass our freshly minted script as a parameter and run it as SYS.

9. Copy the following code, changing [SYS Password] to the actual SYS password in the CDB before running.

$ORACLE_HOME/perl/bin/perl $ORACLE_HOME/rdbms/admin/catcon.pl \
  -u sys/[SYS Password] \
  --force_pdb_mode 'READ WRITE' \
  -b dbms_cloud_install \
  -d /home/oracle/dbc \
  -l /home/oracle/dbc \
  dbms_cloud_install.sql

This script will run for a few seconds. If successful, you should see something similar to the following:

Take a moment to browse the log file to see if there’s anything amiss.

Even better - simply connect to the CDB and check to see if DBMS_CLOUD is there:

10. From the Podman terminal, type the following: sqlplus / as sysdba

11. Once connected, enter and run the following: desc dbms_cloud

You should see all of the procedures and functions associated with DBMS_CLOUD.

Let’s quickly check our PDB:

12. Enter and run the following command: alter session set container = freepdb1;

13. Enter and run the following: desc dbms_cloud

Once again, you should see all of the procedures and functions associated with DBMS_CLOUD.

Wallet Installation & Configuration

In Oracle Database 23ai, there’s no need to install and configure a wallet, since all of the root CA certificates from the operating system can be shared. See this post by Connor McDonald for details.

Adding ACL Entries

Now that we have DBMS_CLOUD installed, we need to create another entry in the database’s ACL so that it can call outbound web services - such as object storage. I’ve trimmed the steps required to do this to assume that we’re running on the Oracle 23ai free container. The steps found on Tim’s blog and the Oracle Support Note are much more comprehensive, and I recommend that you take a look there if your needs fall outside the scope of the container.

Adding ACL entries needs to be done in the CDB this time, not our PDB, so we need to run the following commands from the Podman Terminal again.

1. Navigate to the Podman Terminal.

2. Start SQL*Plus and connect as SYS by entering the following: sqlplus / as sysdba

3. Enter and run the following:

begin
dbms_network_acl_admin.append_host_ace
  (
  host =>'*',
  lower_port => 443,
  upper_port => 443,
  ace => xs$ace_type
    (
    privilege_list => xs$name_list('http', 'http_proxy'),
    principal_name => upper('C##CLOUD$SERVICE'),
    principal_type => xs_acl.ptype_db)
    );

commit;

end;
/

We can verify that this worked with the following formatting & query. Since we’re stuck with SQL*Plus, we’ll have to throw some good ol’ COL commands to make the data fit.

4. Enter and run the following:

col host for a10
col lower_port for a5
col upper_port for a5
col principal for a20
col principal_type for a20
col privilege for a20
set lin 200

SELECT  
   host
  ,lower_port as lower
  ,upper_port as upper
  ,principal
  ,principal_type
  ,privilege
FROM   
  dba_host_aces
ORDER BY 
  host
 ,ace_order
/

The output should look similar to this:

HOST            LOWER      UPPER PRINCIPAL            PRINCIPAL_TYPE       PRIVILEGE
---------- ---------- ---------- -------------------- -------------------- --------------------
*                                GSMADMIN_INTERNAL    DATABASE             RESOLVE
*                 443        443 C##CLOUD$SERVICE     DATABASE             HTTP_PROXY
*                 443        443 C##CLOUD$SERVICE     DATABASE             HTTP

Creating OCI Components

Remember - what we’ve just spent time creating is the plumbing. It does not give us any specific access into OCI, but rather facilitates the calls when we make them. We still need to present the correct credentials, which need to be mapped to a user, which needs to be mapped to a group, which needs to be mapped to a policy that grants access to the object storage buckets in a specific compartment.

Create a User, Auth Token & Group

1. Login to the OCI console at https://cloud.oracle.com with an administrator account.

2. Using the main menu, navigate to Identity & Security > Domains.

3. Click Default (current domain).

4. Click on the Users tab. You should see a list of users in your domain.

5. Click Create User.

6. Fill out the form, entering a First Name, Last Name and Username/Email. Ensure that Use the email address as the username is checked and click Create.

We can dial down this user’s capabilities a bit so that all they are allowed to do is use Auth Tokens.

7. Click the Edit user capabilities button.

8. Uncheck all options except Auth Token.

9. Click Save changes.

Next, let’s create the Auth Token.

10. Under the Resources section, click Auth tokens.

11. Click the Generate token button.

12. Enter Object Storage for the Description and click Generate Token.

10. On the next screen, be sure to copy the generated token. This will be the only opportunity to do so.

11. Click Close to dismiss the modal.

While we’re here, let’s create a group. This group will he mapped to a policy that we’ll create in the next section that will allow our user & auth token to access object storage buckets.

12. In the breadcrumb, click Default Domain.

13. Click the tab for Groups.

14. Click Create Group.

15. Enter Read Object Storage as the Name and be sure to select the user that you created in the previous steps.

16. Click Create.

Create a Policy

Now that we have a user and auth token, we will need to create a policy that permits access to the object storage buckets, map that policy to a group, and then add our user to that group. That will allow us to use dbms_credential to make calls to Object Storage using the auth token associated with our user.

The steps here are similar for what was done to get OCI Email Services integrated with our portable development environment.

1. From the OCI Console, navigate to Identity & Security > Policies.

2. Click Create Policy.

3. Enter ReadObjectStorage for the Name and Read Object Storage Policy for the Description.

4. Since we used the Default Domain, set the compartment to the Root compartment. That’s the first one on the list and should end with (root).

5. In the Policy Builder, set Policy Use Cases to Storage Management.

6. Set Common policy templates to Let users download objects from Object Storage buckets.

7. In the middle select list labeled Select a group, set it to Read Object Storage.

8. In Location select list, set it to any compartment and make note of that. We will need to create an Object Storage bucket in that compartment in the next section.

9. Click Create.

At this point, we have configured our OCI security model - the policy includes a specific set of resources and a group and the group includes the user. Thus, the user that we created can call DBMS_CLOUD and present their auth token to read any bucket in the compartment we specified.

Create a Bucket

Before we can test DBMS_CLOUD, let’s make sure that we have at least one bucket in the compartment we referenced in the policy.

1. From the OCI Console, navigate to Storage > Buckets.

2. Set the Compartment to the one that you selected in the previous steps.

3. Click Create Bucket.

4. Enter bucket_test for the Name.

5. Click Create.

6. Next, click the name of the bucket that was just created - bucket_test - to edit the bucket.

Let’s upload a couple images or files to the bucket so that we can properly test it out. Anything will work.

5. In the Objects region, click Upload.

6. Drag the file you wish to upload to the region on the page and click Upload.

7. Once the file uploads, click the Close button.

Repeat steps 5 through 7 a couple of times so that you have a few files to test with.

Before we leave the Object Storage page, we need one more thing - the URL that we will use to access the button. The easiest way to get this it to edit one of the file and copy it from there.

8. In the Objects region, click the three dots next to any of your files and select View Object Details.

9. Copy the value of the URL Path (URI), as we will need that in the next section.

10. Click Cancel to dismiss the modal window.

Create a DBMS_CREDENTIAL

We’re almost there! The last thing we need to do before testing is create a DBMS_CREDENTIAL. This DBMS_CREDENTIAL will allow us to store our username and auth token in a secure place in the database. When we do call DBMS_CLOUD, we’ll pass in the DBMS_CREDENTIAL that we create here, so that DBMS_CLOUD can properly authenticate when making its calls.

The DBMS_CREDENTIAL should be created in the same schema that your APEX application will parse as. Thus, in our case, we’ll stick with the DEMO schema that we created a while back.

1. Open a new terminal window.

2. Connect to the database as the DEMO user, using the following command, replacing [demo password] with the password of the DEMO schema:

sql demo/[demo password]@localhost:1521/freepdb1

3. Once, connected, run the following command, replacing [email address] with the Username that you created previously and [auth token] with the value of the Auth Token that you copied earlier.

begin
  dbms_credential.create_credential
    (
     credential_name => 'obj_store_cred'
    ,username        => '[email address]'
    ,password        => '[auth token]'
  );
end;
/

Test DBMS_CLOUD

And now, the final step.

1. Enter and run the following command, replacing [object storage url] with the value of the URL you copied in the last section without the filename. It should look something similar to this:

   https://objectstorage.us-ashburn-1.oraclecloud.com/n/fjaltjsfsdxw/b/bucket_test/o/

select 
  object_name
 ,bytes
from   
  dbms_cloud.list_objects
    (
     'obj_store_cred'
     ,'[object storage url]'
    )
/

If everything was done correctly, you should see something like this:

The same SQL can also be used in APEX - simply copy it to a report region and run the page.

Summary

Adding DBMS_CLOUD to your containerized development environment adds yet another capability that you can use. With it, you can easily and securely interact with files stored in object storage buckets. This post only covered adding the ability to read files from a bucket. It’s entirely possible to expand on the scope and build APEX applications that provide the ability to upload and even manage buckets themselves.

Keep in mind that you made changes to the database configuration within the container. Thus, it’s different that the image that you downloaded, and if you create a new container from that image, none of these changes will be there. You would have to re-install DBMS_CLOUD to get back to where we are now. Not a huge deal, but an extra step nonetheless.

Title Photo by Vladimir Anikeev on Unsplash

LLM stands for Large Language Model. It's a type of artificial intelligence (AI) model that's designed to process and understand human language at a massive scale. Large Language Models are trained on vast amounts of text data, which enables them to learn patterns, relationships, and structures within language. This training allows the models to generate human-like text, respond to questions, and even engage in conversations.

And to be fully transparent, an LLM (Llama 3.2) wrote that last paragraph. In fact, AI generates the SEO summaries for all of my blog posts, as it’s a feature of the Hashnode blogging platform. Ya, it’s everywhere.

So why not integrate it with our local development platform?

In this post, we’ll walk through the steps to download & install an LLM - Llama 3.2 - to our local machine, fire it up and integrate it with APEX in our Oracle 23ai container.

Installing Ollama & LLM

The first thing that we need to do is download a program called Ollama. Simply put, Ollama is an application that enables users to install and run LLMs on their local machines. It obfuscates all of the hard parts, and in fact, the next few steps will only take a few minutes to complete.

Download & Install Ollama

To download Ollama, follow the steps below:

1. Navigate https://ollama.com/

2. Click Download.

3. Select your operating system and the download will start.

4. Once it’s downloaded, unzip the file and drag the Ollama icon to your main Applications folder.

5. Double-click the Ollama icon to start the installation. You should see the following window:

6. Click Next.

7. Ollama will prompt to install the command portion. You will need to enter an Administrator password to pass this step after you click Install.

8. Next, copy the command ollama run llama3.2 from the window by clicking on the copy icon.

9. Click Finish to dismiss the window.

10. Open a new terminal window.

11. Paste in the command - ollama run llama3.2 - to install the llama3.2 model and hit return. The model will begin to download. Depending on your network speed, this may take a few minutes, as the size of the download is roughly 2GB.

12. From the >>> prompt, enter any question that you want to ask the model. For example: what does llm stand for?

Ollama is now up and running with the Llama 3.2 LLM. This is the same exact model that you may have interacted with online, but it’s running locally on your machine and is completely free!

Feel free to play around. When you want to exit the interactive mode, type /bye and hit return.

Managing Ollama

Since we “ran” a model, Ollama will check to see if it has the latest model, pull it down if not, and then run the model. You can check to see if it’s running with the following command: ollama ps

If we wanted to stop this model, we can use the following command:
ollama stop llama3.2

This will stop the model, but Ollama will technically still be running. To completely quit Ollama, select the Ollama icon in the menubar and select Quit Ollama.

This will stop all models, as well as any of the Ollama background processes.

Ollama as a Service

While this is all well and good, it’s really not much different from interacting with a LLM via a web site. In fact, if we wanted to go that direction, we could install Open WebUI and get a very familiar looking interface.

But that’s not what we’re after. We want to be able to use this LLM in APEX to drive the APEX Assistant as well as the APEX_AI API. To do that, it may make more sense to run the LLM as a service.

1. Open a new terminal window and run the following command: ollama serve

2. Open another new terminal window and copy & paste the following command:

curl --request POST \
  --url http://localhost:11434/api/chat \
  --header 'content-type: application/json' \
  --data '{
  "model": "llama3.2",
  "messages": [
    { "role": "user", "content": "who was the first president?" }
  ],
  "stream": false
}'

The results should look similar to the following:

{
  "model": "llama3.2",
  "created_at": "2024-12-05T04:03:00.706654Z",
  "message": {
    "role": "assistant",
    "content": "The first President of the United States was 
                George Washington. He served two terms in office 
                from April 30, 1789, to March 4, 1797."
  },
  "done_reason": "stop",
  "done": true,
  "total_duration": 1633274834,
  "load_duration": 18144875,
  "prompt_eval_count": 31,
  "prompt_eval_duration": 667000000,
  "eval_count": 36,
  "eval_duration": 946000000
}

Note that the content line contains the answer from the LLM. Thus, the Ollama service is up and running.

Given that we want to reach out to this service from a Podman container, we can’t use localhost, as that would translate to the container itself. Thus, we need to refer to the service on the IP address of the local machine - i.e. your local IP address.

To find out your local IP on Mac:

3. Open System Settings > WiFi > Details.

4. From there, either scroll down or select TCP/IP to see the IP address of your local machine. Note this address, as we will need it in the next step.

5. Next, copy the below command, replacing [your IP address] with you local machine’s IP address and run it:

curl --request POST \
  --url http://[your IP address]:11434/api/chat \
  --header 'content-type: application/json' \
  --data '{
  "model": "llama3.2",
  "messages": [
    { "role": "user", "content": "who was the first president?" }
  ],
  "stream": false
}'

You should get the same or very similar result as you did before.

If all is well, then we’re ready to hook up the LLM to APEX.

Troubleshooting

In some cases, you may need to run the following command on the Mac, and then stop & start Ollama:

launchctl setenv OLLAMA_HOST "0.0.0.0"

This essentially “unbinds” the Ollama service from 127.0.0.1, allowing you to use your local IP address to access it.

Configuring APEX

Integrating Ollama with APEX is done pretty much the same way as a hosted LLM, with a couple of small differences. Let’s walk through the steps.

Creating an ACE Entry

First things first, we need to create an additional ACE entry to allow the database to talk to the Ollama service.

1. Open a new terminal window.

2. Connect to the database via SQLcl as the SYS user.

3. Ensure that you’re connected to the correct PDB. In this case, it should be freepdb1.

4. Copy the below command, replacing [your IP address] with you local machine’s IP address and run it:

begin
  dbms_network_acl_admin.append_host_ace (
    host       => '[your IP address]',
    lower_port => 11434,
    upper_port => 11434,
    ace        => xs$ace_type(privilege_list => xs$name_list('connect'),
                              principal_name => 'APEX_240100',
                              principal_type => xs_acl.ptype_db));
end;
/

If the IP address of your local machine changes, you will need to create another ACE entry for each new IP address. Thus, it may be easier to use * as the hostname, as that will apply to any and all IP address and/or hostname.

Again, this idea is fine for a local development server, but not for production.

We can quickly test this via SQL Workshop:

5. Login to any APEX workspace (except INTERNAL).

6. Click on SQL Workshop.

7. Click on SQL Commands.

8. Copy the below command, replacing [your IP address] with you local machine’s IP address and run it:

declare
  l_clob clob;
begin

l_clob := apex_web_service.make_rest_request
  (
    p_url         => 'http://[your IP address]:11434/api/chat'
   ,p_http_method => 'POST'
   ,p_body        => '{ "model": "llama3.2", "messages": [ { "role": "user", "content": "who was the first president" }], "stream": false}'
  );

htp.prn(l_clob);

end;
/

If all is working, you should see something similar to the following:

Again, the results may differ slightly, but as long as there’s a JSON document that looks similar to the one above, you’re good to go.

Troubleshooting

If there’s an error here, it almost always has to do with the ACE being improperly configured or the IP address being wrong. Verify that both of these components are correct and try again.

Integrating with App Builder

Integrating our model with App Builder is done pretty much the same way as you would any other hosted LLM. The only real difference is that we’re using our local machine’s IP and the value of the API Key really doesn’t matter, but can’t be null.

Let’s get this thing integrated!

Workspace Integration

Let’s start by adding our LLM to the workspace.

1. Click the App Builder icon.

2. Click the Workspace Utilities icon.

3. Click Generative AI.

4. Click Create.

5. Set or enter the following values, replacing [your IP address] with you local machine’s IP address:

Note: The value of API Key can be anything, as it’s not needed when using local LLMs, but cannot be null.

6. Click Create.

Let’s ensure that it’s working.

7. Navigate to SQL Workshop > SQL Commands.

8. Click on the APEX Assistant button.

9. Since we may not have any tables in our schema, simply type hello and hit enter. You should see a similar response:

While this is less than helpful, it does prove that APEX is able to talk to Ollama.

Application Integration - Chat

Rather than re-invent the wheel, there’s a decent amount of content on the internet about how to build applications with APEX & AI - using chat, generation and the APEX_AI API. Now that we have our local LLM integrated, there’s nothing different that needs to happen when building APEX application that interact with AI - either via a dynamic action or API call.

Here’s a few links to get started:

• Including Generative AI in Applications

• Build AI Powered Apps with Oracle APEX

• How the new APEX AI features work

Conclusion

AI offers an unparalleled set of features that can be used as a platform to build the next generation of application on. APEX provides an ideal place to start to quickly hash out, prototype and build these solutions. The ability to pack the power of AI onto your local machine can accelerate development and save cost at the same time.

Title Photo by Chris on Unsplash

This post won’t dive into what’s possible with Database Actions, but rather walk through how to enable them on our local containerized instance of Oracle 23ai.

Enabling Database Actions

There’s really only one thing to do before we can use Database Actions. It involves REST-enabling any schema that we want to use to connect to it. This can be done via command line or via APEX.

Let’s walk through both scenarios.

REST-Enabling a Schema via SQLcl

It takes only a couple commands to REST-enable any schema in the database. But before we do that, let’s be sure we have a clean schema to walk through the steps with.

Let’s create a schema called HR.

1. Open a new terminal window.

2. Connect to the freepdb1 container as system with the following command:

sql system/oracle@localhost:1521/freepdb1

3. Run the following commands to create the new HR schema:

create user hr identified by oracle quota unlimited on users
/

grant connect, resource to hr
/

Now that we have a new schema, let’s try to connect to Database Actions.

4. Open a new browser and navigate to the following URL:
   https://localhost/ords

5. Click the Go button under the card labeled SQL Developer Web.

6. Enter HR for the Username and oracle for the Password and click Sign In. You’ll see something like this:

This is due to the fact that the HR schema has not yet been REST-enabled, which is a requirement for using Database Actions. Thus, let’s get it enabled.

The first step is to allow SYSTEM to be able to call the ORDS schema objects. We need to issue a grant for that to happen.

7. From the same terminal window, enter and run the following:

grant inherit privileges on user SYSTEM to ORDS_METADATA
/

The next and final step is to actually issue the ords.enable_schema API call.

8. Next, enter and run the following:

BEGIN
ORDS.ENABLE_SCHEMA
  (
   p_enabled => TRUE
  ,p_schema => 'HR'
  ,p_url_mapping_type => 'BASE_PATH'
  ,p_url_mapping_pattern => 'hr'
  ,p_auto_rest_auth => FALSE
  );
commit;
END;
/

One thing to note: in a production environment, it’s better to obfuscate the schema name in the p_url_mappting_pattern so as not to give away the name of the schema to a would-be hacker.

All that’s left now is to try to login to Database Actions again.

9. Switch back to the browser that was just used to try to login to Database Actions.

10. Enter HR for the Username and oracle for the Password and click Sign In. Now, you’ll see something like this:

You can now login to Database Actions as the HR user, and perform any tasks that schema has access to do.

REST-Enabling a Schema via APEX

If you already have an APEX workspace created, you can easily REST-enable your schema from APEX in just seconds. Here’s how:

1. Open a new browser and login to your workspace.

2. Click the SQL Workshop icon.

3. Click the RESTful Services icon.

4. Click Register Schema with ORDS.

5. On the popup region, de-select Install Sample Service.

6. Click Save Schema Attributes.

That’s it! To confirm it worked, simply login to Database Actions with the schema username and password that’s mapped to the workspace.

Same warning about the Schema Alias applies here - using the schema name is fine for testing, but a different name should be used for production in order to better obfuscate the actual schema name.

Integrating Database Actions with APEX

There’s one more integration that we can add to our environment - integrating Database Actions with APEX. This will add a link to Database Actions to the SQL Workshop tab in APEX, making it easy to jump from APEX to Database Actions without having to enter any credentials.

Note: On the APEX side, the older name “SQL Developer Web” is still referenced.

Let’s set that up.

1. Login to the INTERNAL workspace of APEX using the ADMIN account.

2. Click on the Manage Instance icon.

3. Click Feature Configuration.

4. In the SQL Workshop section, set Enable SQL Developer Web to Yes.

5. Click Apply Changes.

That’s all there is to it. To test, simply login to your workspace and from the SQL Workshop tab, select SQL Developer Web.

There’s a near 100% chance that you’ll need to allow popup windows for localhost. Look for a small icon in the address bar that looks like this and click on it:

Then, allow this site to open popup windows by clicking Done. The above screenshot is from Brave; other browsers will differ slightly as to how they manage popup windows.

Summary

With just a command or click, we can now unlock the power of Database Actions in our local instance. This extends the capabilities of our local environment to those who don’t need or want to use APEX alone. It is also a great complement to what APEX offers, as there are a number of useful tools in Database Actions that are simply not part of APEX.

Appendix

Increasing the jdbc.MaxLimit Parameter

In my initial testing, I found that the jdbc.MaxLimit value of 30 was not always sufficient. I kept getting errors like this one, which caused the ORDS container to occasionally crash:

503 The database user for the connection pool named |default|lo|, is not able to proxy to the schema named HR. This could be a configured restriction on the maximum number of database sessions or an authorization failure.

If you run into something similar, it’s simple to increase this value to fix the issue. I found that setting it to 50 made all my problems go away.

To change this parameter:

1. Open up a new terminal window.

2. Way back in the first post in this series, a new directory was created to store the ORDS configuration & secrets. This directory should have three subdirectories - ords_config, ords_secrets & images. Change to that directory in your terminal window.

3. Run the following command to edit the configuration file:
   vi ords_config/databases/default/pool.xml

4. Locate the line that looks like this: <entry key="jdbc.MaxLimit">30</entry>

5. Change the 30 to a 50 and save the file.

Now that the change is made, we need to restart the ORDS container.

6. From the terminal window, enter the following:
   podman stop ords

7. Next, create a new ORDS container with the following command:

 podman run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -v `pwd`/images/:/opt/oracle/apex/24.1.0/images -p 443:8181 container-registry.oracle.com/database/ords-developer:latest &

That’s it! The new container should be running with a higher limit of database sessions.

Title Photo by charlesdeluvio on Unsplash

• A container running Oracle 23ai & APEX 24.1

• A container running ORDS

• A self-signed certificate allowing secure access via ORDS

While the goal is to have a truly portable development environment, there’s some things that do need a network. One of those things that most applications will need is the ability to send emails.

APEX has always had the ability to send emails - specifically using the APEX_MAIL API. Sure, you need to point to a configured mail server, but once you have one of those, it’s trivial to configure APEX to send emails.

While we could create another container and configure something like sendmail there, that would only work if it could talk to other mail servers, and also needs the internet to function. That sounds like a lot of work.

Instead, since we need the internet to send email, let’s just point to an existing internet-based email service instead. In this case, we’ll use the Oracle Email Delivery service as part of the “Always Free” tier on OCI.

If you haven’t created your own free tier by now, you ought to check it out. While it does ask for a credit card while signing up, as long as you stick to the “Always Free” resources, you should not be charged anything. I’ve been using it since 2019 and have paid $0.

Oracle’s Email Delivery service is included in the Always Free tier, meaning that you can use it anytime you like for as long as you like for free. There is a limitation of 100 emails per day, however. For most developers, this is likely an acceptable limit. If you need to send more than 100 per day, you can upgrade your free tier to a regular tenancy, where you will get your first 3,000 emails for free and then pay 8.5 cents per 1,000 additional messages.

Email Configuration Overview

There’s three parts to configuring the Email Delivery service. The configuration is split across OCI, the Oracle Database and Oracle APEX. Let’s walk through each of them.

Steps for OCI

To configure the Email Delivery service, you’ll need administrator-level access to your OCI tenancy. If you’re using the Always Free tier, the account that you typically use to manage things should suffice.

Login to the OCI Console

To login to the OCI Console:

1. Navigate to https://cloud.oracle.com

2. Enter your Cloud Account Name and click Next. This is also the name of your tenancy that you created when you signed up for the Free Tier.

3. Select an Identity Domain and click Next. Typically, this is set to Default.

4. Enter your Username and Password and click Sign In.

5. Allow the login event to occur using Oracle Mobile Authenticator.

You should now see the main page of the OCI Console:

Note: Some tenancies have an upgraded version of the OCI Console home page. Navigation will be slightly different if that is the case.

Create a Group

To start, let’s create a Group. This should be in the same domain that you want to create the user in. Groups are similar to database roles. They are nothing more than a container used to associate users and privileges. Like database roles, Groups can be named anything at all, but won’t inherit any specific privileges until explicitly granted.

To create a Group:

1. From the main menu, select Identity & Security. When the next window appears, under the Identity section, select Domains.

2. On the next screen, choose the Compartment that you want to create all of these resources in. It doesn’t really matter which one you use, as long as you keep them all in the same one.

3. Select the Domain that you want to create the Group in. To keep things simple, we’ll simply use the Default domain, which is also the current one.

4. Click on the Groups tab to see all current Groups.

5. Click Create group.

6. Enter approvedSenders for the Name and Description and click Create.

We now have a new Group. We’ll map this group to the user we create in just a bit.

Create a Policy

Next, we need to create a Policy.

Policies are similar to database privileges. A user that has a policy granted to them will inherit the specific resources referred to in the policy.

Unlike database privileges, policies use their own vernacular when creating them. This post won’t get into the specifics, but you can read more about policy syntax here.

Let’s create a policy to allow our group to send email.

1. Use the Breadcrumbs at the top of the page and click on Domains.

2. Click the Policies tab and then click Create Policy.

3. Enter approvedSenders for the Name and Description, select your Compartment, and then click on Show manual editor.

4. When the text area appears, enter the following text:

Allow group approvedSenders to use approved-senders in compartment <Compartment Name>

Be sure to replace <Compartment Name> with the name of your compartment.

6. Click Create.

Create a User

Next, we need to create a user that will be allowed to send emails. The email address of this user will need to be set in APEX as the designated sender, and only this email will be allowed to perform that role.

1. Click on the Domains tab and select the domain that you created the Group in earlier.

2. Click on the Users tab and click Create user.

3. Enter Email for the First name, Manager for the Last name, and the email address that you want to send from for the Username / Email.
   Note: you can use any email address here. This will be the address in the From field of all emails sent, so choose wisely.

4. Make sure the Use the email address as the username is checked.

5. In the Groups section, be sure to check approvedSenders.

6. Click Create.

Next, we want to remove unnecessary capabilities from this user, since all they will really need to do is store the SMTP credentials.

7. Edit the new user.

8. Click Edit user capabilities.

9. Uncheck all options except SMTP credentials.

10. Click Save changes.

Create SMTP Credentials

Next, we need to create a set of SMTP credentials and associate them with this user. These credentials will also need to be added to APEX and serve as the username and password to access the Email Delivery service with.

1. In the Resources section, select SMTP credentials.

2. Click Generate credentials.

3. Enter SMTP credentials for the Description and click Generate credentials.

On the next screen, it will display the SMTP Username and Password.

4. Copy both the Username and Password to somewhere that you can refer to them later.

Note: This will be the ONLY time you can copy the password, so be sure to copy it before closing this window.

Add Approved Sender

Next, let’s add the email address of the user we just created to the list of Approved Senders. This is the final link that will allow us to send emails from APEX & PL/SQL applications.

1. From the main menu, select Developer Services. When the next window appears, under the Application Integration section, select Email Delivery.

2. Be sure that the correct Compartment is selected.

3. Click the Approved Senders tab.

4. Click Create Approved Sender.

5. Enter the email address of the user that was just created and click Create Approved Sender.

Copy Email Delivery Endpoint

One last bit of information we’re going to need is the SMTP Public Endpoint. This is essentially the address of the Email Delivery service that we will need to add to APEX in just a bit.

To get the SMTP Public Endpoint:

1. Click on the Configuration tab.

2. Under the SMTP Sending Information region, record the value of the Public Endpoint and SMTP Ports. We will need to add this to APEX in the next section.

That concludes the steps that need to be performed in the OCI Console.

Steps for APEX

Now that we have the underlying components configured, all we need to do in APEX is enter them in the corresponding fields in the Instance Administration application.

1. Login to the INTERNAL workspace as the ADMIN user in APEX.

2. Click on Manage Instance.

3. Click on Instance Settings.

4. In the Email section, enter the following values:

Note that most values will need to be replaced with the ones derived in earlier steps.

5. Click Apply Changes.

Since we’re configuring this at the instance level, these settings will apply to all workspaces in the instance of APEX. They can be overridden by passing in new values to the APEX_MAIL API.

Steps for the Oracle Database

There’s one more step at the database level that needs to be performed. We need to create an ACE (access control entry) so that APEX can call the Email Delivery endpoint.

1. Connect to the database via SQLcl as the SYS user.

2. Ensure that you’re connected to the correct PDB. In this case, it should be freepdb1.

3. Run the following SQL statement:

begin
  dbms_network_acl_admin.append_host_ace (
    host       => 'smtp.email.us-ashburn-1.oci.oraclecloud.com',
    lower_port => 587,
    upper_port => 587,
    ace        => xs$ace_type(privilege_list => xs$name_list('connect'),
                              principal_name => 'APEX_240100',
                              principal_type => xs_acl.ptype_db));
end;
/

Note: you may need to change the value of the host parameter, based on what your SMTP Public Endpoint is.

That’s it! All three parts - OCI, APEX & Oracle Database - are all configured to send email from your local instance via the Email Delivery service!

Testing It All Out

Now that everything is configured, let’s test it out. To do this, all you will need is an APEX workspace on your local development environment. Any workspace aside from INTERNAL will do.

1. Login to any workspace (aside from INTERNAL) on your local APEX environment.

2. Click on SQL Workshop.

3. Click on SQL Commands.

4. Enter the following SQL:

begin

-- send a message
apex_mail.send
  (
   p_from => '<email address of user created>'  -- replace this value
  ,p_to   => '<your email address>'             -- replace this value
  ,p_subj => 'Test Email Message'
  ,p_body => 'This is a test email message sent via OCI Email Delivery'
  );

-- push the email queue now
apex_mail.push_queue; 

end; 
/

5. Be sure to replace the p_from & p_to parameters with the email address that was created for the user and any email address that you have access to, respectively.

6. Run the SQL.

If everything works, you will receive an email with the above subject & body in just a few seconds.

In the case that you don’t receive an email, check the view APEX_MAIL_QUEUE - specifically the column MAIL_SEND_ERROR - for more information.

Summary

Our little development environment leveled up once again, and can now send email messages thanks to the OCI Email Delivery service. With just a few steps, we were able to create a user, group, policy, SMTP credential and then map all of that to our APEX instance. This is just another example of just how well you can extend the capabilities of APEX with a variety of OCI services.

Best of all - all of this can be done at no cost using the OCI Free Tier!

Title Photo by Ethan Hoover on Unsplash

While the main difference is that HTTPS will encrypt data in transit and HTTP will not, there’s another subtle one that’s also important. HTTPS pages will not allow Javascript to be called from HTTP-only URLs. Thus, if you don’t use HTTPS, this issue would not rear its ugly head until you deployed to production.

Creating & Installing the Certificate

It only takes a few minutes to get up and running with your own, trusted, self-signed certificate. The initial first few steps work for both Mac & Windows. Pay attention at the end, as adding the self-signed certificate as trusted varies across platforms. I’ve added a section for each OS.

Creating the Certificate

Let’s start by creating our self-signed certificate.

1. Open a new terminal window

2. Navigate to the ords_config directory. This was set up as part of my previous post here.

3. Create a new directory called ssl.

4. Navigate to the ssl directory.

5. Run the following command:

    openssl req -x509 -out cert.crt -keyout key.key -days 9999 \
      -newkey rsa:2048 -nodes -sha256 \
      -subj '/CN=localhost' -extensions EXT -config <( \
       printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
   

Some notes about this command:

• The bulk of this command was taken from this page: https://letsencrypt.org/docs/certificates-for-localhost/

• I set days = 9999 because I don’t want to be bothered to re-create this certificate. Ever.

• The name of the certificate pair - cert.crt & key.key - are what the ORDS container will look for, so don’t change them.

6. Upon running this command, you should have two files in the ssl directory:

   

Installing the Certificate

A simple restart of the ORDS container is all we need to switch over from HTTP to HTTPS.

Remember what I said about that non-standard port? Let’s change that to 443, so that we don’t need to put a port number in the URL at all.

1. Terminate your existing ORDS container.

2. Using this new command, restart the ORDS container:

    podman run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -v `pwd`/images/:/opt/oracle/apex/24.1.0/images -p 443:8181 container-registry.oracle.com/database/ords-developer:latest &
   

This command has one additional argument in it: -p 443:8181 That additional attribute will redirect port 8181 from the container to your local port 443.

As keen readers may have noticed, I’ve saved this command to a local file called start_ords. This way, I can just run that file to restart my container vs. sorting through my blog to find the command syntax.

Testing the Certificate

Let’s see what happens now what we try to access our ORDS container.

1. Open up a new browser window and enter the following URL: https://localhost

As expected, you should see the “Your connection is not private” error. This is because the certificate is self-signed, and the browser cannot associate it with one of it’s CAs.

You can click “Advanced” and then Proceed to localhost (unsafe), but that gets annoying pretty quickly.

Trusting the Certificate

While theres a number of ways to fix this issue, the quickest one that I have come by is to tell your local machine to simply “trust” this self-signed certificate as if it were signed by a legitimate CA. This takes just seconds, and agains, since this is a local development environment, is a perfectly secure approach to take.

Trusting the certificate will vary, depending on your local OS.

MacOS

To trust a self-signed certificate on Mac OS, we simply need to add the certificate to the MacOS Keychain.

1. Launch the application called Keychain Access.

2. Enter your credentials.

You should now see a window similar to this:

3. Using the Finder, navigate to the folder where you placed the certificates that you created earlier. It should be in /ords_config/ssl.

4. Drag the file cert.crt to the “striped” part of the Keychain Access window (under the column headings). You should see the following popup window:

   

5. Select Add.

6. On the main Keychain Access window, search for localhost. You should see a single entry:

   

7. Double-click the localhost entry.

8. Expand the Trust region.

9. Set When using this certificate to Always Trust. All other options should automatically change to Always Trust as well.

   

10. Close the localhost window. You will need to re-enter your credentials for the changes to take effect.

At this point, your local OS will trust our self-signed localhost certificate as if it were valid. You will no longer see the “Not Secure” message, either. Again, fine for development, not really a great idea for production systems.

We can prove this by reloading our browser that was pointed to https://localhost.

The results should look like this:

Windows

On Windows, you need to take similar steps to allow the OS to trust the self-signed certificate.

I did some searching, and this post seems to have a decent set of steps to do this. I did not have the chance to try this out, so please leave a comment if it doesn’t work or you have a better set of steps to use on Windows.

Summary

Even though it’s a local development environment, it’s important to try to mirror what’s on production as much as possible - including the protocol used to access APEX. It doesn’t take much work to create and install your own certificates into the ORDS container, ensuring that all web applications are accessed via HTTPS.

Title Photo by Fer Troulik on Unsplash

I didn’t really notice this, but the version of APEX that I downloaded was 24.1.0. Thus, I’m six patch sets behind what’s current as of the publish date of this post.

Remember: APEX patches typically contain two parts:

• Database objects

• Images / Javascript files / CSS files

Container Differences

In the world of containers, things are a little different - especially with the ORDS Developer container. Looking into how it’s setup, when ORDS starts, it points to a specific location in the container for the APEX images. And that path is somewhat hard-coded.

Here’s the the two commands that run when ORDS starts up:

APEXI=/opt/oracle/apex/$APEX_VER/images

ords --config $ORDS_CONF_DIR serve --port 8181 --apex-images $APEXI

$APEX_VER gets translated into 24.1.0 in this case, so the APEX images directory becomes /opt/oracle/apex/24.1.0/images. Since this is in the container’s filesystem, there’s no easy way to make updates to the images in there and have it persist.

Verifying an APEX Release

To figure out which release of APEX you’re running, you’re going to need to do one of two things, depending on whether you’re looking at the database objects or the “images” directory.

I use “images” lightly here, as most of what APEX relies on these days are Javascript and CSS files. Looking at some of the images that are included, they date back to HTML DB 1.5, where tabs were constructed by assigning images to <td> tags in an HTML table. Good times!

APEX Database Objects Version

The name of the schema is an obvious tell here - APEX_240100 is clearly APEX 24.1. But it gives you no clue as to the patch sets that have been applied. To get that, we have to run the following:

select version from dba_registry where comp_id = 'APEX';

This will return a more specific version of APEX, like below:

APEX “images” Files Version

Hidden in the root directory of the APEX images directory is a file called apex_version.js. The contents of this file are simple:

var gApexVersion = “24.1.0”;

This will always have store the three-digit version of the APEX images directory.

If you don’t have access to the filesystem, simply enter the following URL to see this file’s contents in a browser:

https://servername.com/i/apex_version.js

Upgrading All the Things

So it’s obvious we’re running APEX 24.1.0, and need to upgrade to 24.1.6 - the most current release at the time this was written.

The database side is pretty straightforward - run the patch as SYS and you’re done.

The filesystem part is a little more involved. Since we can’t modify anything in the container, we need to host the files outside of the container. My first thought was to use the APEX CDN point to the proper version. That is a viable solution, so as long as you have network access to the CDN. Since one of the goals here was to have a portable development system that did not rely on the internet, I had to come up with something else.

We can host the APEX image directory locally, and when we run the ORDS container, we can add a parameter to map the directory that the container uses (/opt/oracle/apex/24.1.0/images) to our local directory - which we will then upgrade to 24.1.6.

Let’s walk through the steps do to this.

Download and Stage the APEX Images Directory

First of all, we need to download the APEX 24.1.0 images directory. This can be found in any distribution of APEX itself.

You can find and download all versions of APEX here:

https://www.oracle.com/tools/downloads/apex-downloads/

In this case, I simply downloaded and unzipped the English-language only version.

Next, we need a place to stage these files that is relatively permanent. I chose to move the whole images directory to the same top-level directory that I used to store my ORDS configuration and secrets. Here’s what it looks like in the filesystem:

I simply copied the images folder from the patch directory to my custom directory by dragging it via the Finder; you can move it any way you like.

Restart the ORDS Container

Now that we have our custom images directory in place, let’s use a slightly different command to create a new ORDS container. This command contains an additional volume mapping that will use our images directory in place of the one in the container.

1. Terminate your existing ORDS container via Podman

2. Open a new terminal window

3. Change directories to the directory that contains your images, ords_config and ords_secrets directories

4. Run the following command:

    podman run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -v `pwd`/images/:/opt/oracle/apex/24.1.0/images -p 8181:8181 container-registry.oracle.com/database/ords-developer:latest &
   

This additional volume mapping - -v `pwd`/images/:/opt/oracle/apex/24.1.0/images - will point the container images directory at our local directory - which right now should have identical contents.

From now on, this is the command that you want to use when re-launching ORDS containers.

Confirm the Directory Mapping

Let’s confirm that the change worked.

1. Open a new browser.

2. Enter the following URL, replacing servername.com with your hostname:

   https://servername.com/i/apex_version.js

If successful, you will still see this text:

var gApexVersion = “24.1.0”;

Download and Install the Patch

Now that we have the volume mapped, we will need to download and install the patch for APEX 24.1.6. This patch can only be downloaded from Oracle Support with a valid account. For reference, the patch number is 36695709.

Once you have downloaded and unzipped the patch, follow the instructions in the README.txt file to install the database side of the patch. This should take no more than a few minutes.

When you get to Step 7 of the patch, follow the instructions with the assumption that the /images directory on the APEX server is the one that you’re hosting on your local machine.

In my case, this was the command that I ran from within the main patch directory:

cp -rp images ~/Podman/freepdb1/

Verify the Patch

Now that the patch is applied, let’s check both places to ensure that it was successful.

First, the filesystem:

1. Open a new browser.

2. Enter the following URL, replacing servername.com with your hostname:

   https://servername.com/i/apex_version.js

If successful, you will still see this text:

var gApexVersion = “24.1.6”;

Next, the database:

3. Open a new terminal window and connect to your database a SYS

4. Run the following command:

   select version from dba_registry where comp_id = 'APEX';

You should see the following:

Summary

Congratulations! Your container database is now running APEX 24.1.6, and your ORDS container is using your local directory to provide the correct files for that release.

You should be able to stop & start the ORDS container as often as you need using the command referenced in the Restart the ORDS Container section.

One thing to keep in mind is that you no longer need to create a conn_string.txt file to start to the ORDS container. In fact, if you do, you will get an APEX version mis-match error.

And lastly - just another reminder that the database running in your container is volatile. If you delete the container, you delete the database, too. You will then need to create a new container from the Oracle 23ai image, install APEX, upgrade to 24.1.6, etc. to restore your configuration.

Title Photo by Amira El Pohail on Unsplash

Having a local development instance offers a lot of benefits. It’s fast, it works from anywhere - with or without the internet - and you can configure it any which way you want. It’s also typically free to use, since most vendors - including Oracle - provide versions of their software at no cost for developers.

I find this very useful as a way to test out upgrades or ideas quickly, as well as a backup system that I can use for demonstrations in the case of an issue with my cloud databases.

In the old times, this would involve installing Oracle directly onto your laptop and configuring and managing it there. This was messy, and often conflicted with other software, creating a configuration nightmare. With today’s enterprise management tools, it may not even be possible to do it this way on your work machine.

Enter containers. Containers are portable, self-contained “units” that contain all of the things that an application needs to run. They make moving applications across environments a lot easier, as all of the dependencies are already included. There’s a ton of information on containers elsewhere; having some basic knowledge about containers may make this post a little easier to understand, but is not required.

Building the Environment

To build a containerized APEX environment, we will need two containers - one for the database and one for ORDS. We can visit the Oracle Container Registry and grab pre-packaged containers for each.

Before we get started, we need to prepare our local machine. While Docker is the most popular container management software, it’s not the only one. There are several alternatives, such as Podman & Rancher. This post will make use of Podman - mostly because it’s the standard at Oracle and installing Docker is typically not permitted.

Be Persistent

A note about persistence and containers. A container will typically keep its filesystem intact when it’s stopped. However, if the container is deleted, then the filesystem usually goes with it.

Of course there are ways around this, but this post won’t get into that. Thus, if you end up deleting the Oracle Database container, your database gets deleted, too. It’s best to ensure that all of your code, seed scripts and anything else that lives in the database is stored in script files that are managed in a version control system.

In the case of the ORDS container, persisting the filesystem doesn’t really matter since we inject local configuration information into that container each time it starts.

Download & Install Podman

First, we’ll need to download and install Podman.

Podman is an open source alternative to Docker. Most Docker commands work just fine with Podman.

1. Navigate to https://podman.io/

2. Click Download

3. Select Podman Desktop for your OS

4. Once downloaded, install and start up Podman. You should see a screen that looks like this:

Download the Oracle 23ai Free Container

Next, we’ll need to download the container that contains the Oracle 23ai Free Edition. This can be done either via command line or from within Podman Desktop.

1. Open Podman Desktop

2. Click the Containers icon

3. Click Create

4. Click Existing Image

5. Click Pull

6. Enter the following for Image to Pull:
   container-registry.oracle.com/database/free:latest

7. Click Pull Image

The container will start to download. Depending on your network speed, it will take a few minutes for this to complete.

Once it’s completed, it should look like this:

Click Done to complete this section.

Start & Configure the Oracle 23ai Container

Now that we have the container downloaded, let’s start it up.

1. Open a new terminal window

2. Enter the following command:

    podman run --name oracle --ip 10.88.0.2 -p 1521:1521 container-registry.oracle.com/database/free &
   

This will create a new container called oracle and set the IP address to 10.88.0.2. This is important, since the wallet will bind to the IP address, and having it change after each reboot will get annoying. It will also map port 1521 to local 1521, so that your muscle memory will work when typing connection strings.

3. Switch to Podman to verify that it worked. You should see a single entry in the Containers tab for oracle.

Here’s the cool part - in just a few seconds - yes, seconds - we were able to spin up a fully-functional Oracle 23ai database.

Don’t believe me? Click on Actions > Open Terminal tab and run the following SQL:

sqlplus / as sysdba

While we have the Terminal open, let’s change the password of SYS & SYSTEM, so that we can connect from outside of Podman.

To do this

1. Log out of SQL*Plus, if you’re still logged in

2. Run the following command in the Terminal:

   ./setPassword oracle

In the above example, the password was set to “oracle”, but you can use anything that you want.

Now, you should be able to connect to this container from outside of Podman. Let’s try to connect with SQLcl.

1. Open a new terminal from your local machine and enter the following:

sql sys@localhost:1521/freepdb1 as sysdba

2. Enter the password that you just set, and you should be connected to the FREEPDB1 PDB, as shown below:

Download & Install APEX

To install APEX manually, follow these steps.

1. Download APEX from https://www.oracle.com/tools/downloads/apex-downloads/

2. Unzip the downloaded file to your local machine.

3. Open up a new terminal and change directories to the /apex directory.

4. Connect to the container database as SYS. You can use the following command to do so: sql sys/oracle@localhost:1521/freepdb1 as sysdba

It’s a good idea to create a dedicated tablespace for APEX. This keeps it separate from other schemas.

5. Create a new tablespace with the following command:
   create tablespace apex datafile 'apex_001.dbf' size 300m autoextend on;

Now that we have our tablespace created, we’re ready to install APEX.

6. Install APEX with the following command:
   @apexins apex apex temp /i/

This step will likely take a few minutes to complete, depending on your local machine’s specifications.

Once completed, there’s two more administrative tasks we need to do. First, we need to unlock the APEX_PUBLIC_USER account. This is needed for ORDS to properly connect to the database.

7. To unlock APEX_PUBLIC_USER, run the following command:
   alter user apex_public_user account unlock;

Lastly, let’s reset the APEX administrator account so we will be able to login to the Internal workspace once ORDS is up and running.

8. Run the following command and follow the prompts.

   @apxchpwd

Take the default values for the username and email. You will need to create a somewhat complex password that has at least 1 uppercase character, 1 number and 1 special character. This will be the password that you use to login to the ADMIN user in the INTERNAL workspace.

Here’s an example of what the output should look like:

The APEX database schemas & objects should now be successfully installed in your container database.

Download, Start & Configure the ORDS Container

This next step is pretty cool, as it will do the following:

• Download the ORDS container

• Configure the connection string in ORDS

• Connect to your container database

• Install and configure ORDS in the database

• Install and configure APEX in the database

• Start the ORDS Jetty listener so you can connect to APEX

Before we do this, there’s a couple pre-requisites that need to be completed. We need to create a pair of local directories and add a configuration file so that ORDS knows where to connect to.

Determine the IP of the Database Container

For ORDS to connect to the database, we’ll need to get the IP address of the container database. This is the IP address that containers use to talk to each other, not what we use to connect to it from our local machine.

1. Open up a new local terminal

2. Enter the following command:
   podman inspect oracle | grep IPAddress

3. Note the value of IPAddress, as that will be needed in the next step.

Create the Directories & Files

Next, we need to create a pair of directories and a file on our local machine. This file will be used to seed ORDS with the connect information so that it can connect to the container database.

1. Open up a new local terminal

2. Change directories to where you want to store the connect information for your container database. This should be somewhere relatively permanent on your local machine, as you will need to refer to this configuration data to restart the ORDS container from time to time.

3. Run the following commands:
   mkdir ords_secrets ords_config
chmod 777 ords_config

4. Next, run the following command, replacing [database container IP] with the IP address of the database container from the previous section :
   echo 'CONN_STRING=sys/oracle@[database container IP]:1521/freepdb1' > ords_secrets/conn_string.txt

This file will be deleted once the ORDS container is started, so there is little risk for the password being discovered.

Install and Run ORDS Container

Now that everything is in place, let’s start the ORDS container. From the same terminal where you just ran the last commands, enter and run the following command:

podman run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords-developer:latest &

This will run for about a minute. Once the screen looks similar to this, it should be ready to test:

Looking at the Containers tab in Podman, we can see that our ords container is up and running:

Connecting to APEX

If all went well, we should be able to connect to the Oracle REST Data Services landing page.

1. Open up a new browser

2. Navigate to the following URL: http://localhost:8181

You should see the following page:

3. Click on the “Go” button under the Oracle APEX region.

4. Enter internal for Workspace, admin for Username and the password that you set in the previous section via the @apxchpwd script for Password and click Sign In.

Congratulations! You can now start to create workspaces and do anything else that’s possible with Oracle APEX.

Also - it’s OK to close the terminal that started the ORDS container at this point. The ORDS container will continue to run until it’s terminated manually.

Summary

Building a local instance offers many benefits to both casual and professional developers. It provides a place to learn new things, test existing ones and even build real software. With complete control and no cost, developers can spin these up and down all day long, and owe nothing to anyone.

Mac users have especially been waiting a while for a near-native Oracle Database, and with this new container and Podman, the wait is finally over.

References

I referred to a few different sites for guidance when writing up this blog. They are:

• Oracle Database 23ai Free Edition Container

  https://container-registry.oracle.com/ords/ocr/ba/database/free

• Oracle RESTful Data Services Developer Container

  https://container-registry.oracle.com/ords/ocr/ba/database/ords-developer

• Launch your ORACLE APEX Instance in a Docker Container

  https://medium.com/@hamzaeraoui2000/lunch-your-oracle-apex-in-a-docker-container-22a16e27a6b3

Title Photo by OSG Containers on Unsplash

Fortunately, the fix is pretty simple. Use this view instead of the one mentioned in the post, and it should still work:

create or replace view blog_v
as
with json as
  (
  select
    apex_web_service.make_rest_request
      (
       p_url=> 'https://gql.hashnode.com'
      ,p_http_method => 'POST'
      ,p_body => '{ "query" : "query Publication '
      || '          { publication(host: \"spendolini.blog\") '
      || '            { id title posts(first: 10) '
      || '              { edges '
      || '                { node '
      || '                  { id title subtitle url slug brief publishedAt reactionCount responseCount content { markdown } coverImage { url } '
      || '                  } '
      || '                } totalDocuments '
      || '              } '
      || '            } '
      || '          }" '
      || '        }'
      ) as val
  from
    dual
  )
select
   t.id
  ,to_timestamp(t.date_added, 'YYYY-MM-DD"T"HH24:MI:SS.FF"Z"') as date_added
  ,t.slug
  ,'https://spendolini.blog/' || t.slug as url
  ,t.title
  ,t.brief
  ,t.cover_image
  ,t.popularity
  ,t.total_reactions
  ,t.content
from
  json,
  json_table
    (
      json.val
     ,'$.data.publication.posts.edges.node[*]'
    columns
      (
       id              varchar2(1000) path '$.id'
      ,slug            varchar2(1000) path '$.slug'
      ,title           varchar2(1000) path '$.title'
      ,brief           varchar2(1000) path '$.brief'
      ,cover_image     varchar2(1000) path '$.coverImage.url'
      ,date_added      varchar2(1000) path '$.publishedAt'
      ,popularity      number         path '$.popularity'
      ,total_reactions number         path '$.reactionCount'
      ,content         clob           path '$.content.markdown'
      )
    ) as t;

There’s also a new GraphQL Playground for Hashnode’s APIs that’s worth checking out.

Title Photo by David Kemptner-Rauscher on Unsplash

So where are they going? It sure seems like Bluesky is the destination. In the last couple of weeks, there have been over 1 million new accounts created there per day. Check out this site to see the specifics.

A portion of these millions of digital refugees are from the Oracle community. And form the discussions that have already happened on Bluesky, we are all overjoyed by the refreshing aura of our new home. There’s no ads, bots, trolls or anything else to get in the way of meaningful, spirited and even fun discussions. Just like Twitter used to be a long time ago.

Starter Packs

If you’re ready to make the jump, check out some of these Starter Packs. A Starter Pack is a curated list of people that you can follow with a single click. This makes it easy to populate your feed in just seconds - something that typically takes time and effort on any social platform.

Here’s a list of a few to get you started:

• Oracle APEX Starter Pack

• Oracle ACE Members

• Oracle Database Product Managers

• Oracle Folk

You can use any or all of them once you create an account. In fact, if you don’t have an account, just click any of the links and it will walk you through the process of creating one and adding that Starter Pack!

A New Hope

With better blocking and moderation tools, Bluesky seems to be the new place to be. Whether it’s for Oracle or any other interest, the tone of the conversation is refreshingly decent, and those who try to disrupt this can quickly and easily be ignored. And yes, of course Mark Hamill already has an account there!

Follow me on Bluesky

Title Photo by Çağlar Oskay on Unsplash