How to Pull/Push using Gitora 4

Gitora 4 enables Oracle developers to push to and pull from other Git repositories including the ones hosted by GitHub, GitLab, Bitbucket etc…

Below are the steps to achieve this:

Register the remote repository to Gitora

In the Gitora web application, click the File –> Manage Remote Repositories.

The File Menu

The Remote Git Repositories dialog shows up.

Remote Git Repositories Dialog

Click the green plus button to create a new row. Next, enter a friendly alias for the remote Git repo. Finally, enter the URL that points to the remote repo. If you are using a service like GitHUb, refer to the service provider website for the correct URL. For GitHub, the URL is in the following format:[github user name]/[gitreponame].git

If you are referencing a Git repository managed by another Gitora installation follow the steps below to find the URL pointing to the remote Git repo:

  • Open the Gitora app that manages the remote repo you want the URL for. Note that, this should be a different Gitora app than you are currently in.
  • Open the remote repo in the Gitora app.
  • If the repo is empty, the URL will show up immediately. If it is not empty, click the repo name on the right side of the screen. (In the screenshot below, the repo name is HRRepo.)
  • Copy the URL for the repo.
  • Go back to the first Gitora app and paste the URL to the URL field in the Remote Git Repositories dialog.
  • Check the checkbox “Gitora Repo?”. This informs Gitora that this is a repo used by another database and therefore cannot be pushed to (but can be pulled from.). Git does not allow pushing to repos with a working directory.
  • Click OK to save your changes.

Pushing to a remote Git Repo

Open the Gitora app, select the repo you’d like to push and click the push icon in the toolbar.

The Push dialog shows up.

The Push Dialog

Select the branch you’d like to push and the target remote repository you’d like to push this branch to. Enter the user name and password to connect to the remote repository. Leave these fields empty if the remote repository is not protected by a user name and a password. For example, if you are pushing to GitHub, the credentials you should enter are your GitHub user name and password.

Click push and wait for the response message to show up.

Pulling from a remote Git Repo

Open the Gitora app, select the repo you’d like use and click the pull icon in the toolbar.

The Pull Dialog shows up

The Pull Dialog

Select the remote Git repo and enter the name of one of its branches you’d like to pull from. Enter the user name and password to connect to the remote repository. Leave these fields empty if the remote repository is not protected by a user name and a password. For example, if you are pushing to GitHub, the credentials you should enter are your GitHub user name and password. Repositories managed by Gitora do not have a user name and a password. If you are pulling from a repo managed by Gitora, make sure to leave these fields blank.

Click the Pull button and wait for the response message to show up.

Introducing Gitora 3, version control for the Oracle Database

Today, we’re happy to announce the general availability of Gitora 3.

Gitora 2 enabled developers to manage database objects that support the CREATE OR REPLACE command, namely PACKAGES, PROCEDURES, FUNCTIONS, TRIGGERS, VIEWS, SYNONYMS and TYPES in a Git repository. (In Gitora terminology, we call these “Soft Objects”).

Gitora 3 goes a step further and enables developers to manage every database object in an Oracle Database with Git even if the object does not support the CREATE OR REPLACE command. (In Gitora terminology, we call these “Hard Objects”.)

Specifically, Gitora 3 allows developers to manage TABLES, INDEXES, SEQUENCES, CONSTRAINTS, TABLESPACES, MATERIALIZED VIEWS and every other schema or non-schema objects with Git.

Let’s examine how you can manage these objects with Gitora 3 with an example.

Introducing Managed Schemas

Gitora 3 introduces the concept of a Managed Schema. A managed schema is an Oracle Database Schema that Gitora tracks for execution of Hard Object DDL’s. In other words, you register one or more Oracle Schemas to a Gitora repository. Once a schema is registered to a repository, Gitora will track every hard object DDL executed for that schema. A repository can manage many schemas but a schema can only be managed by one repository.

Adding A Managed Schema to a Gitora Repository

In the Gitora App, select a repository. Click Local Commands –> Add/Remove Managed Schemas menu option. A dialog shows up.

Select the schema(s) you’d like to manage.

Click OK. The dialog closes. The screenshots above show the HR schema being added to a repo as a managed schema.

The Model Package

After a schema becomes managed, Gitora creates a new package in the schema automatically. This package is always called GITORA_MODEL[X] where [X] is a unique number that identifies the package. In our example above, Gitora created the GITORA_MODEL1 package in the HR schema and added this package to the Git repository which is managing the HR schema:

The screenshot above tells us that repo1 is managing the HR schema.

Tracking Soft Objects

There are no changes in Gitora 3 for soft objects. You continue managing soft objects just like you’ve been managing them with Gitora 2. In other words, any repo can manage any number of soft objects and any number of schemas.

To demonstrate this let’s add a dummy package called PACKAGE1 to HR and manage it with the same repo named repo1:

Select Local Commands –> Add/Remove Soft Objects menu item. A dialog shows up where you can select which soft objects you’d like to manage with repo1. Note that, GITORA_MODEL1 package shows up as a managed package because it was automatically created to manage the hard objects in the HR schema. 

Add PACKAGE1 as a managed package and click OK. The Gitora App shows the following object list for repo1:

Tracking Hard Object DDL’s

Let’s execute the following DDL statements for the HR schema: (Note that in the database session we first have to log in to Gitora with a valid Gitora user. In this case, we logged in as admin.)




Finally, let’s also modify a soft object and add a new dummy function to PACKAGE1 called function1.

To commit our changes, let’s switch to Gitora App and click the commit button. The My Objects Dialog shows up, displaying the list of soft objects and hard object DDL’s ready to be committed to Git. Note that the dialog only shows the changes made by the signed in developer:

In this dialog, you can choose which packages or hard object DDL’s you’d like to include in this commit by checking/unchecking the checkbox in the Include? columns of both grids.

Note that, the commit registers the package update and the table DDL statement as a single logical commit which is a key benefit we’d like to get from the version control system.

After the commit, we receive the following message from Git:

Note that, the Git commit not only included PACKAGE1 but also the GITORA_MODEL1 package. After the Git commit is successful, the new GITORA_MODEL1 package code looks like this:

PACKAGE BODY gitora_model1 IS 

function doModel return clob is
  v_log_cl clob;
  v_ddl_cl clob;
  v_cursor_int integer;
  return_value integer;
  procedure log(in_text_cl clob) is
  /*SCRIPT FOR HR.COUNTRIES by user:admin */
    execute immediate v_ddl_cl;
    log('DDL executed successfully.');
    when others then
      log('ERROR:'||' '||SQLErrm||' '||dbms_utility.format_error_backtrace);
  /*SCRIPT FOR HR.EMPLOYEES by user:admin */
   ADD (
    execute immediate v_ddl_cl;
    log('DDL executed successfully.');
    when others then
      log('ERROR:'||' '||SQLErrm||' '||dbms_utility.format_error_backtrace);
  /*SCRIPT FOR HR.COUNTRIES by user:admin */
   ADD (
    execute immediate v_ddl_cl;
    log('DDL executed successfully.');
    when others then
      log('ERROR:'||' '||SQLErrm||' '||dbms_utility.format_error_backtrace);
  return v_log_cl;


The GITORA_MODEL packages contain the DDL statements you commit to your Git repository for the schema they are in. You can edit them any way you’d like to change the DDL statements, call other functions and procedures etc… In other words, they are no different than any other package you are managing with Gitora.

GITORA_MODEL.doModel function executes the DDL statements stored in the package. You can use the doModel function to execute the changes in a target database. For example, after development is completed for a new version, you can pull the new version to from DEV to the TEST database and simply execute the GITORA_MODEL.doModel function to transfer the hard object updates to TEST.

Errors during its execution does not prevent the doModel function from executing remaning DDL statements. The function captures these errors and returns them as a CLOB value. This way, the same GITORA_MODEL package can be executed many times even if contains DDL statements that are previously executed in the target database (because these statements will silently fail). The GITORA_MODEL packages requires minimal maintanance, if any at all.

Non-Schema Objects and GRANTS

Not every database object has a schema. For example, TABLESPACES do not have an owner schema. DDL statements for non-schema objects are tracked by Gitora if the Oracle User(schema) who executed the statement is being managed by Gitora. For example, in the case above, if a DDL statement to create a TABLESPACE is executed by the Oracle User HR, then this DDL will be tracked by repo1.

Similarly, any GRANT and REVOKE statement will be tracked by the Gitora repo which is managing the Oracle User(schema).


You may not want to manage every object or object type with Gitora. Moreover, you may want to define complex rules to decide which object is managed by which repo. Customizing what types of objects Gitora should manage and in which repo is very easy using PL/SQL. Gitora uses four database level DDL triggers to detect DDL statement execution. By editing these triggers, you can define any kind of rule you like.

For example, a common rule used by Gitora customers is to allow developers to create tables for testing purposes. These tables do not need to be managed by Gitora. One of the easy ways of implementing this rule is to tell developers to use a certain prefix such as Z_ for test tables, and exclude any table DDL statement from executing Gitora API’s in the four DDL triggers if the table name starts with Z_.

Existing Customers

Gitora 3 is a free upgrade for all current customers. Please allow us 2-3 weeks to send us your new license scripts.

We’ll have more tutorials and webinars about Gitora 3 in the near future. Now download the Gitora 3 trial and start playing! 🙂

Agile Development with Oracle PL/SQL

Here is the number one question I receive from PL/SQL developers, DBA’s and IT managers who are implementing a version control solution for their Oracle Database:

Developer 1 (or Team 1) works on Feature A (or issue A, bug A, project A). Developer 2 works on Feature B. Both developers make many changes to the PL/SQL code and many commits to the version control repository. We move to testing. Based on the test results, even more commits are made by both developers. Now at the last minute, due to some reason (a last minute bug, a tactical change in direction, a change in strategy etc…) we decide to ship Feature B only. How can we remove Feature A from the source code easily? How does version control help in such a situation?

There are multiple answers to this question. Below, I’ll go over two possible solutions for two potential setups:

  1. If you are using one shared development database
  2. If you are using multiple development databases (or at least you are open to the idea.)

If You Are Using One Shared Development Database

Let’s assume that our shared development database is called DEV. In other words, both Feature A and Feature B are being developed in the same code base. Let’s also assume our only test database is called TEST.

Finally, assume that DEV is managed by Gitora DEV and TEST is managed by Gitora TEST.

In this case, the commit history in Gitora DEV has changes both for Feature A and B in a random order and looks something like this:

There is no easy way to remove the commits for Feature B in this setup. If the team decides to deliver Feature A to production but postpone the delivery of Feature B here are the steps they should follow:

  • Go over the commit history in Gitora DEV and find the commits that are related to Feature A.
  • Comment out/revert back/change the edits made for Feature A. Git will help the developers to see what’s changed, added, deleted and what the previous versions of code objects looked like.
  • Commit these new changes to Gitora DEV.

At this point the commit history in Gitora DEV looks something like this:

And finally, the next steps are:

  • Pull the new version from DEV to TEST using Gitora TEST.
  • Run tests on the TEST database. If there are no errors, deliver the new version to production. If there are errors, go to the second step, rinse and repeat until the desired outcome is reached.

In such a setup Gitora provides the following benefits:

  • Gitora keeps track of all changes made to the PL/SQL code in DEV, automatically. Developer 2 does not have to remember which PL/SQL objects she modified and what she modified in those objects.
  • Moving the code between DEV and TEST is as easy as clicking a button or making a PL/SQL function call. The team does not need to manually prepare scripts.

The downside of this approach is that it involves manual work which is error prone. Developer 2 still has to manually go through the commit history and make the changes to the source code in DEV to disable/remove Feature A. With only one shared development database ( i.e. development environment), there is no feasible way to easily remove Feature A.

If You Are Using Multiple Development Databases

Now things get more interesting. Below is a simplified workflow that uses only two development databases. This setup enables the IT team to deliver only Feature B to deployment without manually editing PL/SQL code objects to remove Feature A. (Obviously, giving each developer her own development environment is ideal but I understand that this might not be possible on day one in many IT departments. With that said, the PDB feature in Oracle 12c makes giving each developer her own environment much easier than before.)

Here is our initial set up:

  • Developer 1 works in the database DEV1 and Developer 2 works in the database DEV2 i.e. both developers (teams) have their own private environment while they are developing their respective features.
  • Our only test database is called TEST.
  • DEV1 is managed by Gitora DEV1, DEV2 is managed by Gitora DEV2 and TEST is managed by Gitora TEST.
  • DEV1, DEV2 and TEST start with the same version of the code which is stored in the master branch of their respective Git repositories. (In other words, DEV1/master and DEV2/master are clones of TEST/master)

Developer 1:

  • Using Gitora on DEV1, create a new branch named featureA (DEV1/featureA). Switch DEV1 to use this new branch.
  • Write code in DEV1
  • Test code in DEV1
  • Commit code changes to the DEV1/featureA (using Gitora DEV1). Go back to step 2 as many times as needed.

As an example, the Git history in Gitora DEV1 looks like this:

Developer 2:

  • Using Gitora DEV2, create new branch named featureB (DEV2/featureB). Switch DEV2 to use this new branch.
  • Write code in DEV2
  • Test code in DEV2
  • Commit code changes to the repository to DEV2/featureB (using Gitora DEV2). Go back to step 2 as many times as needed.

The Git commit history in Gitora DEV2 looks like this:


Moving Code Between Databases

At any point in time, if Developer 1 or Developer 2 decides to send code to TEST (for example, for integration testing purposes..), they follow the steps below.

Please note that in real world development, the workflows described below can be performed simultaneously in DEV1 and DEV2, in no particular order, any number of times until both features are ready to be deployed to production.

The steps below are merely a simplified example of how this workflow can take place.

Developer 1:

  • In our example , we assume that Developer 1 is the first developer sending her commits to TEST.
  • Using Gitora DEV1, merge DEV1/featureA to DEV1/master. (DEV1/featureA –> DEV1/master) In our workflow, as a general rule merges to the master branch are performed in the development database repositories not in the TEST database.)
    After the merge, commit history in Gitora DEV1 looks like this:

  • Pull master branch from Gitora DEV1 to Gitora TEST. (DEV1/master –> TEST/master). A “Pull” is simply a two step process of fetching a branch from a remote Git repository and then merging it to another local branch. In our example Gitora TEST fetches DEV1/master from Gitora DEV1 and merges it to TEST/master which we simply show as DEV1/master –> TEST/master.
    After the pull, commit history of both TEST and DEV1 looks like this:

Developer 2:

  • Pull master branch from Gitora TEST to the master branch in Gitora DEV2. (TEST/master –> DEV2/master). (In our example, this is necessary, because TEST/master has received new commits from DEV1/master.) After the pull, the commit history looks like this: (Remember, previously we pulled commits from DEV1/master to TEST/master and we also made commits to DEV2/featureB)

  • Using Gitora DEV2, merge DEV2/featureB to DEV2/master. (DEV2/featureB –> DEV2/master) After the merge, the commit history looks like this:

  • Using Gitora TEST, pull master branch from Gitora DEV2 to Gitora TEST. (DEV2/master –> TEST/master). After the pull, the commit history looks like this:

In other words, in its final state, the source code in the TEST database is a merge of Feature A and B where the commits in TEST/master branch are in a random order. In our example, the full commit history of DEV1, DEV2 and TEST repositories look like this:

Note that at all times, DEV1/featureA only contains the code for Feature A. Similarly, DEV2/featureB only contains the code for Feature B.

This workflow enables the IT team to exclude Feature A from the next deployment using Git commands at any point in time before going production.

To achieve this in our example, follow the steps below using Gitora:

  • Revert DEV2/master back to its initial state where no code for Feature B has been committed yet. (This uses the Git reset command.)

  • Merge DEV2/featureB to DEV2/master. (DEV2/featureB –> DEV2/master)

  • Reset TEST/master to its original state.

  • Finally, pull master branch of DEV2 to the master branch of TEST. (DEV2/master –> TEST/master)

After these steps are completed, the TEST database only contains code changes related to Feature B. We can use Gitora to extract a DDL script which contains only the changes made between the initial and final state of TEST/master and use this script to deploy Feature B.

You can also watch the video tutorial for this workflow below: (The only difference is that in the video the TEST database is called PREPROD.)

Gitora helps developers execute this workflow with a point&click GUI and PL/SQL API’s. Specifically:

  • Gitora keeps track of all changes made to the PL/SQL code in DEV1, DEV2 and TEST automatically.
  • Gitora updates the source code in the Oracle Database automatically when the executed Git command changes the files in the working directory.


  • Developers don’t have to remember which PL/SQL objects they modified and what they modified in those objects.
  • Moving the code between DEV1, DEV2 and TEST is as easy as clicking a button or making an PL/SQL function call. The team does not need to manually prepare scripts. Gitora can either generate the scripts or update the databases automatically.
  • Crucially, Gitora enables Developer 1 and Developer 2 switch between code branches automatically. (For example if the DEV1 database switches from featureA branch to the master branch, Gitora automatically updates the code in the DEV1 database to reflect this change.)

Download Gitora now and try this workflow in your environment.

Yalim K. Gerger

Gitora 2.1 is available with tagging support

We are happy to announce that Gitora 2.1 is available for download. Along with a few bug fixes, Gitora 2.1 enables PL/SQL developers to use Git Tags to label any commit point in the Git repository.

Tags can be used for a variety of use cases but the most common one is to label a Commit ID for specific versions of the code base such as tagging a specific commit with the label “Version 2.0”.

It is very easy to create tags in Gitora. Simply, go to the local commands menu, select “Create Tag” menu item under “Tags”.



A dialog shows up.

Create Tag Dialog

Enter the name of your tag (no spaces). Enter the commit ID you’d like to attach it to. If you’d like to attach your tag to the HEAD i.e. the most recent commit in the current branch, leave the Commit ID field empty. You may also use a branch name instead of an actual Commit ID.

Click OK to create the tag. If the tag is attached to a commit visible in the Gitora repository browser, it will show up in the Gitora Application.

Gitora Repository Browser

To delete a tag, select the Delete a Tag menu item under the Tags menu, enter the name of the Tag you’d like to delete and click OK.

Tags are available in Gitora 2.1 Professional Edition. Enjoy! 🙂

Kind Regards,
The Gitora  Team

Gitora Webinar Video and Slides

We hosted a webinar about Gitora last week. It received more than 400 signups and over 120 people have attended the event. The interest to the webinar was so high that we hit the 100 attendee limit of the webinar software we are using. Thanks to everyone who attended and helped us to do a better webinar with their questions and comments.

If you could not make it to the webinar, you can watch it or view the slides below. The webinar consists of two parts. In the first part, we talk about transition strategies to move an organization from manual version control for PL/SQL to version control with Gitora. In the second part, we showed the capabilities of Gitora with a live demo.


Installing Gitora Manually

We created a solid installer for Gitora which has a very high success rate. However, IT environment can be very complex and restrictive (and understandably so). So having an installer does not work for everyone and every organization.

Therefore, today we are making the Gitora 2.0 installation scripts available for download. Below are the steps you can follow to install Gitora 2.0 to your environment manually.

Installation of Middletier Components

  1. For Linux and Mac OS, install Git manually from For Windows, Git is already included to this setup.
  2. Move Gitora2 folder to the place you want to locate Gitora middle tier components.
    e.g /Users/username/
  3. For Windows, open fix_parameters_WINDOWS.bat to edit.
    For Mac OS, open to edit.
    For Linux, open to edit.
  4. Set GITORA_ROOT parameter to the absolute path of the Gitora2 folder from step 1..
    e.g /Users/username/Gitora2
  5. Set GITORA_DATABASE_CONNECTION_STRING parameter to the correct jdbc connection string to your database.
    e.g jdbc:oracle:thin:@
  6. For Mac OS and Linux, set GIT_EXECUTABLE parameter to the path of git executable.
    e.g. /usr/bin/git
  7. Open command line terminal and run fix_parameters_WINDOWS.bat for Windows, for MAC OS, for Linux.

Installation of Database Components

  1. Connect to the Oracle Database with the SYS user
  2. Run 01_SYS.sql
  3. Disconnect from SYS
  4. Connect to the database with the GITORA user
  5. Run 02_GITORA.sql
  6. Ensure that there are no invalid packages in GITORA schema.
  7. Create a row in table GITORA.T_TEMP_APPLICATION
  8. Copy the contents of Gitora.xml to this newly created row
  9. Issue a commit to save this row to the database.
  10. Run 03_GITORA.sql
  11. Disconnect from GITORA user
  12. Connect to the database with SYS user
  13. Open 04_SYS.sql and replace the two occurrences of @VERSIONCONTROL_HOST@ keyword with the IP address of your Gitora middle tier machine, where Gitora web server and middle tier components are installed. You need to ensure that your middle tier machine is accessible from database machine by checking network and firewall settings of both machines.
  14. For Windows, change the value of “folderSeparator” parameter from ‘/’ to ‘\’.
  15. Run 04_SYS.sql
  16. Disconnect from SYS.

Starting Up Gitora

  1. For Windows, run Gitora2/apache-tomcat-7.0.69/bin/startup.bat.
    For Mac OS and Linux, run Gitora2/apache-tomcat-7.0.69/bin/
  2. Open your browser and type http://[MIDDLE TIER IP ADDRESS]:7997/gitora/main.html name=Gitora

Generating a Diff Script in Gitora

Gitora 2.0 enables developers to generate a DDL script from the Git repository which can be used to synchronize source code between two databases. For example, this feature can be used to generate a script to syncronize a production database to the latest version of the source code. This tutorial explains how to use this feature in Gitora 2.0.

Open the Gitora Application. Select a Git repository. Next, click the Get Script button either from the menu bar Local Commands –> Utilities –> GetScript or from the tool bar.

Get Script

Alternatively, click the Get Script icon in the Local Commands toolbar section.

Get Script Button


The Get Script Dialog shows up.

Get Script Dialog

Enter the Starting Git Commit ID and the Destination Git Commit ID. Use the keyword HEAD if you’d like to use the latest commit in the current active branch as the Destination Commit ID.

Click the Download DDL Script button. Gitora will generate a DDL script which, if executed, will syncronize a schema (or a group of schemas) which is currently at the Starting Commit Point ID, to the Destination Commit Point ID.

For example, this feature can be used to apply the latest version of the source code to a production database. If the production database is at Git Commit Point A and the new production-ready version of the source code is at Git Commit Point B, a developer can enter A as the Starting Commit ID and B as the Destination Commit Point ID and then execute the generated script in the production database.

Introduction to Gitora, Git for PL/SQL Developers

This document explains the core concepts in Gitora and how developers can use them to control the revisions they make to their Oracle database objects.

Gitora enables developers perform regular version control tasks on the source code of their applications. Gitora supports every database schema object. It can perform Git commands on objects that can be created using the CREATE OR REPLACE command, namely; Packages, Views, Procedures, Functions, Triggers, Types and Synonyms. It can track every DDL performed on other database object such as tables, indexes etc…

Behind the scenes, Gitora seamlessly integrates with Git, the prominent distributed version control system used by millions of developers worldwide. Gitora supports the following Git operations on the source code it manages:

  • Reset
  • Create Branch
  • Change Branch
  • Merge Branch
  • Fetch
  • Pull
  • Push

Gitora Web App

Gitora has both PL/SQL API’s and a web application to help developers manage their PL/SQL code using Git. Using Gitora Web App developers can:

  • Perform the supported version control functions using a point&click interface.
  • Check out database objects for editing
  • Browse the source code in the Git repository
  • Manage Git repositories.
  • Manage users

Creating A Version Control Repository

Open Gitora Web App and select File-> New Repository from the menu bar. The Create New Repository Dialog shows up.

Enter a name for your repository (A Gitora repository can contain PL/SQL objects from any database schema.) Note that the Gitora Web App makes the new repository you created the active one and the repository viewer focuses on it.

Adding Database Objects to a Gitora Repository

In order to be able to perform version control tasks with a database object, it must be added to a Gitora repository.

To add database objects to a Gitora repository click the “Add/Remove Database Objects” icon on the toolbar.

Add/Remove Database Objects

The “Add/Remove Database Objects” Dialog shows up.


To add a database object to the Gitora repository, select the schema the object is in. Next, select the type of the object. Gitora supports the following object types: Procedure, Function, Package, View, Trigger, Type and Synonym.

Finally, select one or more objects from the list of available ones and add them to the list of managed objects. The dialog supports registration of multiple types of objects in one step. Click “OK” to save the changes.

A Gitora repository can manage database objects in multiple schemas. To add database objects from another schema simply change the schema name selected in the dialog’s combo box and continue as described above. Please note that the Gitora Web App will ask to save the modifications prior to changing the selected schema.

Collaboration vs. Parallel Development

Unlike middle tier (Java, PHP etc…) or client side programming language code units (JavaScript, Objective-C etc..) PL/SQL code units do not reside in private files on a developer’s computer. They are globally available to every developer who has access to the database with the appropriate privileges. Therefore, PL/SQL developers mostly collaborate on the same PL/SQL code units (Packages, Procedures, Functions etc…) using a check-out mechanism to prevent them from overriding each other’s modifications.

When working together, developers of other programming languages have a different approach. They work on the same logical code unit but they always edit different copies of the same logical code unit. In most cases it is impractical for PL/SQL developers to set up their own private environments in which each developer has a private copy of the PL/SQL code units she is working on. Therefore, Gitora features a check-out mechanism to better fit into the regular work routine of PL/SQL developers. This enables a team of developers to collaborate on one branch of the application without stepping on each others toes.

More importantly however, Gitora also supports a workflow in which each developer works in her own environment and with her own database objects (similar to a middle tier or client developer). This way, developers can freely modify the same logical code units (but different copies) and merge their changes at a later point in time.

Editing a Database Object Managed by Gitora

Developers may continue using their favorite PL/SQL editor to edit database objects managed by Gitora. Since Gitora is implemented at the database level, it works with any editor.

Once a database object is part of a repository, Gitora will only allow changes to it from database sessions which have a logged in Gitora user and if the database object is not already checked out by another Gitora user.

Use the following API’s in the API_GITORA package to sign in to Gitora with your Gitora user name and password.

login(in_user_cd varchar2, in_password_tx varchar2) :signs in to Gitora with a valid Gitora user name and password

logout;signs out of Gitora

When a developer saves a PL/SQL objects to the database, Gitora automatically attempts to check out the object if the database session has a logged in Gitora user.  If the object is already checked out by another developer, Gitora prevents the save with an appropriate error message.

Developers may also use the Gitora Web App to check out a database object from the navigation tree by right clicking to it and selecting the check out menu item from the pop up menu.

Checking Out a Database Object

Gitora Web App presents a green lock icon on database objects checked out by the logged in developer and a red lock icon on database objects checked out by other developers.

Committing Database Object Modifications

At any time the developer can view the list of objects she checked out from the “Local Commands -> My Objects” menu item.

My Objects

Alternatively, she can use the “Commit Changes” icon in the toolbar to access the same dialog.

My Objects on the Toolbar

The “My Objects” dialog has two tabs. The “All Objects” tab shows the list of every database object in the current repository that is checked out by every developer. The “My Objects” tab shows only the objects the logged in developer checked out.

The developer can review changes made to each object by clicking the associated Diff link. She can also choose to include/exclude each object from the current commit by using the Include? checkbox.

Clicking the “Commit” button opens a the “Commit Message” dialog. Gitora requires a developer to enter a short description of the changes she is attempting to commit. This description comes in very handy when going over the history logs.

Commit Message Dialog

Once the Git commit is finished, Gitora displays the message it retrieves from the Git server. This message gives a summary of the updates made to the Git repository.

After the commit completes, objects included in the commit are automatically released and are no longer checked out by the developer.

Please note that there is no API in the api_gitora package to issue a Git commit. Commits can only be issued via the Gitora Web App.

Releasing an Object

If the developer wants to remove the her edit lock on an object she checked out, she can do so right clicking the object in the navigation tree and clicking the Release menu item.

Resetting to a Commit ID

If a developer wants to cancel her changes in an application’s current branch and bring it to a state it was at a certain point back in time, she can do so by using the “Reset to Commit ID” menu item.

The “Reset to Commit ID” operation needs a valid Commit ID to function. The Git Repository gives a unique ID to each commit issued by a developer. The developer can browse the Git repository using the “Repository” tab to determine the Commit ID she wants the application to revert back to.

Commit ID

To move back the application to a commit ID, click the “Local Commands -> Reset to Commit ID” menu item.  The “Reset” dialog shows up. Paste the Commit ID value to the field named Commit ID in the and click the“Resert” button. The code base goes back to the state it was at that Commit ID and Gitora displays the message it received from the Git Server.

As a shortcut, you can revert to the previous state of the repository by entering HEAD@{1} as the Commit ID.

Please note that the reset command will only update the PL/SQL objects in the repo.

Creating a Branch

Branching is a very powerful feature of version control systems that enables developers to work on multiple versions of a code base easily. For example, a developer can work on the master branch to fix bugs that are reported from the production environment and release maintenance versions while developing a new feature in the dev branch. The deployed new maintenance versions from the master branch never includes the code written in the dev branch.

To create a new Branch click the “Local Commands -> Create Branch” menu item. A dialog show up.

Enter a name for the new branch. Enter the name of another branch or a Commit ID as the starting point of the new branch. Click the “Create Branch” button to create the new branch. Once it is created, the code base automatically switches over to the newly created branch.

Please note that there must not be any checked out objects in the repository for Gitora to be able to create a new branch.

Changing Branches

In order to change the current branch of the repository open Gitora Code Manager, select the “Local Commands -> Change Branch” menu item. A dialog shows up.

Select the branch to switch to and click the “Change Branch” button. The code base in the Oracle Database gets updated to show its state in the selected branch. Please note that there must not be any checked out objects in the code repository for Gitora to be able to switch to another branch.

Merging a Branch to another Branch

Creating and switching between branches would not be meaningful unless Gitora also enabled merging of a branch to another. For example, once the development on the dev branch is finished, developers should be able to move the changes to the master branch of the code base. This is called a merge.

To start a merge click the “Local Commands -> Merge Branch” menu item. A dialog shows ups asking the source branch for the merge operation. The destination branch is always the current branch the code base is on.

Click the “Merge” button to start the merge operation.

During the merge operation, Gitora carries over the changes made in the source branch to the destination branch. In some cases Git may not be able to figure out the right operation to perform to bring over a particular change. These cases are called conflicts.

A conflict may occur if;

  • An object deleted in the source branch is modified in the destination branch.
  • An object is modified in the source branch and in the destination branch, and Git cannot consolidate these modifications. (For example, in both branches the same line of code in a PL/SQL procedure is modified. There is no way a version control system can figure out the right way to consolidate these two changes.)
  • An object modified in the source branch is deleted in the destination branch.
  • A newly created object in source branch and a newly created object in destination branch have the same name.

If there is a conflict in a database object after a merge, Gitora does the following in the destination schema:

  • It creates the database object in an uncompiled form with changes from both source and destination in it.
  • It creates the database object with “MINE” suffix in its name which represents the object in the destination repository.
  • It creates the database object with “THEIRS” suffix in its name which represent the object in the source repository.

The developer who started the merge is responsible to resolve the conflicts in the database objects that might occur after a merge operation.

Gitora provides an easy to use merge wizard to the developer so that she keep track of and mark the conflicts as resolved. The merge wizard shows a commit screen after all the conflicts are resolved. If there are no conflicts after a merge operation, the merge wizard does not show up.

Until the merge conflicts are resolved, Gitora does not allow developers to modify the code base subject to the merge operation.

Please note that the developer is also responsible to fix the compilation errors that might occur after a merge operation which are different than the conflicts. There might be compilation errors after a merge even if there are no conflicts.