Reserving Database Objects for Authorized Users

Gitora 5 Enterprise enables you to reserve database objects so that they can be edited by authorized users only.

To achieve this, in the Gitora web app, right click the database object you’d like to reserve and click the Reserve menu option.

The Manage Object Reservation dialog shows up. In the dialog select the users you’d like to reserve the object for and click the Done button.

Once an object is reserved for a user (or users) only those users can edit it.

Conversely, users can be excluded from editing a database object.

To achieve this, right click on the database object and click the Exclude menu option.

The Manage User Exclusion dialog shows up.

Add the users that you’d like to restrict from changing this object and click the Done button.

From this moment on, the selected users cannot edit the database object.

Database Script Management

Database developers and DBA’s have many scripts that they use for various purposes such as performance monitoring, migration, software upgrades and database maintanance.

There is often no good way to manage these scripts. DBA’s, developers end up emailing them to each other. The lack of good management and communication around scripts causes human mistakes during database upgrades and maintanance.

Gitora 5.1 Enterprise Edition introduces a new feature called Scripts. In Gitora 5.1, each Gitora repo has a separete section where you can manage your database scripts with the power of git.

Gitora scripts feature provides a single source of truth to DBA’s and developers.

Simply create any folder hierarchy you want and add your scripts to Gitora.

Git will store the entire version history of your scripts. You can view changes in your scripts over time. Find out who changed what and when.

You can also restrict who can edit the scripts.

When you pull a repo from one database to another, the scripts will move with the repo to the target database. This ensures that you always move the right version of a script to the target database, preventing emails, IM messages and many other needless back and forth between developers and DBA’s.

Gitora Webinar

On February 16th, we hosted a webinar about Gitora 5. Many thanks to everyone who attended. The recording of the webinar is below.

You can view the slides for the webiner below. You can also download the slides from this link.

There were a few questions we received several times during the webinar. We’d like to reiterate our answers below:

How does Gitora work with GitLab, GitHub or similar services…?
Gitora repos work with these services just like any other local Git repo does. From the point of GitLab, GitHub or similar services, Gitora repos are just local repos that you can push to these services.

How can I create a merge/pull request with Gitora?
Merge/Pull request is not a Git feature. It is a GitHub/GitLab feature. You can continue creating merge/pull requests on these services using the same workflow you use for any other local repo. To create a merge/pull request for a Gitora repo, first push your repo to GitHub/GitLab using the Gitora web app (or use Git directly). Next, go to your GitHub/GitLab account and create your merge/pull request.

How can I work on two different projects with different deadlines in the same development database and send only code related to one project to the test database?
You can’t. Gitora cannot do magic. 🙂 There will never be a tool that will help you to do this because it is impossible. What Gitora empowers you to do is to have multiple databases per project. Then you can work on the same logical objects in different databases and use Gitora to merge code bases.
You can watch a full workflow and detailed explanation of this process at this link.

User Privileges in Gitora Enterprise

Gitora Enterprise comes with a comprehensive authorization module. Using this module, Gitora admins and other privileged users can assign various roles to Gitora users to limit or enhance what they can do during database development and using Gitora’s capabilities.

Authorization settings in Gitora can be set at three levels:

  • Database
  • Repo
  • Database Object

Database Level Authorization

The highest level where privileges for users can be set is the database level. Only admins can set database level authorization. Each database managed by Gitora has its own authorization scheme that can be set separately.

Gitora Enterprise comes with two default roles: Developer and Release Manager. Customers can edit the database level authorization according to their needs by either editing existing default roles, deleting them or creating new ones.

Each user in Gitora Enterprise must be assigned a database level role.

Gitora provides database level privileges to execute the following functions. These priveleges can be given or taken from a role as desired:

System Privileges:

Edit Repos: Create, edit or delete repos.

Edit Remotes: Create, edit or delete remote repo entries.

Edit Repo Roles: Create, edit, delete or assign repo level roles.

Developer Privileges

Checkout: Take control of a database object to edit it.

Commit: Commit database objects to Git.

Edit Managed Schema Script: Edit the contents of the “Managed Schema Script” file in Gitora.

Repo Management Privileges

Add/Remove Objects: Add or remove database objects to/from a repo.

Add/Remove Schemas: Add or remove schemas to/from a repo for Gitora to keepo track of DDL statements executed in that schema.

Local Git Command Privileges

Reset: Execute the Git Reset command for a repo.

Create Branch: Execute the Git create branch command for a repo.

Change Branch: Change the active branch in the database for the repo.

Merge Branch: Perform a Git Merge for a repo.

Delete Branch: Delete a branch in a repo.

Tag: Mark a Git commit ID in a repo with a recognizable indentifier.

Remote Git Command Privileges

Push: Perform a Git Push to a remote repository.

Pull: Perform a Git Pull from a remote repo.

Fetch and Merge: Fetch a commit ID from a remote repo and merge it to the current branch.

Switch to Remote Branch: Fetch a remote branch and make it the active branch of the current repo.

Other Privileges

Get Script: Download the diff DDL script of two commit ID’s of a repo.

Rebuild from Working Directory: Execute the DDL statement file of a database object (or all database objects) in the working directory folder of a repo in the database.

Managing Database Level Authorization

Log in to Gitora as an admin. Select [Connected Database Name] – > Database Authorization menu item from the main menubar.

The Manage Database Roles page shows up.

Gitora Enterprise comes with two built-in roles: Developer and Release Manager. Privileges for both of these roles are editable. You can also create your own roles.

To create a role click the Add button. The Create Role Dialog shows up. Enter a descriptive name for the role. Check the checkboxes next to the functions that you want the new role to be able to perform. Click the Save button.

Editing existing roles work in a similar way.

Click the delete button on the Manage Database Role page to delete a role.

Repo Level Authorization

Repo level authorization is optional. An admin or a user with the database level privilege Edit Repo Roles can manage repo level privileges. When activated, repo level privileges override any privileges set at the database level for the database objects in the repo and Gitora functions performed for the repo. When users work with a database object that belongs to a repo with an active authorization scheme, they are assigned a repo level role that overrides their database level role. For example, a user with a database level Release Manager role, can act with a Developer role in the context of a repo with an authorization scheme of its own.

Once repo level authorization is activated for a repo, a repo level role must be given to a user explicitly. If no repo level role is assigned to a user, she will have no privileges in the context of the repo with repo level privileges. Admins are not affected by repo level authorization.

Repo level privileges that Gitora Enterprise provides are a subset of the database level privileges. System privileges are only set at the database level. The following privileges can be set at the repo level:

Developer Privileges

Checkout: Take control of a database object to edit it.

Commit: Commit database objects to Git.

Edit Managed Schema Script: Edit the contents of the “Managed Schema Script” file in Gitora.

Repo Management Privileges

Add/Remove Objects: Add or remove database objects to/from a repo.

Add/Remove Schemas: Add or remove schemas to/from a repo for Gitora to keepo track of DDL statements executed in that schema.

Local Git Command Privileges

Reset: Execute the Git Reset command for a repo.

Create Branch: Execute the Git create branch command for a repo.

Change Branch: Change the active branch in the database for the repo.

Merge Branch: Perform a Git Merge for a repo.

Delete Branch: Delete a branch in a repo.

Tag: Mark a Git commit ID in a repo with a recognizable indentifier.

Remote Git Command Privileges

Push: Perform a Git Push to a remote repository.

Pull: Perform a Git Pull from a remote repo.

Fetch and Merge: Fetch a commit ID from a remote repo and merge it to the current branch.

Switch to Remote Branch: Fetch a remote branch and make it the active branch of the current repo.

Other Privileges

Get Script: Download the diff DDL script of two commit ID’s of a repo.

Rebuild from Working Directory: Execute the DDL statement file of a database object (or all database objects) in the working directory folder of a repo in the database.

Managing Repo Level Authorization

Select a repo from the main select box in the Gitora Web App. Click the Git -> Repo -> Repo Authorization menu item from the menubar. The Manage Repo Roles page shows up.

Use the Add, Delete and Edit buttons to manage repo level roles.

Check the Enable Repo Level Authorization Scheme checkbox so that the repo level roles take effect. You can disable repo level roles by unchecking this checkbox at any time.

To assign a repo level role to a user, click the [Connected Database Name] – > Users menu item from the menubar. Click the Edit button next to a user. The Edit User screen shows up.

Please note that the top portion of this screen where you can edit a users name, password, database role etc… will only show up for admins.

The table at the bottom of the screen with the title Repo Specific Roles for User displays the roles a user has for a specific repo. To add a role click the Add button. The Add Repo Role Dialog shows up.

Select the repo and the role you’d like to assign to the user in this repo. Please note that the repo select box only shows repos with repo level roles. Click the Save button.

The assigned role will show up in the edit user page.

Please note that, a user can only have one role for a repo. To change the user’s role, delete the current role and create a new one.

Database Object Level Authorization

Gitora Enterprise enables admins and users with database level privilege Edit Repo Roles to reserve a database object for a user or group of users. This way, only the users in the reservation list can check out (and therefore edit) an object.

To achieve this, in the main select box, select the repo the obejct is in. Navigate to the object in the tree and right click to it. In the context menu, click Reserve.

The Manage Object Reservation Dialog shows up. Select the user and click the Add link to add the user to the list of users for whom this object is reserved. Click the Done button when you are finished.

Gitora API’s

Gitora Enterprise has a set of API’s that enables developers to programatically execute tasks that users can perform via the Gitora Web App such as reset, create branch, commit etc…

Below is the list of API’s with their description, input parameters and outputs.

Gitora API’s respect the authorization scheme defined in the Gitora Web App. In other words, if a user lacks the necessary privilege to perform an operation in the Gitora Web App, the corresponding API will also fail for the same user.

Introduction

After the default installation, Gitora API’s can be accesses from the URL http://[IP ADDRESS]:8080/gitora/api.

The method parameter specifies the name of the method you’d like to execute like so:

http://localhost:8080/gitora?method=login.....

Developers must log in to the API server before executing any other API call. Therefore, it makes sense to describe the login method first.

Method: login

Use to sign in to Gitora.

Parameters:

user: A valid Gitora username.

password: Password of the Gitora user.

database: The name of the database. This name is specified in the Settings->Database Connections screen in Gitora.

Output:

The login method returns a token that you need to use in every other API call.

Example: http://localhost:8080/gitora/api?method=login&user=admin&password=admin

Method: add

Add a database object to a Gitora repo.

Parameters:

name: Name of the database object

repo: Name of the repo to add the database object to.

schema: Schema of the database object to be added.

token: A valid token string received from a login API call.

type: Type of the database object to be added. Valid values are TABLE, PACKAGE, VIEW, PROCEDURE, FUNCTION, TRIGGER, SYNONYM, TYPE, SEQUENCE, MATERIALIZED_VIEW

Output:

Returns null if it completes successfully. It returns an error message if the operation fails.

Example:

http://localhost:8080/gitora/api?method=add&name=EMP_PKG&repo=HR_REPO&schema=HR&token=YhfhseY45&type=PACKAGE

Method: changebranch

Changes the active branch of a Gitora repo.

Parameters:

branch: Name of the branch to switch to.

repo: Name of the repo this operation will be performed.

token: A valid token string received from a login API call.

Output:

Returns null if it completes successfully. It returns an error message if the operation fails.

Example:

http://localhost:8080/gitora/api?changebranch&branch=dev&repo=HR_REPO&token=Hhjfir7hd87

Method: checkout

Checks out the database object for a specific user.

Parameters:

object: ID of the object to check out

token: A valid token string received from a login API call.

Output:

Returns null if it completes successfully. It returns an error message if the operation fails.

Example:

http://localhost:8080/gitora/api?checkout&object=1234&token=Hdyhed7645g

Method: commit

Commits a list of objects to the specified repo.

Parameters:

message: Commit message.

ddls: A comma separated list of ID’s of DDL statements captured by Gitora.

objects=Comma separated list of object ID’s to be committed.

repo: Repo name.

token: A valid token string received from a login API call.

Output:

Returns the message received from Git.

Example:

http://localhost:8080/gitora/api?commit&message=Fixed%20the%20employee%20queries&objects=1234,4523&ddls=3642,7854&repo=HR_REPO&token=jirHJj8rfnJi

Method: createbranch

Creates a new branch in the specified repo.

Parameters:

branch: Name of the new branch.

checkout: Indicated whether the new branch should be set as the active branch. Set to true to make the new branch the active branch, to false otherwise.

commitid: Git commit ID, tag name or branch name to create the new branch from.

repo: Name of the repo to create a branch in.

token: A valid token string received from a login API call.

Output:

Returns a list of modified database objects if there are any or an error message.

Example:

http://localhost:8080/gitora/api?createbranch&checkout=true&commitid=Hdjdjhuend8874h29jdij&repo=HR_REPO&token=Kjirjdnc767yHy3

Method: createrepo

Creates a Gitora repo.

Parameters:

repo: Name of the repo to be created.

token: A valid token string received from a login API call.

Output:

Returns the message received from Git.

Example:

http://localhost:8080/gitora/api?createrepo&repo=HR_REPO&token=HJndnr8783dj

Method: deletebranch

Deletes the specified branch.

Parameters:

branch: Name of the branch to be deleted.

repo: Name of the repo the branch is in.

token: A valid token string received from a login API call.

Output:

Returns the message received from Git or an error message.

Example:

http://localhost:8080/gitora/api?deletebranch&branch=dev&repo=HR_REPO&token=Hjfurns75bdy

Method: fetchmerge

Fetches a specific commit ID from a remote repo and merges it to the specified repo’s active branch.

Parameters:

branch: The name of the remote branch to fetch from.

commitid: Git commit ID to fetch from the remote branch and merge to the active branch.

password: The password or the personal access token to connect to the remote repo. For example your GitHub personal access token. This parameter is optional. Don’t use it if the remote repo does not need a password to access.

remote: The alias specified for the remote database in the Gitora Web App.

repo: The name of the local repo.

token: A valid token string received from a login API call.

user: user name to connect to the remote repo. For example your GitHub user name. This parameter is optional. Do not use it if the remote repo does not need a user name to access.

Output:

Returns the message received from Git.

Example:

http://localhost:8080/gitora/api?fetchmerge&branch=dev&commitid=Jdudnr75hfgsj84fj&password=myPersonalAcessToken1&remote=myRemoteHRRepo&repo=HR_REPO&user=myGitHubUser&token=Hjnf74hehd

Method: fetchmergefromdb

Fetches a specific commit ID from a Gitora repo for another database and merges it to the specified repo’s active branch.

Parameters:

branch: Name of the branch to fetch from the fromrepo.

commitid= Git commit ID to fetch from the branch and merge to the active branch.

database: Name of the database the fromrepo is for.

fromrepo: Name of the repo to fetch from.

torepo: Name of the repo to merge to.

token: A valid token string received from a login API call.

Output:

Returns message received from Git.

Example:

Assume Gitora is connected to the TEST database. The example below fetches the commitid 1234 on branch master from the HR_REPO_DEV repo at the DEV database to the active branch of the HR_REPO at the TEST database.

http://localhost:8080/gitora/api?fetchmergefromdb&branch=master&commitid=1234&database=DEV&fromrepo=HR_REPO_DEV&torepo=HR_REPO&token=Hjnf74hehd

Method: getmanagedschemascript

Returns the “managed schemas script” of the specified repo.

Parameters:

repo: Name of the repo of which the developer is getting the managed schemas script.

token: A valid token string received from a login API call.

Output:

The contents of the managed schemas scrpt file, represented as the DDL_SCRIPT.sql in the Git repo.

Example:

http://localhost:8080/gitora/api?getmanagedschemasscript&repo=HR_REPO&token=Kjfur03nd8

Method: getmyobjects

Returns the list of checked out database objects by the current user.

Parameters:

repo: The repo for which the API queries the objects the user has checked out.

token: A valid token string received from a login API call.

Output:

Returns a JSON array. Each object in the array represents an database object that is checked out by the user. Each JSON object in the array has the following attributes:

id: ID of the database object in Gitora.

name: Name of the object.

schema: Schema of the object.

status: Indicates the modification state of the object. Valid values are: UNMODIFIED,MODIFIED, DELETED

type: Type of the object. (PACKAGE, PROCEDURE etc…)

token: A valid token string received from a login API call.

Example:

http://localhost:8080/gitora/api?method=getmyobjects&repo=HR_REPO&token=Jnjf744jn

Method: getrepoobjects

Returns a JSON array of database objects in the repo.

Parameters:

repo: Name of the repo to return the objects for.

token: A valid token string received from a login API call.

Output:

Returns a JSON array. Each object in the array represents a database object managed by the specified repo. Each JSON object in the array has the following attributes:

id: ID of the database object in Gitora.

name: Name of the object.

schema: Schema of the object.

status: Indicates the modification state of the object. Valid values are:

token: A valid token string received from a login API call.

type: Type of the object. (PACKAGE, PROCEDURE etc…)

UNMODIFIED,MODIFIED, DELETED

user: Name of the user who checked out the database object.

Example:

http://localhost:8080/gitora/api?method=getrepoobjects&repo=HR_REPO&token=Nkjf8nf8

Method: merge

Performs git merge.

Parameters:

commitid: Git commit ID, branch or tag name to merge to the active branch.

repo: Name of the repo to perform merge on.

token: A valid token string received from a login API call.

Output:

Returns the the text value conflict if there is a conflict after the merge or noconflict if there isn’t any.

Example:

http://localhost:8080/gitora/api?method=merge&commitid=dev&token=Hjfur84bnfr

Method: pullfromdb

Performs a Git pull from a Gitora repo for another database to the specified repo’s active branch. For example, you can pull the master branch of HR_REPO in DEV database to the master branch of HR_REPO in TEST database to move your latest code to the testing environment.

Parameters:

branch: Branch name on the fromrepo to pull.

database: Name of the database (identified in Gitora Web App under Settings->Database Connections) the from repo is for.

fromrepo: Repo to pull from.

token: A valid token string received from a login API call.

torepo: Repo to pull to.

Output:

Returns the message received from Git.

Example:

Assume thet the developer is connected to the TEST database. The example below pulls the master branch from the HR_REPO repo for DEV database to the master branch of HR_REPO repo for the TEST database.

http://localhost:8080/gitora/api?method=pullfromdb&fromrepo=HR_REPO&torepo=HR_REPO&branch=master&database=DEV&token=Hjgg6ghf

Method: push

Pushes the specified repo’s branch to a remote Git repo (which commonly resides in GitHub, GitBlit, BitBucket or a similar cloud service).

Parameters:

branch: Name of the branch to push.

password: Password or the personal access token to connect to the remote repo.

remote: The alias specified for the remote repo in the Gitora Web App under Settings–>Manage Remote Connections.

repo: Name of the repo to push.

token: A valid token string received from a login API call.

user: User name to connect to the remote repo.

Output:

Returns the message received from Git.

Example:

http://localhost:8080/gitora/api?method=push&branch=master&password=1234&remote=GitHubHRRepo&repo=HR_REPO&user=myGitHubUser1&token=Hjf85jf

Method: release

Releases the lock placed by a user on a database object. Overwrites the content of the object with the latest version available in the active branch.

Parameters:

object=ID of the database object to be released.

token: A valid token string received from a login API call.

Output:

Returns null if succeeds or an error message if it fails.

Example:

http://localhost:8080/gitora/api?method=release&object=3455&token=Hjfu57hf

Method: remove

Removes the specified database object from Gitora.

Parameters:

name: Name of the database object.

repo: Name of the repo the database object will be removed from.

schema: The schema of the object

token: A valid token string received from a login API call.

type: The type of the object. Valid values are: Valid values are TABLE, PACKAGE, VIEW, PROCEDURE, FUNCTION, TRIGGER, SYNONYM, TYPE, SEQUENCE, MATERIALIZED_VIEW.

Output:

Returns null if succeeds or an error message if it fails.

Example:

http://localhost:8080/gitora/api?method=remove&name=EMP_PKG&repo=HR_REPO&schema=HR&type=PACKAGE&token=Hfjuh784hnd

Method: reset

Performs the Git reset command on the active branch of the specified repo.

Parameters:

commitid: Git commit ID or tag name to reset the active branch to.

repo: Name of the repo to perform the Git reset.

token: A valid token string received from a login API call.

Output:

Returns the Git message received from Git.

Example:

http://localhost:8080/gitora/api?method=reset&commitid=375hfhd&repo=HR_REPO&token=Hjfnh894jhhnfr

Method: setmanagedschemascript

Updates the “Managed Schema Script” content and commits it.

Paramaters:

message: Commit message to be used when the new script is committed to Git.

repo: Name of the repo to set the script for.

script: The new text of the script.

token: A valid token string received from a login API call.

Output:

Returns the message received from Git.

Example:

http://localhost:8080/gitora/api?method=setmanagedschemascript&messageScript%23updated.&repo=HR_REPO&script=ALTER%23EMPLOYEES%23ADD%23COLUMN%23(MIDDLE_NAME%23VARCHAR2(200);&token=Hjhu837h

Method: switchtobranchfromdb

Fetches the branch in a repo for another database and makes it the active branch in the specified repo for the currently connected database. Used if the fetched branch is not present in the repo for the currently connected database. For example the featureA branch in HR_REPO for the DEV database may not exist in the HR_REPO for the TEST database. Using this API will bring over the featureA branch from DEV to TEST and make it the active branch.

Parameters:

branch: Name of the branch to fetch and make active.

database: The database the fromrepo is for.

fromrepo: Name of the repo to fetch the branch from.

token: A valid token string received from a login API call.

torepo: Name of the repo to fetch the branch to. It is expected that torepo does not have this branch.

Output:

Returns the message received from Git.

Example:

Assume that the featureA branch is in DEV but not in TEST database and the developer is connected to the TEST database. The example below fetches the featureA branch from the DEV database to the TEST database and makes it the active branch.

http://localhost:8080/gitora/api?method=switchtobranchfromdb&fromrepo=HR_REPO&database=DEV&torepo=HR_REPO&branch=featureA&token=Hjfi94fj4

Method: switchtoremotebranch

Fetches the branch in the remote repo and makes it the active branch in the specified repo for the currently connected database. Used if the fetched branch is not present in the repo for the currently connected database. For example the featureA branch in the remote repo GitHubHRREPOmay not exist in the HR_REPO for the TEST database. Using this API will bring over the featureA branch from remote repo to the TEST database and make it the active branch.

Parameters:

branch: Name of the branch to fetch from the remote and make active.

database: The database the fromrepo is for.

password: The password or personal access token to connect to the remote repo.

remote: Alias of the remote repo specified in the Gitora Web App under Settings–>Manage Remote Repos.

repo: Name of the repo to fetch the branch to. It is expected that torepo does not have this branch.

token: A valid token string received from a login API call.

user: User name to connect to the remote repo.

Output:

Returns the message received from Git.

Example:

Assume that the featureA branch is in remote GitHubHRRepo but not in local HR_REPO for the TEST database and the developer is connected to the TEST database. The example below fetches the featureA branch from the GitHubHRRepoto the TEST database and makes it the active branch.

http://localhost:8080/gitora/api?method=switchtoremotebranch&remote=GitHubHRRepo&torepo=HR_REPO&branch=featureA&user=myGitHubUser&password=1234&token=Hjfi94fj4

Managing Tables

With Gitora 5 users can track changes made to any table’s definition individually.

The way tables work in Gitora is very similar to the way soft objects such as packages, procedures work but there are a few key differences. We’ll go over them briefly.

Adding a Table to a Repo

You can add a table to a Gitora repo just like you add any other object. Simply open a repo from the main select box. Click Git->Add/Remove Object from the menubar. The Add/Remove Database Objects dialog shows up.

Simply, select, add the tables you’d like to include to the open repo and click the Done button.

Gitora will generate a DDL script for the table and save it as a file in the Git repo. The DDL script will contain the table’s definition as well as any constraints and indexes created on it.

Making Changes To a Table Definition

The workflow for executing a DDL on a table managed by Gitora is exactly the same as any other object managed by Gitora.

Once a table is added to a Gitora repo, developers must log in to Gitora in their database session to be able to make modifications to its definition. (The table must also be available for checkout for the developer to execute a DDL statement on the table.)

After a developer executes a DDL statement for the table (such as adding a column), Gitora automatically checks out the table for the developer if the table is not checked out by another developer already.

The developer can commit her changes to Git just like she commits any other object in the Gitora app, namely by clicking the “Git->Commit” item in the menubar and including the table in her commit.

Effects of Executing Git Commands on Tables

Executing Git commands such as reset, change branch, merge may change the file that contains the table DDL. The file will contain the correct DDL statement for the current Git commit ID. However, Gitora will not reflect this change in the database. This behavior differs from how Gitora behaves for soft objects such as packages, views, procedures etc… If there are changes, Gitora updates these objects in the database after a Git command is executed.

Sequences and materialized views work the same way as tables.

In Gitora parlance, any object that can be used with CREATE OR REPLACE syntax is called a soft object. Objects such as tables, sequences and materialized views which cannot be used with CREATE OR REPLACE 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.

Moving Hard Object Changes between Databases

Gitora can move soft objects (packages, procedures, views etc…) between databases with a single click or an API call (enterprise edition only) automatically.

The method described above to track tables is very useful to create schemas from scretch, to track changes over a period of time and see the definition of an object in a previous state. However, it is not very useful to move hard object changes to another database. To achieve this, Gitora has a “Managed Schemas” feature. You can register one ore more schemas to a Gitora repo so that it tracks every hard object DDL statement executed in these schemas. To achieve this, click Git->Add/Remove Managed Schema. Select the schemas you want to manage and click Done.

In the picture above, Gitora will track DDL statements executed in the HR user.

Let’s assume that we execute the following DDL statement in the HR schema:

ALTER TABLE EMPLOYEES ADD (MIDDLE_NAME VARCHAR2 (25));

DDL statements show up in the “Managed Schema DDL” section of the Commit Changes page.

Once committed, these DDL statements show up in a file named “Managed Schema DDL’s” in the Gitora main screen. Please note that the DDL statement above shows up at the end of the document after it is committed.

As developers commit their DDL statements, they are added to this file. Gitora users can edit this file by clicking Edit in its right click menu.

If we pull this repo (say from DEV to TEST) the “Managed Schema DDL’s” will also be pulled.

Once the pull is completed, the DDL statement we executed in DEV is now in TEST but not yet executed.

To determine which DDL statements we need to execute, we simply need the diff between the Managed Schema DDL’s file’s current state and previous state before the pull. We get this diff by right clicking the Compare button in the right click menu of the Manage Schema DDL’s file.

The Compare Versions dialog shows up. Left Side and Right Side fields accept any Git commit ID. Clicking the compare button shows a screen which highights the differences between the two versions of the Manage Schema DDL’s file.

HEAD@{1} is a Git shorthand that represents the previous commit ID (before the pull) and similarly HEAD represents the current commit ID (after the pull). Clicking the Compare button gives the following result:

The DDL statement we need to execute in TEST to sync it with DEV is highlighted in green.

Any Gitora repo can manage any number of schemas. However, we recommend users to create a separate repo to manage schemas of a project.

Introducing Gitora 5

We are very excited to announce that Gitora 5 is now available for download.

Gitora 5 is a huge step forward for version management of database objects.

Gitora 5 has many new features. Below are just six of our favorites:

  • A Brand New User Interface and Application
  • One Gitora Installation to Manage Any Number of Databases
  • Gitora Now Manages Tables
  • No-login development experience
  • A Comprehensive Developer Privileges Management Module
  • Full API To Completely Automate Your Workflow

Let’s go over these new features briefly:

A Brand New User Interface and Application

We redesigned every screen in Gitora from the ground up. The new design gives Gitora 5 a beautiful modern look with large components, easy to read, fresh colors and updated icons. 

We also rebuilt the application with Java. This reduced Gitora’s database footprint by more than 95% making it much easier to install and manage.

One Gitora Installation to Manage Any Number of Databases

This was probably one of the most requested features. Previously, if you wanted to manage a database with Gitora, you needed a new Gitora installation. This is no longer the case.

Thanks to Gitora 5’s new architecture, users can now manage any number of databases with Gitora 5 from a single application.

This makes moving code and switching between databases much easier. Maintenance and upgrade tasks are also much simpler because there is only one application to manage.

Moreover, we made installing Gitora much easier. No more running hundreds of database scripts or changing database settings. Once you create a database user for Gitora, the application will automatically install its database objects.

Gitora Now Manages Tables

Tables are now first class citizens in Gitora. You can manage every table’s DDL in Git repos along with its constraints and indexes, in its own file with its complete history, automatically.

No-login Development Experience

Previously, signing in to Gitora required an extra step for database developers. Every time they opened a database session, they had to execute one line of code to sign in to Gitora. Gitora 5 can be configured to recognize selected database users as valid Gitora users. This way, Gitora 5 becomes completely transparent during regular development activities.

A Comprehensive Developer Privileges Management Module

Gitora 5 Enterprise comes with a sophisticated authorization module with which you can manage who can edit which database object and perform which Git operation. You can define privileges for actions such as check out, commit, pull, push etc… at database level and at repo level. You can even restrict access to certain objects to specific developers.

Full API To Completely Automate Your Workflow

Last but not least, Gitora 5 Enterprise comes with a set of API’s so that you can fully automate your workflow. The API’s are easy to use and support the restrictions you specify in the authorization module.

These are our top six features but there are many more. Here is just a few of them:

  • A new and improved diff screen
  • A new way to track every DDL you execute in the database
  • Table DDL generation that is master-detail relationship aware
  • Support for sequences, materialized views

Gitora 5 comes with the features you are already familiar with:

  • Create Git repos with any of your database code objects such as Packages, Views, Types, Triggers etc…
  • Gitora doesn’t miss a change. Capture every change in these objects automatically and commit them to Git with a single click.
  • Perform Git operations such as reset, branch, merge, pull etc.. These operations will update your database objects automatically.
  • Push your repos to any cloud service such as GitHub, GitLab etc…

Gitora is a unique tool that integrates Git to the Oracle Database. It enables you to use Git just like a Java, JavaScript or C# developer.  

Gitora 5 is by far our biggest and most important release since releasing the first version of Gitora in 2015. Gitora 5 is an indispensable tool to improve developer productivity, implement modern development workflows and cut delivery times significantly.

Try Gitora 5 today.

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.

Gitora 4 is available for download

We’re happy to announce the general availability of Gitora 4.

Gitora 4 builds on top of the great foundation of Gitora 3 and makes it even easier for Oracle developers to integrate version control to their daily workflow.

Gitora 4 comes with three new improvements:

  • Pull from and push to Github, Gitlab, Bitbucket or any other Git repository…
  • Simplified workflow and vastly improved working folder organization.
  • SQL Developer Plugin (Coming soon.)

You can download Gitora 4 from this link.

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! 🙂