ADT - APEX Deployment Tool

ADT is an open-source tool written in Python which allows you to connect to your Oracle database, export objects and 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 in multiple variants.

It does not store anything in your database.

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 extend. So, I have decided to start from scratch for like 15th time...

 

Install

Checkout the INSTALL guide. You might find more technical things here in documentation, but more human friendly version with some explanations is on my blog under the Project ADT tag.

 

Feature requests

Any feature requests, bugs are accepted on my LinkedIn (checked daily), Slack (checked weekly) or via the contact form on my web http://www.jankvetina.cz. Thank you.

 

Actions/Roadmap

Filename	Description	Status
config.py	to manage database connections and settings	Done
export_db.py	to export database objects	Done
export_apex.py	to export APEX & REST services	Done
export_data.py	to export data into CSV files	Done
live_upload.py	to upload files to APEX	Done
patch.py	to prepare patch files and deploy them	Done
compare.py	to compare two databases	Planned
recompile.py	to recompile invalid objects	Done
search_apex.py	to search for objects in APEX	Done
search_repo.py	to search repo history	Done

 

Main features (also a Roadmap)

• ✅ it can connect to on-premise and cloud Oracle databases
• ✅ it can export APEX application(s)
  • ✅ you can request specific components based on page or date
  • ✅ also in YAML/JSON formats
  • ✅ possible with embedded code reports
  • ✅ including application and workspace files
  • ✅ option to deploy exported files to specified environment
  • ✅ live upload for files
  • ✅ export REST services
• ✅ it can create patch files so you can easily deploy your database and APEX changes since last deployment, or based on your features/cards
  • ✅ it can connect to Git/BB to create a release notes for you
  • ✅ it can also create a patch file based on a feature/card, it will lookup which files were committed under that name and create a patch based on that (and even for APEX components so you dont have to deploy the whole app)
  • ✅ it allows you to search Git/BB history for specific string
  • ✅ include various checks and scope limits for what will be part of the patch
  • ✅ you can use sequences to sort patches created on same day, it checks for clashes
  • ✅ files are properly sorted based on dependencies
  • ✅ statements in patch scripts converted to your templates so they can be rerun
• ✅ it can also deploy these patches to different environments (basically any database you can reach via direct connection on via a REST service)
  • ✅ multiple schemas patching (so far you manually specify order with numeric prefix on each patch file)
  • ✅ show progress, results and save output in customized log files
  • ✅ include various checks and logs to limit deployment issues (like using old files)
  • ✅ option to quickly deploy or redeploy created patch
  • ✅ show patch result (build log) on Teams channel
  • ✅ generate ALTER statements automatically from your commits and in a safe/repeatable way
  • ⭕️ remote REST app deployment
• ✅ it can export database objects
  • ✅ if does not use SQLcl anymore, because direct exports are 3x faster
  • ✅ generate list of dependencies
  • ✅ you can filter objects by type, name and time (export for example everything starting with XX% and changed in past 3 days)
    • ✅ tables, views, indexes, sequences, synonyms
    • ✅ packages, procedures, functions, triggers, types
    • ✅ materialized views + logs
    • ✅ jobs (resp. schedulers)
    • ✅ grants (made and received), user grants and roles, directories
  • ✅ there are also multiple whitelist and blacklist filters so you can specify which prefixes you want to include or you want to skip
  • ✅ multiple schemas are supported via subfolders (schema/db/object_type..., db/schema/object_type...)
  • ✅ you can also manually create subfolders for objects (so you can put for example views into groups/folders)
  • ⭕️ option to deploy exported files to specified environment
• ✅ it can export data into CSV files
  • ✅ dumps specified tables to CSV files, with some filtering
  • ✅ creates SQL MERGE statements for patching, you can set INS/UPD/DEL parts in config
  • ⭕️ althought it will skip LOB columns (for now)
  • ⭕️ option to deploy exported files to specified environment
• ✅ generate install script for test/local environments to install everything into a clean schema
• ⭕️ it can compare two databases and show you the differences and what you need to do to sync them, including the data changes
  • ⭕️ no false positives on different column positions, different identity column sequences, whitespaces...
  • ⭕️ it can also quickly compare APEX applications based on the signatures
  • ⭕️ generate ALTER statements for table changes, align columns order, sync sequences...
• ✅ it can recompile invalid objects + limit the scope based on type and name
  • ✅ it can also force recompile objects and set specific PL/SQL attributes on them
• ✅ see config.yaml file for many parameters you can customize
  • ✅ to use your config.yaml file, just place it in the config folder in root of your project repo

 

Folder structure

• doc/
  • if you are into documenting things, you will love this folder
• database_{$info_schema}/{$object_type}/ for database objects
• database_{$info_schema}/data/ for exported data
• database_{$info_schema}/unit_tests/ for packages which are unit tests
• database/grants_made/{$info_schema}.sql
• database/grants_received/{$info_schema}.sql
  • made and received grants for each schema involved
• apex/{$app_ws}/{$app_group}/{$app_owner}/{$app_id}_{$app_alias}/
  • for APEX app and related objects
  • optional workspace, application group, owner and app alias in the path
  • you don't have to use all of these variables
• apex/{$app_ws}/rest/
  • with folders and files
• apex/{$app_ws}/workspace_files/
• patch/{$date_today}.{$sequence}.{$patch_code}/ for generated patch files
• patch/{$date_today}.{$sequence}.{$patch_code}/LOGS_{$info_env}/ for deployment logs
• patch_archive/ for old patches (use deploy.py -archive)
• patch_template/ for patch templates (appended to all patches)
• patch_scripts/{$patch_code}/ for patch scripts (appended to just for specific patch)
• scripts/ for your scripts, snippets, tests...

 

You can customize all of these paths through the config.py and there are plenty of variables available to fit your needs.

 

Supporting apps

ADT provides you more benefits when used with other APEX apps (but it is fully functional without these apps):

Application Name	Description	Status
Cards	to manage your tasks, bugs...	Done
Roadmap	to plan and track whole projects on higher level	In Progress
Deployments	to track commits, releases and deployments	Planned
Reviews	to improve quality of your code	Planned