Skip to main content

APEX Deployment Tool

I

Imagine this: You create a new page in APEX, or change existing one. Create new LOV, create a view for this LOV, create a view for report/grid on page, create a package to handle the logic... Now what? Now you have to get this to version control and you have to deploy it to other environments. So you want it now on test env, but you have to create a patch in a way, which can be run later on prod. With ADT you can do all of this without any effort just in few seconds. The whole idea behind ADT is to move as quickly as possible with minimum hassle for developers, to create something simple to setup, simple to explain, simple to use, so you can quickly start using it. Something which would save you a lot of time every day.


This will be split to several articles:


Intro

There are several tools out there covering various parts of CI/CD pipeline. This is my offering, the APEX Deployment Tool. An open-source tool written in Python which allows you to connect to your Oracle database (cloud or on premise), export objects, data and APEX applications, files and individual components into a folder structure. It helps you to automate the patching and deploying/migrating your changes to other environments. It does several other things and this is simplified description. If you are missing something, feel free to ask or add it yourself.

ADT supports different branching strategies. From trunk based development to feature factory (GitHub Flow) with various hybrids in between. Basically this process is up to you. ADT was designed for teams with 10 developers or less. You can use it for larger teams, but at that point your strategy and pace would be probably a bit different. Checkout the APEX Lifecycle technical paper from Oracle for larger teams.

I would say it is easy to setup once you install it. You just need to specify a connection to your database and you are ready to go. ADT does not store anything in your database, so you can be using it without leaving trace or any help objects in database. You don't need any permissions, you don't need DBA.

I have been building these CI/CD tools since 2008 and ADT is the newest version, heavily based on the previous OPY tool, which unfortunately outgrown to a hefty spaghetti code and became more and more difficult to maintain. So, I have decided to start from scratch for the 15th time...

All of this is based on files (since you can use version control on files). Every database object and every APEX component has its own file and the whole folder structure is in your Git repo. This repo thingy is also mandatory for automated patching, you will see later.


Spoiler alert

It is not finished yet. Well, all APEX related features are. It is missing some core DB features like exporting objects and data (I am planning to deliver this before summer holidays, for now I am using OPY tool for these). Don't be scared, you can test drive it now. Roadmap with features is on main page on GitHub (link above).

UPDATE: Added the database exports, so you now have everything you need in ADT.


Workflow

Since there are teams out there struggling with the whole workflow concept, here is how it works. You pickup a task and you start changing database objects and/or APEX app. If you do it on your own instance or on the shared one, that is up to you. Small teams usually work on shared environment. Similar for the files. You can open and work with your database objects through the local files or you can modify them directly in the database. You have the freedom to choose and there is no correct or wrong approach. I mostly work with the files.


Export changes

adt export_apex -app 100 -split -embedded
adt export_apex -app 100 -recent 1
adt export_db -recent 1
adt export_db -type PACKAGE -name A%

When you are done with the changes or you have anything significant you want to save, you run the tool which basically export your changes to files. More details later. You can do multiple commits and you should mark all of them with a task number and description. If your change requires some table ALTERs and/or data changes, you have to save these changes to a file. For automated patching this should be in patch_script/task_number/ folder. Other than that you don't have to care about anything. And you can cherry pick your lines in the commits, you don't have to commit the whole file.

As a fan of the trunk development, I do this in a DEV branch. But you can do this in your feature branch if you want, that is perfectly fine. At some point you would have to merge your branch to DEV and at that point you will be the one responsible for the merge and dealing with merge conflicts. ADT works with bot approaches. For small teams and minimalistic approach you only need two branches: DEV for work in progress and MAIN for production code.

For automated pipeline this would be the point where you trigger the deployment to your test environment. You have to create hooks in GitHub Actions yourself, it is not part of the ADT. But you can call ADT from the pipeline to deploy your patches.


Create and deploy patch

adt patch -target UAT -patch TASK1
adt patch -target UAT -patch TASK1 -create -head
adt patch -target UAT -patch TASK1 -deploy

When you want to test your code on another environment, you have to somehow move your code there, right? ADT will create a patch for you, all you have to do is provide a task number and target environment. It will go through all the commits and create a list of files in proper order so you can just run the patch without invalidating half of your database or going through the log full of errors. It will add prompts so you will know what is happening in log. It will pull the correct files version for that task (there are some other options implemented) to a snapshots folder, so your patch contains everything for this specific card.

It also performs some checks, for example for the merge conflicts you forgot to solve or to check if the file you are trying to use isn't an older one. That happens when you deploy your changes with significant time delays (the waterfall method) and when you push changes to production randomly (when project management turns into crisis management and you decide to deploy patch A, C and D, but not B, because B will be deployed a month later and at that point you start sweating about all the things which will go wrong). Been there, so again, I am a huge fan of deploying things often.

One more thing, ADT does not handle any rollbacks. If you need a way how to revert your code, you have to deal with that yourself. In small teams it is usually better to roll forward and just fix the issue with next patch. In my experience it is also more effective this way and the often you do the releases to PROD, the less issues you will have.

When you deploy this to your target environment, it will make sure your objects are valid and show you the errors. It will also notify whole team on Teams channel with patch and deployment details, so everyone is aware. Since whole tools consists of these separated commands, you can automate it. When you merge patch into MAIN branch, you can initiate the deployment to production.


Summary

To summarize the workflow: as a developer you will work on your card, you will make one or more commits with task number and description, you will sooner or later decide to deploy this to test environment so you will create a patch, you deploy the patch to UAT, test it there and repeat on PROD (pre-prod, stage, integration or whatever other environments you have). Point is, that this tool will export objects for you in a readable formats, in customizable structure and it will create the patch scripts for you. That is where you save most of the time. And with just one more command it will deploy it for you anywhere you have access. So when I am done with a task, in less then a minute it is deployed to UAT, in less then a minute it is deployed to PROD. And everything is covered in Git.


Tags:

Comments

Post a Comment