Monthly Archives: October 2014

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 that can be created using the CREATE OR REPLACE command, namely; Packages, Views, Procedures, Functions, Triggers and Synonyms.

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 (Called Revert to Commit Point in Gitora)
  • Create Branch
  • Change Branch
  • Merge Branch
  • Clone
  • Fetch
  • Pull

Gitora Code Manager

Gitora has both PL/SQL API’s and an application built with Formspider to help developers manage their PL/SQL code using Git. Using Gitora Code Manager 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

Gitora Code Manager


Creating A Version Control Repository

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


Enter a name for your repository and an optional default database schema the repository works with. A Gitora repository can contain PL/SQL objects from any database schema. Providing a default schema helps to save a few clicks if most of the PL/SQL units in the repository will be in the same schema. Click OK. Note that the Git Code Manager 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.

Add/Remove Database Objects Dailog addremoveobjects

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 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 Code Manager 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. Please see Cloning an Application section for more information on this subject.

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 user.

Gitora has an API package called api_gitora.

The API’s in api_gitora are as follows:

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

checkOutDBObject(in_schema_cd varchar2, in_type_cd varchar2, in_name_tx varchar2); Locks the specified database object for the logged in Gitora user.

releaseDBObject(in_schema_cd varchar2, in_type_cd varchar2, in_name_tx varchar2); Releases the lock on the specified database object owned by the logged in Gitora user.

addDBObject(in_schema_cd varchar2, in_type_cd varchar2, in_name_tx varchar2, in_repoName_tx varchar2); Adds a database object to a Gitora repository.

There are four more API’s in api_gitora that are used by Gitora internally to manage database objects.Use the TYPE_FUNCTION, TYPE_PACKAGE, TYPE_PROCEDURE, TYPE_SYNONYM, TYPE_TRIGGER, TYPE_VIEW constants in the api_gitora package as input values to the in_type_cd parameter in the API’s.

Use the checkOutDbObject API to check out a database object. During a save, Gitora automatically attempts to check out a database 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 Code Manager and 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 Code Manager 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 “Version Control -> My Objects” menu item in the Gitora Code Manager.

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 “Commit” button at the bottom commits the developer’s changes to the Gitora repository.

My Objects Dialog

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 the developer checked out are automatically released.

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 Code Manager.

Releasing an Object

If the developer wants to remove the edit lock on an object she checked out, she can do so by attempting to release the object. For an object to be released, it must not have been edited by the developer. If an object is edited, the only way to remove the lock is to issue a commit.

To release an object, click “Version Control -> My Objects” menu item or the “Commit Changes” button on the toolbar. Next, click the “Release” hyperlink next to the object. This causes Gitora to attempt to release the edit lock on the object. If the current definition of the object is the same as the last committed version, then the release succeeds.

Reverting to a Commit Point

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 “Revert to Commit Point” option.

The “Revert to Commit Point” 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 “Version Control” tab in the Formspider IDE. Using the “Version Control” tab she can determine the Commit ID she wants the application to revert back to.

Commit ID

To move back the application to a commit point, click the “Version Control -> Revert to Commit Point” menu item from the IDE menu bar.  The “Revert” Dialog shows up. Paste the Commit ID value to the field named Commit ID in the and click the“Revert” 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.

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 “Version Control -> 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 “Version Control -> 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 “Version Control -> 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 Gitora 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 server 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.

Cloning a Repository

Gitora allows each developer to work on its own private copy of the code base. This way of working is similar to how middle tier and client side developers build applications where everyone has its own private copy of the code base.

To clone a repository, click the “Version Control -> Clone” menu item. A dialog shows up.

Clone Dialog

Enter a name for the new repository which is going to be created as part of the cloning and optionally a default datasource schema name.

Cloning creates a new copy of the repository based on the last commit its current branch is on.

Since clone operation copies every database object being managed by the original repository, to the clone repository, it must know the schema names it needs to use to create the new database objects. Therefore, it lists the schema names of the database objects in the original repository and asks the developer to provide a destination schema for each one of them.

For example, assume that the developer is cloning a repository named RepoOne with the default datasource schema SchemaOne. Further assume that the new name for the clone repository is CloneRepoOne and the new datasource schema for ClonerepoOne is TargetSchemaOne. If RepoOne is managing Database Objects in SchemaOne and SchemaTwo, the clone dialog asks for two destination schema names, one for SchemaOne and one for SchemaTwo such as TargetSchemaOne and TargetSchemaTwo. The clone operation copies all the Database Objects in SchemaOne to TargetSchemaOne and  the ones in SchemaTwo to TargetSchemaTwo. Further, clone operation ensures that the copied database objects are being managed by CloneRepoOne . This way it creates a completely new copy of RepoOne named CloneRepoOne that does not share any dependencies with RepoOne.

Fetching Branches from Another Application

Cloning a repository only makes sense if it can later be merged to the original. The fetch operation is the first step to achieve this goal. Fetch retrieves the branches from another repository to the current one open in the Gitora Code Manager. These new branches can be used in a merge operation.

To fetch from another repository, click “Version Control -> Fetch” menu item. The fetch dialog shows up. Select the repository to retrieve the branches from and click “OK”.

Fetch Dialog

Pulling from Another Application

Performing a pull is identical to performing a fetch and a merge. In other words, a pull retrieves branches from another repository and merges the selected branch to the current branch of the repository open in the Gitora Code Manager. Click the “Version Control -> Pull” menu item in the IDE menubar. The pull dialog shows up. Select the repository and the branch to pull from and click “OK”.

Pull Dialog