While testing NL2IR and the built-in Token Limit, I kept hitting this message:

"An unexpected error occurred." Not very helpful.

I looked at the AI response handler, tried a few things, and eventually gave up. I assumed there was some internal code that displays this whenever anything goes wrong during the LLM processing chain. Nothing can be done. Maybe a future release will add customization options.

Oh how wrong I was. This is APEX - everything is standardized. What we are seeing here is just an ORA error, specifically ORA-20962 with the APEX error code APEX.AI.ERROR. And ORA errors in APEX can be handled with the standard error handling function.

Reproducing the error

Set up a service that will fail immediately:

The important part is Maximum AI Token Limit - set it to 0.

Now go to Edit Application Definition → AI and assign this service.

Now all NL2IR and Assistant features in this app will fail with the "unexpected error" message. But it is not unexpected, and it is not really an error - it is a token limit check doing exactly what it should. So how do we give the user a proper message?

The fix

Create an error handling function:

create or replace function log_apex_error(
    p_error in apex_error.t_error
) return apex_error.t_error_result
as
    l_result apex_error.t_error_result;
begin
    l_result := apex_error.init_error_result(p_error => p_error);

    -- Handle AI token limit error with a user-friendly message
    if p_error.ora_sqlcode = -20962
       and p_error.apex_error_code = 'APEX.AI.ERROR'
    then
        l_result.message          := 'You have exceeded your available AI tokens. Please contact your administrator.';
        l_result.display_location := apex_error.c_inline_in_notification;
    end if;

    return l_result;
end log_apex_error;
/

The function hooks into the standard APEX error pipeline. It only modifies the message for that specific ORA code and passes everything else through unchanged.

Now add it to Edit Application Definition → Error Handling → Error Handling Function:

And that is it.

I actually figured this out during an APEX Office Hours session - someone else asked a related question and it clicked. If you are not joining those sessions, you should. Half the time the best insights come from other people's problems.

The same pattern works for any AI-related ORA error APEX might throw. If Oracle adds new error codes for other AI limit scenarios, you just add another condition to the same function.

When I looked at the requests going out for NL2IR, a normal call was around 17k tokens. The important part is that roughly 15k of those tokens are not really changing between calls. So if we can cache that stable part of the prompt, we stop paying full price for it every single time.

That is exactly what this post is about.

We are going to route NL2IR to a dedicated Anthropic service, enable prompt caching on the static part of the prompt, and use a request handler package to move the variable structured-data section out of the system prompt.

One important thing up front: this specific implementation is for Anthropic.

The high-level idea can work with other providers too, but not in exactly the same way. This version depends on Anthropic prompt caching and on being able to shape the request so that Anthropic sees a stable prefix it can reuse.

What we will build:

• A dedicated AI service for NL2IR

• A static system prompt stored in the service Additional Parameters

• Anthropic prompt caching enabled on that static prompt

• A request handler package that rewrites the NL2IR request into a cache-friendlier shape

The result is that after the first request pays the initial cost, the vast majority of the prompt gets cached and reused on every subsequent call. In practice, that means every NL2IR call across your reports can benefit from the same cache.

What Anthropic prompt caching actually does

If you have not used Anthropic prompt caching before, the short version is simple: Anthropic can cache an identical prompt prefix and reuse it on follow-up calls.

So instead of sending the same big static prompt over and over again at full price, you pay once to write it into cache, and then the next requests can read that cached prefix much more cheaply.

The important part is this: the cached prefix must stay identical.

If the stable part of the prompt keeps changing, you will keep missing the cache and you will not save much. By default, the cache lives for 5 minutes, which is perfectly fine for a feature like NL2IR where users often try several queries one after another.

There is also an option to extend it to 1 hour, although you pay a little bit more, if you expect your usage patterns to be more sporadic.

If you want the full details, Anthropic has a good prompt caching guide here: https://platform.claude.com/docs/en/build-with-claude/prompt-caching

That is why prompt shape matters here.

Why NL2IR is a good candidate for caching

NL2IR sends a lot of prompt data. And most of that prompt is not the user question.

The user might type something short like:

show me orders from last month

But the request also contains a large system prompt, instructions, metadata, and structured information about the report. That is where the token cost really comes from.

In my tests, the static portion of the instructions made up almost 90% of that massive payload.

That makes NL2IR a very good fit for prompt caching, as long as we can keep the reusable part stable.

The problem with the default prompt shape

The problem is that the APEX-generated system prompt does not contain only the static instructions we want to cache.

It also contains a ## Structured Data section. That section is the variable part we do not want glued into the static prefix.

So if we just cache the raw system prompt as-is, we are not really controlling the prompt shape. What we want instead is:

• Keep the static instructions in one place

• Move the structured data out of that static prompt

• Keep the final request stable enough for Anthropic caching to do useful work

That is what the package below does.

Step 1: Create a dedicated NL2IR service

Just like in my previous NL2IR post, create a dedicated AI service for Natural Language to IR.

I am using Anthropic and routing NL2IR to a cheaper model. The exact model is up to you, but NL2IR is a very good place to use a lower-cost model because the input is huge and the output is usually small.

The important part is the static ID of the service. In my package I use:

haiku-for-ir

You can call it whatever you want, but remember to update the package if you use a different static ID.

Step 2: Put the static prompt into Additional Parameters

This time the dedicated service is not just about model routing. It is also where we keep the static system prompt and enable Anthropic prompt caching.

Wait, where do I get the static prompt?

Since APEX generates the NL2IR prompt under the hood, you need to grab it first. The easiest way is probably to add logging to the package in the next section and log p_result.request.system_prompt, or just check your provider logs. Copy that massive system prompt, delete the ## Structured Data section from it, and use the rest as your static instructions.

In the service Additional Parameters, put that static part of the NL2IR prompt and enable caching.

{
  "system": [
    {
      "type": "text",
      "cache_control": { "type": "ephemeral" },
      "text": "<system prompt>"
    }
  ]
}

The key idea is that this system prompt block should contain only the stable instructions you want Anthropic to cache.

Do not include the variable ## Structured Data section there. The package will take care of that part during request handling.

Step 3: Deploy the request handler package

Now deploy this package:

create or replace package ai_handler_cache as
  procedure ai_request (
    p_param  in            apex_ai.t_chat_request_handler_param,
    p_result in out nocopy apex_ai.t_chat_request_handler_result );
end ai_handler_cache;
/

create or replace package body ai_handler_cache as

  g_target_service_static_id constant varchar2(255) := 'haiku-for-ir';

  function get_service_id(
    p_service_static_id in varchar2
  ) return number
  as
    l_service_id number;
  begin
    select remote_server_id
      into l_service_id
      from apex_workspace_ai_services
     where upper(remote_server_static_id) = upper(p_service_static_id)
     fetch first 1 rows only;

    return l_service_id;
  end get_service_id;

  function is_interactive_report(
    p_region_id in number
  ) return boolean
  as
    l_dummy number;
  begin
    select 1
      into l_dummy
      from apex_application_page_ir
     where region_id = p_region_id
     fetch first 1 rows only;

    return true;
  exception
    when no_data_found then
      return false;
  end is_interactive_report;

  function least_positive(
    p_left  in pls_integer,
    p_right in pls_integer
  ) return pls_integer
  as
  begin
    if nvl(p_left, 0) = 0 then
      return p_right;
    elsif nvl(p_right, 0) = 0 then
      return p_left;
    else
      return least(p_left, p_right);
    end if;
  end least_positive;

  function next_top_level_heading_pos(
    p_source       in clob,
    p_search_start in pls_integer
  ) return pls_integer
  as
    l_lf_heading_pos   pls_integer;
    l_crlf_heading_pos pls_integer;
  begin
    l_lf_heading_pos := dbms_lob.instr(p_source, chr(10) || '## ', p_search_start);
    l_crlf_heading_pos := dbms_lob.instr(p_source, chr(13) || chr(10) || '## ', p_search_start);

    if l_lf_heading_pos > 0 then
      l_lf_heading_pos := l_lf_heading_pos + 1;
    end if;

    if l_crlf_heading_pos > 0 then
      l_crlf_heading_pos := l_crlf_heading_pos + 2;
    end if;

    return least_positive(l_lf_heading_pos, l_crlf_heading_pos);
  end next_top_level_heading_pos;

  function slice_clob(
    p_source in clob,
    p_start  in pls_integer,
    p_length in pls_integer
  ) return clob
  as
    l_result clob;
  begin
    if p_source is null or p_length <= 0 then
      return null;
    end if;

    dbms_lob.createtemporary(l_result, true);
    dbms_lob.copy(
      dest_lob    => l_result,
      src_lob     => p_source,
      amount      => p_length,
      dest_offset => 1,
      src_offset  => p_start );

    return l_result;
  end slice_clob;

  function extract_structured_data_section(
    p_system_prompt in clob
  ) return clob
  as
    c_heading_marker constant varchar2(20) := '## Structured Data';
    l_heading_pos      pls_integer;
    l_next_heading_pos pls_integer;
    l_section_end_pos  pls_integer;
    l_prompt_length    pls_integer;
  begin
    if p_system_prompt is null then
      return null;
    end if;

    l_heading_pos := dbms_lob.instr(p_system_prompt, c_heading_marker);
    if l_heading_pos = 0 then
      return null;
    end if;

    l_prompt_length := dbms_lob.getlength(p_system_prompt);
    l_next_heading_pos := next_top_level_heading_pos(
                            p_source       => p_system_prompt,
                            p_search_start => l_heading_pos + length(c_heading_marker) );

    if l_next_heading_pos > l_heading_pos then
      l_section_end_pos := l_next_heading_pos - 1;
    else
      l_section_end_pos := l_prompt_length;
    end if;

    return slice_clob(
             p_source => p_system_prompt,
             p_start  => l_heading_pos,
             p_length => l_section_end_pos - l_heading_pos + 1 );
  end extract_structured_data_section;

  function has_structured_data_message(
    p_messages in apex_ai.t_chat_messages
  ) return boolean
  as
    l_idx pls_integer;
  begin
    l_idx := p_messages.first;
    while l_idx is not null loop
      if p_messages(l_idx).chat_role = apex_ai.c_role_user then
        return false;
      elsif p_messages(l_idx).chat_role = apex_ai.c_role_assistant
        and p_messages(l_idx).message is not null
        and dbms_lob.instr(p_messages(l_idx).message, '## Structured Data') > 0
      then
        return true;
      end if;

      l_idx := p_messages.next(l_idx);
    end loop;

    return false;
  end has_structured_data_message;

  function assistant_message(
    p_message in clob
  ) return apex_ai.t_chat_message
  as
    l_message apex_ai.t_chat_message;
  begin
    l_message.chat_role := apex_ai.c_role_assistant;
    l_message.message_type := apex_ai.c_chat_message_type_text;
    l_message.message := p_message;
    return l_message;
  end assistant_message;

  procedure insert_assistant_message_before_first_user(
    p_messages in out nocopy apex_ai.t_chat_messages,
    p_message  in            clob
  )
  as
    l_existing_messages apex_ai.t_chat_messages := p_messages;
    l_new_messages      apex_ai.t_chat_messages;
    l_source_idx        pls_integer;
    l_target_idx        pls_integer := 0;
    l_inserted          boolean := false;
  begin
    if p_message is null then
      return;
    end if;

    l_source_idx := l_existing_messages.first;
    while l_source_idx is not null loop
      if not l_inserted and l_existing_messages(l_source_idx).chat_role = apex_ai.c_role_user then
        l_target_idx := l_target_idx + 1;
        l_new_messages(l_target_idx) := assistant_message(p_message);
        l_inserted := true;
      end if;

      l_target_idx := l_target_idx + 1;
      l_new_messages(l_target_idx) := l_existing_messages(l_source_idx);
      l_source_idx := l_existing_messages.next(l_source_idx);
    end loop;

    if not l_inserted then
      l_target_idx := l_target_idx + 1;
      l_new_messages(l_target_idx) := assistant_message(p_message);
    end if;

    p_messages := l_new_messages;
  end insert_assistant_message_before_first_user;

  procedure ai_request (
    p_param  in            apex_ai.t_chat_request_handler_param,
    p_result in out nocopy apex_ai.t_chat_request_handler_result )
  as
    l_structured_data_section clob;
  begin
    if p_param.component.type != 'APEX_APPLICATION_PAGE_REGIONS' then
      return;
    end if;

    if not is_interactive_report(p_param.component.id) then
      return;
    end if;

    l_structured_data_section := extract_structured_data_section(p_result.request.system_prompt);

    if l_structured_data_section is not null
       and not has_structured_data_message(p_result.request.messages)
    then
      insert_assistant_message_before_first_user(
        p_messages => p_result.request.messages,
        p_message  => l_structured_data_section );
    end if;
        -- add logging here to capture the system prompt
        -- example: insert into my_logs (clob_column) values (p_result.request.system_prompt)
    p_result.request.system_prompt := null;
    p_result.request.service_id := get_service_id(g_target_service_static_id);
  end ai_request;

end ai_handler_cache;
/

What the package is doing

The package does not try to reinvent NL2IR. It just changes the request shape before it goes out.

The flow is:

1. Check that the request is really coming from an Interactive Report.

2. Look inside the APEX-generated system prompt for the ## Structured Data section.

3. Extract that section.

4. Insert it into the message history as an assistant message, before the first user message.

5. Clear the request system prompt.

6. Route the request to the dedicated Anthropic service.

That one change is the whole trick.

Instead of sending one big changing system prompt every time, we separate the stable part from the variable part.

The stable instructions now live in the service configuration, where Anthropic can cache them. The structured data is still sent to the model, but it is no longer glued into the same system prompt that we want to keep stable.

Why the structured data is moved into a message

This is the part that matters for caching.

The package extracts only the ## Structured Data section and injects it as an assistant message before the first user question.

That means the model still gets the structured data it needs, but the static system instructions can stay static.

And static prompt prefixes are exactly what Anthropic caching likes.

The package also checks whether that structured-data message is already present, so it does not keep inserting duplicates into the conversation.

Step 4: Configure the request handler in APEX

Once the package is deployed, go to your application:

• Edit Application Definition

• AI tab

• Request Handler Procedure

Enter:

ai_handler_cache.ai_request

That is it.

From that point on, NL2IR requests for Interactive Reports will be rewritten and routed through the dedicated cached service.

Everything else is left alone, because the package exits unless the request is really coming from an Interactive Report.

What changes in practice

From the user point of view, nothing really changes. They still type natural language into the report and get the same feature.

From the request point of view, quite a lot changes.

Before:

• Around 17k tokens per request

• Big prompt repeated every time

• No real benefit from prompt reuse

After:

• First request still pays the full setup cost

• Roughly 15k tokens can be cached

• Those cached tokens are reused on each NL2IR call

That is where the savings come from.

A few important notes

This package is built around the current shape of the APEX NL2IR prompt, so there are a few assumptions worth calling out.

• It only targets Interactive Reports

• It expects the generated prompt to contain a ## Structured Data heading

• It routes requests to a dedicated service with static ID haiku-for-ir

• It assumes your static system prompt is already stored in the dedicated service Additional Parameters

So if Oracle changes the internal NL2IR prompt structure in a future release, this package may need a small update.

What about other providers?

This post uses Anthropic for the concrete implementation.

If your provider of choice is OpenAI, caching is fully automatic, so it will probably cache something even without changes. If you want to make it work better, you would need to modify my package so it removes the Structured Data section from the system prompt, but does not null out the system_prompt attribute. Instead, you would populate it with the rest of the system prompt. Also, because the system prompt is part of the message array rather than a separate attribute in OpenAI, you would want to modify how the package injects the structured data into the message array.

With Google, caching is also automatic, and the same general approach as OpenAI could work. If it does not, Google also has a separate endpoint where you define the cache, populate it with the content you want cached, and then refresh the TTL every hour or so. That could become a separate job to schedule and maintain.

I did not test those approaches, but I would be very happy to consult on them if someone dares to do it.

A few closing thoughts on the APEX AI hooks

I actually like that Oracle gave us request and response handler injection points this early. Without them, this whole approach would not really be possible.

That said, I do think the current request-building model works against optimization.

Right now Oracle builds the request such that messages land in the middle of it, between the system prompt, tools, and anything that we add in service configuration. For cost optimization, caching, and even debugging, that is a bit backwards.

What I would really like is a lower-level injection point just before the request is sent to the LLM service, after Oracle has finished building the final payload. That would make it much easier to do provider-specific optimizations cleanly instead of reverse-engineering the generated prompt shape.

I would also like better visibility into the actual provider request and response payloads. Right now that is one of the frustrating parts of working with caching. Anthropic exposes useful usage information, including cache-related fields, but Oracle does not really expose that final response data back to us in a way that lets us inspect cache hits properly.

So yes, the hooks Oracle gave us are already useful. But if Oracle exposed the final outbound payload and the real provider usage details, building and validating optimizations like this would be much easier.

If this were a production project, I would probably suggest not relying too heavily on the standard Oracle AI services directly. In that kind of setup, it would probably be better to configure one standard Ollama or OpenAI-compatible service in APEX, put a small proxy in front of the real provider, and let that proxy intercept the calls, optimize them properly, and then pass them on to the actual LLM service or at least use a service like OpenRouter.

And that is it

The interesting part here is that the big saving does not come from only switching to a cheaper model.

It comes from changing the request shape so the expensive, stable part of the prompt can actually be cached.

Instead of paying for a massive system prompt on every single turn, you turn it into a flow where the heavy lifting is cached and much cheaper on follow-up calls.

That is a much better place to be.

If you want to build on top of this, the obvious next steps are moving the service static ID into configuration, adding more defensive error handling around service lookup, and hoping Oracle eventually exposes enough provider-level usage data to make cache-hit validation much easier.

But first, why would you want to do this? Usually because you want a less expensive model for this feature. The system prompt for NL2IR is massive and very restrictive, and a decent chunk of metadata and tool information is sent along with each request. When I looked at the logs, each NL2IR call contained around 17,000 input tokens and only about 100 output tokens. That is massive, maybe even too massive.

My LLM provider of choice is Anthropic, and as of May 2026, 17k tokens works out to about \(0.11 per request on Sonnet (the mid-tier model), while on Haiku (the small, fast model) it is about \)0.04. So no matter what you are doing, you probably want NL2IR glued to the cheapest model possible.

This post also came from a question by Matt Mulvaney And if an Oracle ACE Director asks, the only real answer is: let’s do it ;)

We will start by creating two AI services.

One named Dummy, which we will set as our default service. I am setting Maximum AI Tokens to 0 to show the solution working, but you can set it however you want.

And the second will be the one we actually want to use.

The choice of model does not really matter. What matters is the static ID of the service we want to use for NL2IR. For me, it is haiku-for-ir.

Now we need to configure the default service in the app. Go to Edit Application Definition of your selected app, click the AI tab, and select the Dummy service. This is required for the NL2IR feature to show up.

Let's go into the app and observe the behavior.

Okay, looks like Oracle may need an NVL when checking the limits, because the first call is partially working, but after that we get errors. This is what we expected for this demo, so now let's make it use the correct service.

First, create this procedure. If you are coming from my previous blog post, you can modify the contents of the package we created there. Remember to change haiku-for-ir to the static ID of your LLM service.

create or replace procedure ai_request (
    p_param  in            apex_ai.t_chat_request_handler_param,
   p_result in out nocopy apex_ai.t_chat_request_handler_result
) is
   l_test number;
   l_service_id number;
begin
   -- Check if the request is coming from IR.
   select count(*)
     into l_test
     from apex_application_page_ir
     where region_id = p_param.component.id;

   if l_test = 0 then
      return; -- Not an IR request, skip.
   end if;

   -- Get the service ID.
   select remote_server_id
      into l_service_id
      from apex_workspace_ai_services
     where upper(remote_server_static_id) = upper('haiku-for-ir')
     fetch first 1 rows only;

   -- Set the new service.
   p_result.request.service_id := l_service_id;
end;

Then enter the procedure name, ai_request, into the Request Handler Procedure field on the AI tab of Edit Application Definition.

And you are done.
If we go back to the app, we will see that even though our default service is Dummy, NL2IR works perfectly.

APEX can limit token usage per service over 24 hours, but not directly per app user.
In this post, I will show a simple pattern to enforce per-user limits.

What we will build:

• A table to log AI usage per user

• Request/response handlers in APEX AI configuration

• Daily quota checks with warning and hard-stop behavior

Let's start by creating a table that will store all our users' AI calls.

create table ai_stats (
    id                     number default on null to_number(sys_guid(), 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX') 
                           constraint ai_stats_id_pk primary key,
    apex_user              varchar2(4000 char),
	input_tokens           number,
    output_tokens          number,
    total_tokens           number,
    resp_time              date,
    component_name         varchar2(4000 char),
    component_static_id    varchar2(4000 char)
);

Then we need to intercept the standard Oracle APEX calls to the LLM. Fortunately, Oracle APEX 26.1 gives us a standard way to do that.

Go to the Edit Application Definition of your chosen APEX app, then to the AI tab.
What we are interested in are the Request Handler Procedure and Response Handler Procedure fields. By default, they are empty.
Enter the following values:

ai_handler.ai_request

ai_handler.ai_response

Now every LLM request and response in your app will be routed through the ai_handler package.

The request handler blocks over-limit calls before they run, while the response handler logs usage and adds warnings as users approach the limit.

This implementation enforces limits based on total_tokens (input + output), not input tokens alone.

So let's create it:

create or replace package ai_handler as
	procedure ai_request (
		p_param  in apex_ai.t_chat_request_handler_param,
		p_result in out nocopy apex_ai.t_chat_request_handler_result
	);

	procedure ai_response (
		p_param  in apex_ai.t_chat_response_handler_param,
		p_result in out nocopy apex_ai.t_chat_response_handler_result
	);
end ai_handler;
/
create or replace package body ai_handler as
	g_daily_total_allowance                   number := 10000;
	g_daily_total_allowance_warning_threshold number := 8000;

	procedure ai_request (
		p_param  in apex_ai.t_chat_request_handler_param,
		p_result in out nocopy apex_ai.t_chat_request_handler_result
	) is
	l_total_tokens number;
	begin
			select nvl(sum(total_tokens),0)
		  into l_total_tokens
		  from ai_stats
		  where apex_user = sys_context(
			   'APEX$SESSION',
			   'APP_USER'
		   )
		   and trunc(resp_time) = trunc(sysdate);

       if l_total_tokens > g_daily_total_allowance then
         RAISE_APPLICATION_ERROR(-20001, 'Daily token allowance exceeded. You have used ' || l_total_tokens || ' total tokens today, which exceeds the daily allowance of ' || g_daily_total_allowance || ' tokens.');
        end if;
  end ai_request;

	procedure ai_response (
		p_param  in apex_ai.t_chat_response_handler_param,
		p_result in out nocopy apex_ai.t_chat_response_handler_result
	) is
		l_total_tokens number;
	begin
		insert into ai_stats (
			apex_user,
			input_tokens,
			output_tokens,
			total_tokens,
			resp_time,
			component_name,
			component_static_id
		) values ( 
      sys_context('APEX$SESSION','APP_USER'),
		  p_result.response.input_tokens,
		  p_result.response.output_tokens,
		  p_result.response.total_tokens,
		  sysdate,
		  p_param.component.name,
		  p_param.component.static_id );

		select nvl(sum(total_tokens),0)
		  into l_total_tokens
		  from ai_stats
		 where apex_user = sys_context(
			   'APEX$SESSION',
			   'APP_USER'
		   )
		   and trunc(resp_time) = trunc(sysdate);

        if l_total_tokens > g_daily_total_allowance then
         RAISE_APPLICATION_ERROR(-20001, 'Daily token allowance exceeded. You have used ' || l_total_tokens || ' total tokens today, which exceeds the daily allowance of ' || g_daily_total_allowance || ' tokens.');
        end if;

		if
			l_total_tokens > g_daily_total_allowance_warning_threshold
			and p_result.response.message.message is not null
		then
			p_result.response.message.message := p_result.response.message.message
			                                     || chr(10)
			                                     || 'Warning: You have used '
			                                     || l_total_tokens
			                                     || ' total tokens today, which is approaching the daily allowance of '
			                                     || g_daily_total_allowance
			                                     || ' tokens.';
		end if;

	end ai_response;
end ai_handler;

And that's it.

You may want to modify the g_daily_total_allowance and g_daily_total_allowance_warning_threshold variables. Or even move them to a separate table and build a whole system around this approach.

This is how it looks with a warning:

And this is what will happen when you exceed the limit:

APEX does not currently provide a clean cancel mechanism for this flow, so raising an application error is the most reliable way to stop over-limit requests.
With warning thresholds in place, users get clear notice before they hit the hard limit.

Here at Pretius we love Liquibase. It is a perfect tool that works at many levels of complexity, from simple generate schema no git setup to complex CI\CD pipelines that automatically install and upgrade dozens of environments. In this article, we will be focusing on the more complex use of oracle flavored liquibase. If you need a refresher on what liquibase is and how to use it you can visit Rafal's blog.

Let’s imagine you would like to write your own XML changeset using all the bells and whistles that Oracle provides, what are your options?

SQLCL documentation gives you a nice but unfortunately lacking table. What are the parameters for those tags? What are they used for? How to use them? Do we even know?

How to use them?

To use those tags you need to add a new XSD to your database change log - Notice the xmlns:n0 parameter in the example below - and use SQLCL to run your changes. Alternatively, you can add the extension to the standalone liquibase, a description of how to do it is in SQLCL documentation.

<databaseChangeLog 
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xmlns:n0="http://www.oracle.com/xml/ns/dbchangelog-ext" 
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog 
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

Oracle dbchangelog-ext

Unfortunately, while Oracle gives you a path to XSD to add to your XMLs this link leads to nowhere. I did some digging and found the file in SQLCL, but it is missing a lot of tags that Oracle specifies can be used. Hopefully, in future iterations, we will get a working link and full XSD.

Tags

Most of the tags do exactly what is written on the tin, but not all. Parameter specification is taken from dbchangelog-ext where possible but most are a result of me tinkering with them.

On the objectName attribute - Be sure that it matches the name of the object you are creating, SQLCL will use that attribute to generate rollback statements and it will put it into quotation marks. Unless you are using mixed case letters in your tables, triggers, sequences etc. always use all caps for this attribute.

createOracleDictionary

Missing from XSD.

Example:

        <n0:createOracleDirectory objectName="DATA_PUMP_DIR" objectType="DIRECTORY" ownerName="ADMIN"  replaceIfExists="true" >
            <n0:source><![CDATA[CREATE OR REPLACE DIRECTORY "DATA_PUMP_DIR" AS 'dpdump';]]></n0:source>
        </n0:createOracleDirectory>

createOracleProcedure

Missing from XSD.

        <n0:createOracleProcedure objectName="HELLOLIQUIBASE"  ownerName="ADMIN"  replaceIfExists="true" >
            <n0:source><![CDATA[CREATE OR REPLACE EDITIONABLE PROCEDURE "ADMIN"."HELLOLIQUIBASE" 
(
  NAME IN VARCHAR2 
) AS 
BEGIN
  dbms_output.put_line('Hello '||name);
END HELLOLIQUIBASE;
/]]></n0:source>
        </n0:createOracleProcedure>

createOracleConstraint

Missing from XSD.

There is a problem with this one. 1st of all it's missing from XSD, and lb generate-schema or lb generate-object will not use this tag, so there is no way for me to work out the intended use for it. Secondly, I tinkered with it a bit and in the example, you can see what I found working, but lb rollback will not be able to properly run. The same goes for createOracleRefConstraint although it gave me a slightly different error. I would advise you to not use those tags currently.

        <n0:createOracleConstraint objectName="TEST_CONST2" ownerName="SC_CORE"  >
            <n0:source><![CDATA[ ALTER TABLE test_table ADD CONSTRAINT test_const2 UNIQUE (column3); ]]>
            </n0:source>
        </n0:createOracleConstraint>

createOracleGrant

Missing from XSD.

        <n0:createOracleGrant objectName="object_grant0" objectType="OBJECT_GRANT" ownerName="SC_CORE"  replaceIfExists="true" >
            <n0:source><![CDATA[
  GRANT INSERT ON "SC_CORE"."TEST_TABLE" TO "LIQUIBASE_USER"]]></n0:source>
        </n0:createOracleGrant>

createOraclePackageBody

        <n0:createOraclePackageBody objectName="TEST" objectType="PACKAGE_BODY" ownerName="SC_CORE"  replaceIfExists="true" >
            <n0:source><![CDATA[
  CREATE OR REPLACE EDITIONABLE PACKAGE BODY "SC_CORE"."TEST" as
procedure p_test  as
begin
null;
end p_test;
end TEST;]]></n0:source>
        </n0:createOraclePackageBody>

createOracleJob

Missing from XSD.

<n0:createOracleJob objectName="LIQUI_JOB" objectType="JOB" ownerName="SC_CORE"  replaceIfExists="true" >
            <n0:source><![CDATA[

BEGIN 
dbms_scheduler.create_job('LIQUI_JOB',
job_type=>'PLSQL_BLOCK', job_action=>
'begin
 null;
end;'
, number_of_arguments=>0,
start_date=>TO_TIMESTAMP_TZ('04-OCT-2023 10.01.38.534232000 PM EUROPE/ATHENS','DD-MON-RRRR HH.MI.SSXFF AM TZR','NLS_DATE_LANGUAGE=english'), repeat_interval=> 
'FREQ=YEARLY;BYDATE=1101;BYTIME=213700'
, end_date=>NULL,
job_class=>'DEFAULT_JOB_CLASS', enabled=>FALSE, auto_drop=>FALSE,comments=>
'My test job for blogpost'
);
sys.dbms_scheduler.set_attribute('LIQUI_JOB','NLS_ENV','NLS_LANGUAGE=''ENGLISH'' NLS_TERRITORY=''POLAND'' NLS_CURRENCY=''zł'' NLS_ISO_CURRENCY=''POLAND'' NLS_NUMERIC_CHARACTERS='', '' NLS_CALENDAR=''GREGORIAN'' NLS_DATE_FORMAT=''RR/MM/DD'' NLS_DATE_LANGUAGE=''ENGLISH'' NLS_SORT=''BINARY'' NLS_TIME_FORMAT=''HH24:MI:SSXFF'' NLS_TIMESTAMP_FORMAT=''RR/MM/DD HH24:MI:SSXFF'' NLS_TIME_TZ_FORMAT=''HH24:MI:SSXFF TZR'' NLS_TIMESTAMP_TZ_FORMAT=''RR/MM/DD HH24:MI:SSXFF TZR'' NLS_DUAL_CURRENCY=''zł'' NLS_COMP=''BINARY'' NLS_LENGTH_SEMANTICS=''BYTE'' NLS_NCHAR_CONV_EXCP=''FALSE''');
dbms_scheduler.enable('LIQUI_JOB');
COMMIT; 
END; 
]]></n0:source>
        </n0:createOracleJob>

createOraclePackageSpec

        <n0:createOraclePackageSpec objectName="TEST" objectType="PACKAGE_SPEC" ownerName="SC_CORE"  replaceIfExists="true" >
            <n0:source><![CDATA[
CREATE OR REPLACE EDITIONABLE PACKAGE "SC_CORE"."TEST" AS 
procedure p_test;
end;
]]></n0:source>
        </n0:createOraclePackageSpec>

createOraclePublicSynonym

Missing from XSD. Lb generate-schema will not use this tag. Functions the same as createOracleSynonym.

createOracleRefConstraint

Missing from XSD. See createOracleConstraint.

createOracleSynonym

Missing from XSD. Lb generate-schema will use this tag even for public synonyms.

        <n0:createOracleSynonym objectName="LOGGER_LOGS_5_MIN" objectType="SYNONYM" ownerName="SC_CORE"  replaceIfExists="true" >
            <n0:source><![CDATA[
  CREATE OR REPLACE EDITIONABLE SYNONYM "SC_CORE"."LOGGER_LOGS_5_MIN" FOR "LOGGER_USER"."LOGGER_LOGS_5_MIN"]]></n0:source>
        </n0:createOracleSynonym>

createOracleTrigger

        <n0:createOracleTrigger objectName="TEST_TRIGGER" objectType="TRIGGER" ownerName="SC_CORE"  replaceIfExists="true" >
            <n0:source><![CDATA[
  CREATE OR REPLACE EDITIONABLE TRIGGER "SC_CORE"."TEST_TRIGGER" 
BEFORE DELETE OR INSERT OR UPDATE ON TEST_TABLE 
BEGIN
  NULL;
END;
/
ALTER TRIGGER "SC_CORE"."TEST_TRIGGER" ENABLE]]></n0:source>
        </n0:createOracleTrigger>

createOracleTypeBody

Missing from XSD.

        <n0:createOracleTypeBody objectName="DATA_TYP1" objectType="TYPE_BODY" ownerName="SC_CORE"  replaceIfExists="true" >
            <n0:source><![CDATA[
  CREATE OR REPLACE EDITIONABLE TYPE BODY "SC_CORE"."DATA_TYP1" IS   
      MEMBER FUNCTION prod (invent NUMBER) RETURN NUMBER IS 
         BEGIN 
             RETURN (year + invent);
         END; 
      END; ]]></n0:source>
        </n0:createOracleTypeBody>

createOracleTypeSpec

Missing from XSD.

<n0:createOracleTypeSpec objectName="DATA_TYP1" objectType="TYPE_SPEC" ownerName="SC_CORE"  replaceIfExists="true" >
            <n0:source><![CDATA[
  CREATE OR REPLACE EDITIONABLE TYPE "SC_CORE"."DATA_TYP1" AS OBJECT 
   ( year NUMBER, 
     MEMBER FUNCTION prod(invent NUMBER) RETURN NUMBER 
   ); 
]]></n0:source>

createSxmlObject

A bit strange but can be useful in a pinch. This tag lets you create an object defined by SXML. What is SXML? In this context, this is a specification of a given object generated by dbms_metadata with SXML transformation applied. This tag is used by Oracle to generate table changesets when you run lb generate-schema instead of doing separate changesets for each 'parts' of the table.

<n0:createSxmlObject objectName="TEST_TABLE" objectType="TABLE" ownerName="SC_CORE"  replaceIfExists="true" >
            <n0:source><![CDATA[
  <TABLE xmlns="http://xmlns.oracle.com/ku" version="1.0">
   <SCHEMA>SC_CORE</SCHEMA>
   <NAME>TEST_TABLE</NAME>
   <RELATIONAL_TABLE>
      <COL_LIST>
         <COL_LIST_ITEM>
            <NAME>COLUMN1</NAME>
            <DATATYPE>NUMBER</DATATYPE>
            <NOT_NULL></NOT_NULL>
         </COL_LIST_ITEM>
         <COL_LIST_ITEM>
            <NAME>COLUMN3</NAME>
            <DATATYPE>VARCHAR2</DATATYPE>
            <LENGTH>20</LENGTH>
            <COLLATE_NAME>USING_NLS_COMP</COLLATE_NAME>
         </COL_LIST_ITEM>
         <COL_LIST_ITEM>
            <NAME>COLUMN2</NAME>
            <DATATYPE>DATE</DATATYPE>
         </COL_LIST_ITEM>
      </COL_LIST>
      <PRIMARY_KEY_CONSTRAINT_LIST>
         <PRIMARY_KEY_CONSTRAINT_LIST_ITEM>
            <NAME>TEST_TABLE_PK</NAME>
            <COL_LIST>
               <COL_LIST_ITEM>
                  <NAME>COLUMN1</NAME>
               </COL_LIST_ITEM>
            </COL_LIST>
            <USING_INDEX>
               <INDEX_ATTRIBUTES>
                  <PCTFREE>10</PCTFREE>
                  <INITRANS>20</INITRANS>
                  <MAXTRANS>255</MAXTRANS>
                  <TABLESPACE>DATA</TABLESPACE>
                  <LOGGING>Y</LOGGING>
               </INDEX_ATTRIBUTES>
            </USING_INDEX>
         </PRIMARY_KEY_CONSTRAINT_LIST_ITEM>
      </PRIMARY_KEY_CONSTRAINT_LIST>
      <DEFAULT_COLLATION>USING_NLS_COMP</DEFAULT_COLLATION>
      <PHYSICAL_PROPERTIES>
         <HEAP_TABLE>
            <SEGMENT_ATTRIBUTES>
               <SEGMENT_CREATION_DEFERRED></SEGMENT_CREATION_DEFERRED>
               <PCTFREE>10</PCTFREE>
               <PCTUSED>40</PCTUSED>
               <INITRANS>10</INITRANS>
               <MAXTRANS>255</MAXTRANS>
               <TABLESPACE>DATA</TABLESPACE>
               <LOGGING>Y</LOGGING>
            </SEGMENT_ATTRIBUTES>
            <COMPRESS>N</COMPRESS>
         </HEAP_TABLE>
      </PHYSICAL_PROPERTIES>
   </RELATIONAL_TABLE>
</TABLE>]]></n0:source>
        </n0:createSxmlObject>

dropSxmlObject

So this should remove your object. It will just try and drop anything you will give it. I allowed myself a small joke in this example ( 'lb up' will try to execute it )

        <n0:dropSxmlObject objectName="HOT" ownerName="SC_CORE" objectType='IT LIKE IT&apos;S ' >
            <n0:source>Anything can go here
            </n0:source>
        </n0:dropSxmlObject>

dropOracleProcedure

<n0:dropOracleprocedure objectName="HELLOLIQUIBASE" ownerName="ADMIN"></n0:dropOracleprocedure>

dropOracleFunction

<n0:dropOracleFunction objectName="HELLOLIQUIBASE" ownerName="ADMIN"></n0:dropOracleFunction>

dropOracleGrant

Missing from xsd. I was unable to work out how to make that one work. It requires objectName and ownerName parameters but even those trow an error.

dropOraclePackageBody

<n0:dropOraclePackageBody objectName="HELLOLIQUIBASE" ownerName="ADMIN"></n0:dropOraclePackageBody>

dropOraclePackageSpec

<n0:dropOraclePackageSpec objectName="HELLOLIQUIBASE" ownerName="ADMIN"></n0:dropOraclePackageSpec>

dropOracleRefConstraint

Missing from xsd. Unfortunatly i wasn't able to make that one work.

dropOracleTrigger

<n0:dropOracleTrigger objectName="HELLOLIQUIBASE" ownerName="ADMIN"></n0:dropOracleTrigger>

dropOracleTypeBody

Missing from xsd.

        <n0:dropOracleTypeBody objectName="DATA_TYP1" ownerName="SC_CORE"  >
        </n0:dropOracleTypeBody>

dropOracleTypeSpec

Missing from xsd.

        <n0:dropOracleTypeSpec objectName="DATA_TYP1" ownerName="SC_CORE"  >
        </n0:dropOracleTypeSpec>

dropOracleSynonym

Missing from xsd.

        <n0:dropOracleSynonym objectName="DATA_TYP1" ownerName="SC_CORE"  >
        </n0:dropOracleSynonym>

runOracleScript

This one is well documented here

Example taken from documentation:

   <n0:runOracleScript objectName="myScript" ownerName="JDOE" sourceType="STRING">
       <n0:source><![CDATA[DEFINE table_name = RUNNERSTRING;create table &&table_name (id number);]]></n0:source>
    </n0:runOracleScript>

runApexScripts

This one is undocumented and used by Oracle in creating changesets that install Apex applications. I didn't do any testing on this one. It seems that compared to runOracleScript it adds some context values and probably sets the correct security group.

  <n0:runApexScript objectName="install" objectType="SCRIPT" ownerName="LIQUIBASE_USER" sourceType="STRING" >
        <n0:source><![CDATA[
-- your apex script goes here
-- you can also call a file like this
--@@path/to/file/install.sql
]]>
<n0:source>
</n0:runApexScript>

What's next

Hopefully, this list will save you a little bit of time next time You decide to write your own XML changesets. In the future, I plan to release part 2 where we will take a look at how those tags translate into automatic rollbacks.