Managing Tables with Single Schema Repos

This article describes how you can track schema changes with a Single Schema Repo (SSR). If you haven’t done so already, we recommend you to read this article first, which explains how Gitora manages tables.

Terminology

In Gitora parlance, any object that can be created with the CREATE OR REPLACE syntax is called a soft object. Objects such as tables, sequences and materialized views which cannot be created with the CREATE OR REPLACE syntax are called hard objects.

Altough one repo can store both hard and soft objects without any issues, we recommend users to store hard and soft objects of a project in separate repos.

Managing Schema Changes with Gitora

Gitora repos can track all changes to hard objects and SSR’s are no different. However, an SSR can only track the hard objects changes in the schema it is associated to.

You can enable this feature by checking the Manage Schema Changes checkbox while creating or editing the SRR.

If a schema is managed by a Gitora repo, Gitora will not allow any user to create or edit any hard object in the schema without connecting to Gitora first.

An SSR can only manage the changes in the schema it is associated to.

A schema can only be managed by one repo.

The DDL statements captured by an SSR will be committed to Git without the schema prefixes.

In the example below, we add a column named DEPARTMENT_CD to the HR.DEPARTMENTS table. The DDL statement in Gitora does not have the schema prefix HR.

After the commit, the DDL statement shows up in the Git repo. It is appended to the previous list of committed DDL statements. You can access committed DDL statements to Gitora by clicking the Schema Changes tree node:

Moving Hard Object Changes Between Schemas

Single Schema Repos enable developers to move hard object changes among schemas easily. This is best explained with a simplified example. A real world situation will probably be more complex but the principles will remain the same.

Assume that HR is our master schema and HR_HARD_OBJECTS_REPO is the single schema repo where we manage the hard object changes in the HR schema. Further, assume that two developers Joe and Jane are working in the same database but in their own schemas named HR_JOE and HR_JANE respectively. They can manage hard object changes with the following setup:

  1. Create two single schema repos, one for Joe and one for Jane, named HR_JOE_HARD_OBJECTS_REPO and HR_JANE_HARD_OBJECTS_REPO respectively. Associate the HR_JOE_HARD_OBJECTS_REPO with HR_JOE and HR_JANE_HARD_OBJECTS_REPO with HR_JANE. Do NOT check the Manage Schema Changes checkbox for each repo during creation.
  2. Pull from HR_HARD_OBJECTS_REPO to HR_JOE_HARD_OBJECTS_REPO and to HR_JANE_HARD_OBJECTS_REPO.
  3. Open HR_JOE_HARDOBJECTS_REPO in Gitora. From the menu bar, select to Git–>Repo–>Edit Repo menu item and check the Manage Schema Changes checkbox. Repeat this step for HR_JANE_HARDOBJECTS_REPO as well.

Now that our developers’ repos are initialized, they can pull hard object changes from each other’s repos. Not having the schema prefixes in the DDL statements makes executing these DDL statements in their own schema easier.

Obviously, in a real world scenario this flow will be more complex. It will most likely involve pushing to and pulling from repos in GitHub, GitBlit or similar services. Developers may also need to manually edit the document that contains the schema changes.

Fortunately, Gitora works seamlessly with GitHub GitLab and similar services. It also allows developers to edit the schema changes document and commit their changes right within the Gitora app. Finally, after a pull, developers can compare old and new versions of the schema changes document to determine which DDL statements they need to execute in their own schema. This comparison can be done in the Gitora application, as well.

For development teams, Gitora makes managing schema changes much easier. It helps the teams use Git with their code base and implement modern development workflows to increase productivity and stay compliant.

Introducing Gitora 6

We are happy to annouce that Gitora 6 is available for download.

With Gitora 6, developers can work on the same code base (i.e. a package, procedure etc…) in the same database without blocking each other.

Many development teams use a single database for development. Many of them use the same database for testing, as well. They achieve this by using different schemas for different purposes. Gitora 6 enables these teams to create Git repos for these schemas and pull updates between them.

With Gitora 6, you can even create a different schema for every developer and have them merge their code using Git.

Gitora 6 enables you to implement any modern development workflow in a single database.

How does Gitora 6 work?

Gitora 6 introduces a new repo type called Single Schema Repo (SSR). As its name suggests an SSR manages database objects from a single schema. The DDL scripts in SSR’s don’t contain the schema prefixes so that Gitora can execute them in other schemas in the same database.

This enables developers to work on the same package, procedure, function, view etc… (i.e. anything that can be created with the CREATE OR REPLACE command) at the same time, in the same database in different schemas.

An Example

Let’s go through an example: Let’s assume that the team is working on a logistics software and have a schema named LOGISTICS that stores all their database objects. The team can create a schema (or already have one) called LOGISTICS_TEST in the same database. Here are the steps the team needs to follow so that they can pull their changes to LOGISTICS_TEST.

  1. Create a single schema Gitora repo that manages the LOGISTICS schema. Let’s call it the REPO_LOGISTICS.
  2. Add all relevant database objects in the LOGISTICS schema to the LOGISTICS_REPO.
  3. Create another single schema Gitora repo that manages the LOGISTICS_TEST schema. Let’s call it the REPO_LOGISTICS_TEST
  4. Pull from the REPO_LOGISTICS to REPO_LOGISTICS_TEST

That’s it. That’s all there is to it. From this point on, any change you make to the code in the LOGISTICS schema can be pulled to the LOGISTICS_TEST schema using Gitora (and vice versa).

Single Schema Repos can also be used to create separete development environments in the same database for every developer in the team.

Multiple Developers, Same Database

Assuming we already have the LOGISTICS schema and the REPO_LOGISTICS repo from the previous example, here is how that would work:

  1. Create a schema for each developer: LOGISTICS_JOE, LOGISTICS_MARY, LOGISTICS_PAUL.
  2. Create a single schema Gitora repo for each schema. Let’s call them REPO_LOGISTICS_JOE, REPO_LOGISTICS_MARY, REPO_LOGISTICS_PAUL respectively.
  3. Pull from the REPO_LOGISTICS to REPO_LOGISTICS_JOE, REPO_LOGISTICS_MARY and REPO_LOGISTICS_PAUL.

From this point on, all three developers can work in their own schema and edit any package, procedure, view etc… freely, without overwriting each other’s changes or being affected by them. Using Gitora, they can create new branches in their own repo, for features or bugs they work on without affecting anyone else.

When the time comes to put it all together, they can use Gitora to merge their changes.

We wrote a few articles to get you started:

Creating Single Schema Repos.

How to implement agile development in a single database

How to manage changes to tables with Single Schema Repos

Before Gitora 6, agile database development with Gitora required multiple databases to implement. With Gitora 6 you can achieve it in a single database.

We are incredibly excited to release Gitora 6. We believe it will bring a massive productivity boost to Oracle database development teams worldwide. We can’t wait for you to try it.

Gitora 6 is available now. You can download it from this link.

Agile Development with a Single Database

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 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 schema in a single database
  2. If you are using multiple development schemas in a single database (or at least if you are open to the idea.)

If You Are Using One Shared Development Schema

Let’s assume that our development database is called DEV and the shared development schema in DEV is called HR. In other words, both Feature A and Feature B are being developed in the same code base. Let’s also assume that there is no other database for testing. We test in DEV in the schema called HR_TEST.

Assume that HR and HR_TEST schemas are managed by two Gitora single schema repos (SSR) repos named HR_REPO and HR_TEST_REPO, respectively.

In this case, the commit history in HR_REPO 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 HR_REPO 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 HR_REPO.

At this point the commit history in HR_REPO looks something like this:

And finally, the next steps are:

  • Pull the new version from HR_REPO to HR_TEST_REPO using Gitora.
  • Run tests on the HR_TEST schema. 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 the HR schema, 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 HR and HR_TEST schemas is as easy as clicking a button. 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 the HR schema to disable/remove Feature A. With only one shared development database ( i.e. development environment), there is no easy way to remove Feature A.

If You Are Using Multiple Development Schemas

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.

Here is our initial set up:

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

Obviously, all Git operations mentioned below are executed using Gitora. Gitora takes care of updating the database code after a Git command is executed.

Developer 1:

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

As an example, the commit history of DEV1 looks like this:

Developer 2:

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

The Git commit history in Gitora DEV2 looks like this:

Moving Code Between Schemas

At any point in time, if Developer 1 or Developer 2 decides to send code to the HR_TEST schema (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 repos, 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 takes place.

Developer 1:

  • In our example , we assume that Developer 1 is the first developer sending her commits to the HR_TEST schema.
  • Merge DEV1/featureA to DEV1/master. (DEV1/featureA –> DEV1/master)
    After the merge, commit history in DEV1 looks like this:
  • Pull master branch from DEV1 to 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 a local branch. In our example TEST fetches DEV1/master from the DEV1 repo 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:

Now it is time for Developer 2 to send her changes to the HR_TEST schema. She does the following steps:

  • Pull master branch from the TEST repo to the master branch in 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)
  • Merge DEV2/featureB to DEV2/master. (DEV2/featureB –> DEV2/master) After the merge, the commit history looks like this:
  • Pull master branch from the DEV2 repo to the TEST repo. (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 HR_TEST schema (and in the TEST repo) is a merge of Feature A and B. 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.

Removing Feature A from the Deployment

This workflow enables the IT team to exclude Feature A from the next version of the software at any point in time before deploying it to the production environment.

To exclude Feature A from the deployment in the example above, follow the steps below:

  • 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 HR_TEST schema only contains code changes related to Feature B. We can use Gitora to extract a DDL script from HR_TEST which contains only the changes made between the initial and final state of TEST/master and use this script to deploy Feature B to the production environment.

Gitora helps developers execute this workflow with a point&click GUI:

  • Gitora keeps track of all changes made to the PL/SQL code in HR_DEV1, HR_DEV2 and HR_TEST schemas automatically.
  • Gitora updates the source code in the Oracle Database automatically when the executed Git command changes the files in a Git working directory.

Therefore:

  • Developers don’t have to remember which PL/SQL objects they modified and what they modified in those objects.
  • Moving the code between HR_DEV1, HR_DEV2 and HR_TEST is as easy as clicking a button. 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 to switch between code branches automatically. (For example if the DEV1 repo switches its active branch from featureA to the master branch, Gitora automatically updates the code in the HR_DEV1 schema to reflect this change.)

Download Gitora now and try this workflow in your environment.

How to Create a Single Schema Repo

This article shows how you can create a Single Schema Repo (SSR) wit Gitora 6.

Sign in to Gitora. Next click Git –> Repo –> Create Repo –> Single Schema Repo.

The Single Schema Repo Creation Dialog show up.

  1. Enter a unique repo name. (In this example, we’ll call it SSR_1)
  2. Select the schema the SSR is associated to. (In this example it will be associted to the HR schema)
  3. Leave the Manage Schema Changes unchecked for now.
  4. Click save.

The repo SSR_1 is created. SSR_1 can only manage objects that are in the HR schema. (Other than this limitation, the SSR_1 repo works just like any other repo.)

Adding Database Objects To a Single Schema Repo

This process is the same as adding objects to a regular Gitora repo (which is now called a Multi Schema Repo MSR)

Select the SSR_1 repo from the example above from the combobox if it is not already selected.

In the menu bar, click to Git –> Add/Remove Objects. The Add or Remove Database Objects Dialog shows up.

Select the database objects you’d like to manage with this repo and click Save. Use the Object Type dropdown to switch between different object types.

Note that the schema dropdown is disabled because we are working with a Single Schema Repo.

Commit, Reset, Create/Change/Merge/Delete Branch Operations

These commands work just like they do for regular repos. There are no changes.

Pulling from Other Repos

In Gitora 5, repos could only pull from repos managing objects in other databases. In Gitora 6, single schema repos can also pull from other single schema repos managing objects in the same database.

The example below shows how you can pull from one SSR to another managing objects in the same database. All three pull operations (i.e. Pull, Fetch&Merge, Switch to Branch in Another Repo) work the same way.

Let’s assume we have two schemas named LOGISTICS and LOGISTICS_TEST and two SSR’s named REPO_LOGISTICS and REPO_LOGISTICS_TEST, managing these schemas, respectively. Read this article to learn how you can initialize these repos, correctly.

Here are the steps to pull from REPO_LOGISTICS to REPO_LOGISTICS_TEST.

  1. Open the REPO_LOGISTICS_TEST repo in Gitora.
  2. From the menu, select Git –> Pull

The Pull from Another Repo to Active Branch Dialog shows up.

3. Select the name of the single schema repo you want to pull from. (In our case, it is the LOGISTICS_REPO.)

4. Type the name of the branch you want to pull from.

5. Click the Pull button.

That’s it. All changes in LOGISTICS_REPO are now merged to the LOGISTICS_REPO.

FAQ

Can I create multiple Single Schema Repos that are associated to the same schema?

Yes. You can create multiple SSR’s that are associated to the same schema. This is especially useful in dividing the database objects in the schema into multiple logical groups.

Can Single Schema Repos pull from other databases?

Yes. It works exactly like it does in Gitora 5. In the Gitora app, select Git–>Other Databases–>Pull from the menu bar.

Can I track changes to tables with a Single Schema Repo?

Yes. Just like with regular repos, the same SSR can be used for both managing packages, procedures etc… and tracking table DDL’s. A single schema repo can only track the table changes in the schema it is connected to. Please read this article to learn how Schema Management in Gitora works and read this article to learn how an SSR manages the schema it is assoicated to.

How to Pull/Push using Gitora

Gitora enables Oracle developers to pull code from other databases managed by Gitora with a single click. It also enables them 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:

Moving Code from one Database to Another Using Gitora

Gitora 5 can manage any number of databases. It also enables these databases to pull code from each other. This makes moving code in your delivery pipeline (from dev to test, from test to preprod etc…) much less error prone and easier.

Open the Gitora app. Select the repo you want to pull to from the main select box.

In order pull code from another database managed by Gitora, click the “Git->Other Databases -> Pull” menu item. The Pull Dialog shows up.

Select the database you want to pull from. Next choose a repo and the branch.

In the example above, we are connected to our TEST database. We are pulling from the DEV database the MyNewRepo repo’s master branch. Any code changes that exist in the database objects that are part of MyNewRepo’s master branch (but don’t exist in TEST) will move to the TEST database after clicking the Pull button.

Pull is the simplest and most common use case. It moves the latest version of a code base from one database to another. Gitora also supports more sophisticated workflows. For example, you can move the code at a specific commit ID on a specific branch from one database to another database.

To achieve this click “Git->Other Databases->Fetch and Merge” menu item. The Fetch and Merge Dialog shows up. To further extend the example above, using this dialog, you can specify which commit ID you want to fetch from the other database. The example below fetches and earlier commit ID from the MyNewRepo’s master branch in DEV. (Pull always fetches the current code in the DEV database.)

Finally, we may want to fetch a new branch in another database that does not exist in the database we are connected to. For example, we may want to test a new feature developed in the feature branch FEATURE1. To test this feature, we need to pull it to the TEST database. To achieve this, click “Git->Other Databases-> Switch to Branch in Another Database” menu item. A Dailog shows up. Enter the database, repo and the branch name you want to bring over to the database you are connected to. In the example above, we are brining the FEATURE1 branch from MyNewRepo in DEV to the TEST database.

Pull from/Push to Remote Repos

In the Gitora web application, click the Settings –> Manage Remote Repos from the menubar.

The Manage Remote Repos page shows up.

Remote Git Repositories Dialog

Click the add button. The Add Remote dialog shows up. 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: https://github.com/[github user name]/[gitreponame].git

Moving Code from Remote Repos to Databases using Gitora

Pulling from remote repos work the same way as pulling from other databases. Please note that in order for Gitora to successfully pull from a remote repo and update the database the structure, the remote repo must be either created by Gitora initially or the structure, folder and file names of the repo must be as if they are created by Gitora.

Pushing to a remote Git Repo

Open the Gitora app, select the repo you’d like to push from the main select box. Netx, click Git->Remote->Push. 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 the push 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.)

ALTER TABLE COUNTRIES MODIFY (COUNTRY_NAME VARCHAR2 (200))

ALTER TABLE EMPLOYEES ADD (MIDDLE_NAME VARCHAR2 (25))

ALTER TABLE COUNTRIES ADD (CURRENCY_NAME VARCHAR2 (200))

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:

CREATE OR REPLACE 
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
  begin
    v_log_cl:=v_log_cl||in_text_cl||chr(10);
  end;
begin
  /*GITORA GENERATED COMMENT. DO NOT EDIT OR REMOVE. ONLY WRITE CODE UNDER THIS LINE.*/
  null;
  
  /*SCRIPT FOR HR.COUNTRIES by user:admin */
  begin
    v_ddl_cl:='ALTER TABLE COUNTRIES 
   MODIFY (
    COUNTRY_NAME VARCHAR2 (200)
  
   )
  ';
    log(v_ddl_cl);
    execute immediate v_ddl_cl;
    log('DDL executed successfully.');
  exception
    when others then
      log('ERROR:'||' '||SQLErrm||' '||dbms_utility.format_error_backtrace);
  end;
  
  /*SCRIPT FOR HR.EMPLOYEES by user:admin */
  begin
    v_ddl_cl:='ALTER TABLE EMPLOYEES 
   ADD (
    MIDDLE_NAME VARCHAR2 (25)
   )
  ';
    log(v_ddl_cl);
    execute immediate v_ddl_cl;
    log('DDL executed successfully.');
  exception
    when others then
      log('ERROR:'||' '||SQLErrm||' '||dbms_utility.format_error_backtrace);
  end;
  
  /*SCRIPT FOR HR.COUNTRIES by user:admin */
  begin
    v_ddl_cl:='ALTER TABLE COUNTRIES 
   ADD (
    CURRENCY_NAME VARCHAR2 (200)
   )
  ';
    log(v_ddl_cl);
    execute immediate v_ddl_cl;
    log('DDL executed successfully.');
  exception
    when others then
      log('ERROR:'||' '||SQLErrm||' '||dbms_utility.format_error_backtrace);
  end;
  /*GITORA GENERATED COMMENT. DO NOT EDIT OR REMOVE. ONLY WRITE CODE ABOVE THIS LINE.*/
  return v_log_cl;
end;
end;

The GITORA_MODEL Package

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

Customization

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

This articles is about agile development using multiple (pluggable) databases. If you are trying to implement an agile workflow using a single database please read this article.

Here is the number one question we 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 we decide to ship Feature B only. How can we remove Feature A from the source code easily? How does Gitora 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 and TEST are managed by Gitora. All version control operations are done with Gitora.

In this case, the commit history of the DEV repo 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 of the DEV repo 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 the DEV repo.

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

And finally, the next steps are:

  • Pull the new version from DEV to 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, wash, 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 the DEV database, automatically. Developers do not have to remember which PL/SQL objects they modified and what they modified in those objects.
  • Moving the code between DEV and TEST is as easy as clicking a button. The team does not need to manually prepare scripts.

The downside of this approach is that it involves manual work which is error prone. Developers still have 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, there is no easy way to 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 the Feature B without manually editing PL/SQL code objects to remove Feature A.

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.
  • All databases are managed by Gitora and all Git command are executed using Gitora.
  • 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:

  • Create a new branch named featureA (DEV1/featureA). Switch DEV1 to use this new branch.
  • Write code in DEV1
  • Commit code changes to the DEV1/featureA. Go back to step 2 as many times as needed.

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

Developer 2:

  • Create a new branch named featureB (DEV2/featureB). Switch DEV2 to use this new branch.
  • Write 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 takes place.

Developer 1:

  • In our example , we assume that Developer 1 is the first developer sending her commits to TEST.
  • Merge DEV1/featureA to DEV1/master. (DEV1/featureA –> DEV1/master). After the merge, commit history for DEV1 looks like this:
  • Pull master branch from DEV1 to 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 a local branch. In our example TEST fetches DEV1/master from 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 TEST to the master branch in 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)
  • Merge DEV2/featureB to DEV2/master. (DEV2/featureB –> DEV2/master) After the merge, the commit history looks like this:
  • Pull master branch from DEV2 to 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 combined. 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 at any point in time before going to production.

Removing Feature A from the Deployment

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

  • 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 the 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 the new version which only includes Feature B to the production database.

Gitora helps developers execute this workflow with a point&click GUI. 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.

Therefore:

  • 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. 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 to 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.

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.

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