Tag Archives: documentation

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

gitora-tags-menu

 

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.

 

Gitora, Version Control for PL/SQL from Gitora

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 https://git-scm.com/. 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 fix_parameters_MAC.sh to edit.
    For Linux, open fix_parameters_LINUX.sh 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:@192.168.1.99:1521:orcl
  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, fix_parameters_MAC.sh for MAC OS, fix_parameters_LINUX.sh 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/startup.sh
  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.

How to Connect to Remote Databases

Gitora 2.0 enables developers to clone, fetch and pull code from remote Oracle Databases. An important step to use these features is to establish a connection between source (i.e. remote) and destination Gitora installations This tutorial explains how to create this connection.

1. Install Gitora to Source and Destination Databases

In order to be able to perform remote database operations, Gitora must be installed to both databases.

2. Enter the Connection information for the Remote Gitora Installation

Open the Gitora Application for the destination database. Under the menu bar click File –> Manage Remote Gitora Connections.

Menu Bar

The Remote Connections Dialog shows up.

Remote Gitora Connection Management

Click the + button end enter the following information:

Alias: A descriptive name for the Gitora Server of the source database. (No spaces or special characters.

Protocol: http

IP: The IP of the Gitora Server of the source database. This information can be obtained from the URL of the Gitora Application of the source database.

Port: The port of the Gitora Server. This information can be obtained from the URL of the Gitora Application of the source database.

Context: If the URL of the Gitora Application for the source database is http://192.168.15:8080/GitoraForSourceDB/main.jsp?name=Gitora then the value for context is GitoraForSourceDB

Root Folder: Name of the database schema of the Gitora installation in the source database, in lowercase.

Click OK to save the changes.

Your Gitora installation (destination) is now ready to clone, fetch and pull from the remote (source) Gitora installation.

Important Note: Gitora 2.0 assumes the presence of a secure network. In other words, do not use public IP addresses for connecting to remote Gitora installations. Authentication to connect to a public Gitora installation will be implemented in a future 2.x version.

 

 

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.

NewRepo

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.

NewRepoCreated

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