I’ve been using Oracle Application Express (APEX) for more years than I can count on my fingers. Throughout the entire time, I, along with many others, have grappled with version controlling APEX applications. Before diving into this controversial topic, it’s important to recap some background information around APEX and version control.

APEX is a development framework whose source is primarily maintained in the database. It is not file-based, which is very different from “traditional” development frameworks and languages. The one file it does produce (called an export file which is used as an install script), is automatically generated and uses many randomized values which don’t easily allow for comparing two copies of the same application. Another way to think of APEX and its file/install process is that it’s an “all or nothing” approach.

Not surprisingly, this can make developers coming from traditional file-based frameworks a little nervous at best, or set them off to gather up their torches and pitchforks at worst.

But where’s the clutch?

Let me pause for a minute and ask a question: what’s your favorite “but where’s the X” story? A friend of mine who grew up on a ranch and learned to drive at a very young age, it was when he first got into an automatic pickup truck after only ever driving a standard and asked, “But where’s the clutch?!?” His dad’s reply, “There is no clutch; it’s all automatic,” was, of course, met with suspicion.

Similarly, developers coming to APEX from traditional file-based frameworks who ask, “But where are the source files to put in our version control system?”, are suspicious when they hear, “It doesn’t work like that”. Of course, some jump to the conclusion that there is no version control with APEX at all, but that’s not the case. It’s just done differently, and that’s what this blog post covers.

Let’s clarify version control

To get started, let’s first clarify what we mean by “version control” as it can mean different things to different people. In most cases, it covers the following:

1. Tracking versions of the application by tagging the code at a given point in time
2. Tracking changes between code check-ins
   • Enable developers to view specific changes in the code and/or track when a feature was introduced into the code.
3. Rolling back changes for a specific file or entire version
4. Merging code to allow multiple developers to work on the same piece of code at the same time

Given how APEX works, it supports the first point listed above for version control. Basically, you “version” the entire application at a given point in time. The other points need to be handled differently, and this can be a contention point for some people when evaluating APEX as it may not comply with their current release management practices.

I had the same concern when I became more involved with APEX, and over the years, I’ve learned to get over it. Despite APEX’s inability to support “traditional” version control, it hasn’t prevented people from not only developing many applications with it, but also running their entire business on APEX applications. One must look no further than Oracle itself. a significant portion Oracle’s cloud UI runs APEX applications.

Benefits far outweigh perceived limitations

Basically, for me and many others, benefits of APEX, (e.g. development and deployment speed), far outweigh any perceived limitations with version control. APEX developers everywhere have been able to mitigate APEX’s version control constraints by using good development practices that work well with APEX and support traditional version control standards. As a result, organizations have been able to reap the benefits of using a high-productivity development tool like APEX, while at the same time ensuring they have adequate controls in place. The processes are different, but the end result is more or less the same. You give a little, but gain a lot. For me, the choice is clear, but each organization will have to decide what is most important to them.

Below I’ve addressed each of the points I listed above, and have included suggestions on how to address when developing with APEX.

1 – Tagging the code

This is a very simple thing to do with APEX applications. In your source directories, ensure that you have a folder for APEX apps (an example shown below). As part of your build script auto-export your APEX applications and check them into the apex folder.

2 – Track changes

Since APEX is table based, everything ends up being a row in a table. The export file, (which is used to install the application), reflects this table-driving architecture. The export file is really a PL/SQL script that re-inserts the application into rows (a snippet of the export file is shown below). The IDs may easily change in export files. When doing a file comparison, commonly called a diff, most rows will be marked as changed, since the IDs are different, making it nearly impossible to see what has really changed in an app between versions.

Strategies to mitigate the inability to track changes in the export file

There are ways you can mitigate the inability to track changes in an APEX export file:

• Store as much code as possible in packages, views, CSS, JavaScript, etc. These database objects can be stored as “regular” files. They handle diffs very easily. See the previous image on a standard version controlled directory structure.
  • This means that instead of having large blocks of code in an APEX application, you move the business logic to packages and views and reference those instead.
• The previous point still doesn’t address the root of the problem of diffing two versions of an APEX application. APEX Diff is an open source tool that will export an APEX application in a JSON format. Using the JSON format export you can do diffs on different version of an APEX application as it allows you to remove the row IDs and focus just on the APEX modifications that developers make.After using this tool for a while, I’ve found that it helps identify small changes (when doing minor releases), but if comparing versions with a lot of work in between, it can become hard to determine what has changed as there are a lot of modified lines.
• APEX 5.2 may have native built in version control. I saw this on a tweet from a conference. This is just speculation, for now. The APEX development team has been testing out a new feature called “Blueprints” which allows you to save templates of APEX applications as a JSON structure. Based on this initiative, I expect to see a JSON export of APEX applications in future versions that will diff a lot better than the current expert file. Again, this is a guess. Don’t base your purchasing decisions on this information.

3 – Rollback changes

If you look at the underlying tables in the APEX schema, you’ll see that they share many relationships. These relationships mean that a lot of the APEX objects are tightly integrated with one another. This has its pros and cons. The pros are that it allows for a declarative development framework. The con, with respect to version control, is that items are very tightly integrated with one another.

An example of this tight integration is a page item and a validation on that page item. The validation is tied directly to the page item. What happens if someone wanted to roll back the change of creating a given page item? What would happen to the validation? For this reason, I don’t see the ability to rollback specific changes happening anytime soon.

For the most part, this hasn’t been too big of an issue. They’re some things that can help with this:

• Storing as much code in files outside of APEX (see SVN folder structure above as an example)
• Using Build Options for controlling which objects are available in specific releases
  • This allows teams to develop on future work but not make it available
• Shorter release cycles
  • Shorter release cycles help identify and fix problems quickly
  • It will help mitigate the need to rollback changes to a specific version

4 – Merge code

As mentioned in the previous point, merging two APEX files doesn’t work well as there could be many cross-dependencies. It also isn’t a common requirement since most teams work on APEX applications that exist in one database (i.e. they develop on the same system).

In most situations, developers tend to “own” a set of pages and do most of their work in those areas. It’s rare that multiple developers are trying to work on the same page at the same time. In the case that certain areas in an application are contention points for developers the following tips can help:

• Store as much code as possible in files
  • I realize I have mentioned this many times. This is on purpose. I want to emphasize how this mitigates most of the “version control” problem in APEX. 
• Lock pages before developing them.
  • This will only give a single developer access to the page while working on it
  • Don’t forget to unlock the page once done!

If you want more information about version control and APEX, Oracle has written a white paper about Life Cycle Management with Oracle Application Express that covers a lot of what was mentioned in this article (full disclosure: Insum helped contribute to this white paper). Of course, if you need some help setting things up or want to discuss your current APEX development setup and how you can improve it for better version control, let us know.