Gitora

Gitora For Data API

Fri, 06 Oct 2023 16:20:43 +0300

Gitora For Data exposes a JSON API that you can use to complete the most common tasks you’d use the application for.

Specifically, using the API you can:

Export data from a database to a repo
Import data from a repo to a database
Clone a repo
Get the text content of a file from the repo
Download a binary file (LOB) or a folder from the repo

Authentication

Gitora For Data API uses API keys for authentication. Please read the section titled Generating and Using API Keys at the end of this document to learn about API keys.

All API requests should include your API key in an Authorization HTTP header as follows:

Authorization: Bearer GITORA_FOR_DATA_API_KEY

Below is a Java code example to establish a connection to the Gitora For Data API. Note that the API end point is at [your domain]/gitorafordata/api

   private static String getApiKey() {
        return "YOUR API KEY";
   }

   private static HttpURLConnection getHTTPConnection() {
        try {
            URL url = new URL("http://127.0.0.1:7101/gitorafordata/api");
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setRequestProperty("Authorization", "Bearer " + getApiKey());
            connection.setDoOutput(true);
            return connection;
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

Sending an HTTP Request to the API

The HTTP request body must be a JSON object. The JSON object contains the name and the input parameter values of the API function being called. Below is the list of functions with an example to show how to call them:

Export:

JSON Object Specification:

method: export

input: A JSON Object that contains the input parameters to the export function.

input JSON Object properties:

database: Name of the database you want to export from.

repo: Name of the Git repo you want to export to.

message: Your Git commit message.

threads: Number of threads to use to export the data. (Defaults to 1).

{"method":"export", "input":{"database":"Gitora 7","repo":"CO","threads":2,"message":"API Export"}}

Java example:

        try {
            JSONObject payload  = new JSONObject();
            payload.put("method","export");
            JSONObject input = new JSONObject();
            input.put("database","Gitora 7");
            input.put("repo","CO");
            input.put("message","API Export");
            input.put("threads",2);
            payload.put("input",input);
            JSONObject response = contactGitoraAPI(payload);

        }catch(Exception e){
            e.printStackTrace();
        }

Response

The response from the server returns a JSON Object in the body. If the export function is successful, the object looks like the following:

{"status":"success"}

If the export function is not successful, the object looks like the following:

{"status":"error","error":"Some error message"}

Import

JSON Object Specification

method: import

input: A JSON Object that contains the input parameters to the import function.

input JSON Object properties:

database: Name of the database you want to import into.

repo: Name of the Git repo you want to import.

execute: Boolean. Set to true if you want to actually perform the import to the database. Set to false if you want to download the generated insert statements. Defaults to false.

{"method":"import", "input":{"database":"Dulcian Local","repo":"CO","execute":true}}

Java example:

        try {
            JSONObject payload  = new JSONObject();
            payload.put("method","import");
            JSONObject input = new JSONObject();
            input.put("database","Dulcian Local");
            input.put("repo","CO");
            input.put("execute",true);
            payload.put("input",input);

            JSONObject response = contactGitoraAPI(payload);

        }catch(Exception e){
            e.printStackTrace();

        }

Response

The response from the server returns a JSON Object in the body. If the import function is successful and the execute property was set to true, the object looks like the following:

{"status":"success", "entityReports":[If there are any errors during the import they appear here other wise this property does not exist], "result":"Message that indicates that the import completed without errors. This property exists only if there are no errors during the import." }

Important Note: The status of the response can be success and the import can be a failure. The status property only indicates that the Gitora For Data server accepted and executed your request. It does not indicate that the import itself was successful. For import to be successful, there must be no entityReports property in the response. In other words, the result property must be in the reponse.

If the execute property was set to false, then the response contains a fileName property which you should use with the download function to download the generated script.

{"status":"success","fileName":"Use this value with the download function"}

If the import function is not successful, the object looks like the following:

{"status":"error","error":"Some error message"}

Clone

JSON Object Specification

method: clone

input: A JSON Object that contains the input parameters to the clone function.

input JSON Object properties:

source: A JSON Object that specifies the source repo that will be cloned.

source JSON Object properties:

database: Name of the database you want to clone from.

repo: Name of the Git repo you want to clone.

target: A JSON Object that specifies the target repo.

database: Name of the database you want to create the new repo in.

repo: Name of the Git repo you want to create.

databaseUser: Name of the database user to be associated with the new repo.

{"method":"clone", "input":{"source":{"database":"Gitora 7","repo":"CO"},"target":{"databaseUser":"CO","database":"Dulcian Local","repo":"CO"}}}

Java example:

        try {
            JSONObject payload  = new JSONObject();
            payload.put("method","clone");
            JSONObject input  = new JSONObject();
            JSONObject source = new JSONObject();
            source.put("database","Gitora 7");
            source.put("repo","CO");
            input.put("source",source);
            JSONObject target = new JSONObject();
            target.put("database","Dulcian Local");
            target.put("repo","CO");
            target.put("databaseUser","CO");
            input.put("target",target);
            payload.put("input",input);

            JSONObject response = contactGitoraAPI(payload);

        }catch(Exception e){
            e.printStackTrace();
        }

Response

The response from the server returns a JSON Object in the body. If the clone function is successful the object looks like the following:

{"status":"success"}

If the clone function is not successful, the object looks like the following:

{"status":"error","error":"Some error message"}

Get

Returns the content of a file stored in the Git repo.

JSON Object Specification:

method: get

input: A JSON Object that contains the input parameters to the get function.

database: Name of the database you want to get from.

repo: Name of the Git repo you want to get from.

path: Path of the file you want to get. Start the path after the data folder. For example, if the repo is at directory C:\gitora\datastore\GitoraForData\repos\databases\DVD Rental\dvdrental_repo and the file you want to get is actor.json which is at the path C:\gitora\datastore\GitoraForData\repos\databases\DVD Rental\dvdrental_repo\data\actor\actor.json path parameter value must be actor/actor.json . You can download an entire folder by specifying the path to the folder.

commitId: ID of the git commit you want to query from. If you want the current state of the file in the working directory, leave this property null or empty.

returnDownloadLink: If set to true, the function returns a download link that you can use to download the file. If set to false, the body of the response contains the file. Defaults to false. If a file is not a text file, the property is omitted. Binary files and folders are always returned as a downloadable link.

{"method":"get", "input":{"path":"PRODUCTS/PRODUCTS.json","database":"Gitora 7","repo":"CO","commitId":"01f05021c5136db6d3979d61f6b5bfac21fdb42f","returnDownloadLink":true}}

Java example:

        try {
            JSONObject payload  = new JSONObject();
            payload.put("method","get");
            JSONObject input = new JSONObject();
            input.put("database","Gitora 7");
            input.put("repo","CO");
            input.put("path","PRODUCTS/PRODUCTS.json");
            input.put("commitId","01f05021c5136db6d3979d61f6b5bfac21fdb42f");
            input.put("returnDownloadLink",true);
            payload.put("input",input);

            JSONObject response = contactGitoraAPI(payload);

        }catch(Exception e){
            e.printStackTrace();
        }

Response

The response from the server returns a JSON Object in the body. If the get function is successful and the returnDownloadLink property is set to false the object looks like the following:

{"status":"success", "result":{"fileContent","This is the content of my file."}

If the returnDownloadLink property is set to true or the referenced path is a binary file or a folder then the request looks like the following:

{"status":"success", "result":{"filePath","use this path with the download function"}

If the get function is not successful, the object looks like the following:

{"status":"error","error":"Some error message"}

Download

Downloads a file

JSON Object Specification:

method: download

input: A JSON Object that contains the input parameters to the get function.

fileName: A file name that you received from other Gitora For Data API functions. You cannot pass any file name to this function and expect it to return it. The file must be created by another API function.

{"method":"download", "input:{"fileName":"rBa1k6lWlDoFIbzD3OqMh6iZxS7gAsVWw7flhoJQ7zQzDThm3fI.zip"}}

Java example:

        try {
            JSONObject payload  = new JSONObject();
            payload.put("method","download");
            JSONObject input = new JSONObject();
            input.put("fileName","rBa1k6lWlDoFIbzD3OqMh6iZxS7gAsVWw7flhoJQ7zQzDThm3fI.zip");
            payload.put("input",input);
            downloadFromGitoraAPI(payload);
        }catch(Exception e){
            e.printStackTrace();
        }

Response

The response from the server can be downloaded using standard http file download.

Below are the other Java methods used in these examples:


    private static JSONObject contactGitoraAPI(JSONObject payload) {
        HttpURLConnection http = getHTTPConnection();
        try {

            http.getOutputStream().write(payload.toString().getBytes());

            int responseCode = http.getResponseCode();

            JSONObject responseJson = null;
            if (responseCode == HttpURLConnection.HTTP_OK) {
                BufferedReader reader = new BufferedReader(new InputStreamReader(http.getInputStream()));
                String line;
                StringBuilder response = new StringBuilder();
                while ((line = reader.readLine()) != null) {
                    response.append(line);
                }
                reader.close();
                responseJson = parseResponse(response.toString());

            } else {
                System.out.println("contactGitoraAPI:Request failed. Response Code: " + responseCode);
            }
            return responseJson;
        } catch (Exception e) {
            e.printStackTrace();

        }finally{
            http.disconnect();
        }
    }

    private static void downloadFromGitoraAPI(JSONObject payload) {
        HttpURLConnection http = getHTTPConnection();
        try {

            http.getOutputStream().write(payload.toString().getBytes());
            String savePath = "c:\\downloadedfiles\\downloaded_file.zip"; 
            int responseCode = http.getResponseCode();

            if (responseCode == HttpURLConnection.HTTP_OK) {
                try (FileOutputStream fileOutputStream = new FileOutputStream(savePath);
                     BufferedOutputStream bufferedOutputStream = new BufferedOutputStream(fileOutputStream)) {

                    // Create input stream connected to the server response
                    try (InputStream inputStream = http.getInputStream();
                         BufferedInputStream bufferedInputStream = new BufferedInputStream(inputStream)) {

                        // Create a buffer and a variable to keep track of how many bytes are read
                        byte[] buffer = new byte[4096];
                        int bytesRead;

                        // Read the file and write it to the output stream
                        while ((bytesRead = bufferedInputStream.read(buffer)) != -1) {
                            bufferedOutputStream.write(buffer, 0, bytesRead);
                        }
                    }
                }

            } else {
                System.out.println("contactGitoraAPI:Request failed. Response Code: " + responseCode);
            }
            //return responseJson;
        } catch (Exception e) {
            e.printStackTrace();

        }finally{
            http.disconnect();
        }
    }

Introducing Gitora For Data

Fri, 29 Sep 2023 14:12:02 +0300

We are thrilled to announce the release of a brand new app: Gitora For Data.

Gitora For Data seamlessly integrates data in your tables with Git, enabling robust version control. Utilize any Git command for collaboration and effortlessly import any dataset version back into your chosen database. Gitora For Data is ideal for versioning metadata, business logic, Large Objects (LOBs), and value lists in your tables.

A Solution for Database Centric Applications

Many teams in the Oracle database community build database centric applications where most of the business logic, code, settings, workflows and even user interfaces are stored in the database tables. This has great benefits but it comes at a great cost: Lack of version control. Deprived of version control, database teams struggle to collaborate. Having two people working on the same application becomes a daunting task, a trivial undertaking for middle tier and web developers. Deploying changes from the development database to production fairs no better. A missing row in a table, a forgotten CLOB update causes havoc. Gitora For Data is our first attempt to provide a solution to these shortcomings.

Database centric application development is an area with a lot idiosyncratic implementations and no real industry wide standards. Accommodating the wide range of requirements may take additional features. We are looking forward to hearing from you. We fully anticipate that there will be unique needs and Gitora For Data application architecture is flexible enough to support a wide variety of requirements.

We published two tutorials already. One that shows how you can get started and one that shows how to start versioning your metadata.

You can download Gitora For Data from this link.

Working with a Gitora For Data Repo

Fri, 29 Sep 2023 12:05:54 +0300

If you have not done so already, please read Getting Started with Gitora For Data to learn how you can create and open repos.

In this tutorial, we will add every table in the Oracle sample schema CO to the CO_REPO, extract the data in the tables, make some modifications to them, issue a git commit and import the data into another database.

Clicking the open button next to the repo in the Home Screen opens the Repo App in a new browser tab.

Below is the screenshot of the CO_REPO in its initial state.

At its initial state, the repo CO_REPO is empty and there is only the initial commit that stored the initial Gitora configuration file.

Following tutorials will focus on other git features such as branching, merging etc…

Creating Entities

To add tables to the repo, click the plus sign on the left of the screen titled under the repo search field.

The Add Table to repo dialog shows up.

Select every table by clicking the Select button next to each table. Finally, click OK. Gitora will create an “Entity” for each database table. In Gitora parlance, an Entity is an SQL query with a target table. Gitora for Data can export and import entities.

Our repo looks much better now with seven entities.

We’ll talk about entities and what you can do with them in another tutorial. For the purposes of this tutorial, we are ready to export the data out of the CO schema in the DEV database.

Exporting Data to the Git Repo

Click the Export button which is the first button from the left, at the top of the screen.

The Export dialog shows up.

Gitora can export the data in multiple threads in parallel. Gitora displays the number of processors in your server. We recommend picking a number below the processor count as the number of threads to be used for export.

Finally, Gitora adds and commits the generated files to Git. The more files there are the longer this process takes, although JGit is surprisingly fast at adding and committing files.

Enter a Commit Message and click the Export button. A notification will slide in from the right side of the screen, informing you that the export has begun and Gitora will inform you once it is completed. The same message is also displayed in the Messages tab at the bottom of the screen.

After a short while you will receive a second notification that informing you that the export is completed. The Message tab will also display the same message. The Git tab in the middle of the screen will show the new commit created by the export.

A Word On Export Speed

Gitora is not tested with large datasets and the goal of the product is not to support millions of rows. The CO schema has 8783 rows and Gitora exports the data quickly. Please note that the number of files generated by Gitora can change significantly depending on the File Generation Strategy you choose and the number of LOB columns the tables have.

Browsing the Exported Data

Click on the entity names or open the button group for each entity and select Edit Data to browse the generated JSON files.

In the screenshot below, we clicked the CUSTOMERS entity to view the contents of the CUSTOMERS folder in the repo’s working directory.

Editing the JSON Documents

To edit the document, click the CUSTOMERS.json link. Click the download icon next to it to download the JSON file.

Gitora displays the data in a JSON editor that formats the document properly. Gitora also enforces the JSON syntax for the document. Trying to save the document with a JSON syntax error will cause an error.

For the purposes of this tutorial, change the name of the first customer to John Doe.

Click the Save button at the top menu to save your changes.

Viewing the LOB files

Click the PRODUCTS entity to view the data Gitora exported for products.

The PRODUCTS table contains a CLOB and a BLOB column named PRODUCT_DETAILS and PRODUCT_IMAGE respectively. The PRODUCTS folder contains the files generated for these LOB columns.

As with the JSON documents, you can view the LOB files in the browser (if it is a file type that can be viewed in a browser) or download them.

To view a CLOB file click on the row_o_PRODUCT_DETAILS.txt link. Gitora opens a plain text editor.

The text data stored in the PRODUCT_DETAILS column happens to be a JSON file (which is confusing for the purposes of this tutorial) but let’s ignore that for a moment. Stored in a CLOB, it could be any kind text data that we are viewing. Since the data is plain text, you can edit it within the Gitora for Data application and save your changes just like you would with a JSON file. Make a change to the file and click save.

To view a BLOB file, either click on the link for the file to view it in the browser or click the download button next to the link to download it.

Unfortunately, the original PRODUCTS table in the Oracle sample schema CO does not contain any BLOB data but we’ve added one for this tutorial.

Clicking the link row_0_PRODUCT_IMAGE.pdf will open the PDF file stored in this file in the browser.

Note that, Gitora can figure out common file types of BLOB data such as PDF’s, PNG’s JPEG’s etc… , automatically.

Committing the Changes

Committing the changes we made to Git is a straightforward git commit. Click the menu item named git at the top of the application and select Commit.

The Commit dialog shows up.

The Commit dialog lists the changed files that can be committed to the repo. Click the name of the file to open the diff editor in a new browser tab that highlights the changes made to the file since the last commit.

Select the files by either clicking Select All or by clicking the Select link for each file. Enter a short explanation to the Commit Message field and click the Commit button.

Clicking the Commit button closes the dialog and refreshes the Git tab to display your latest commit.

Ordering Entities for Import

Gitora For Data allows you to set an import order for entities. Click the icon that looks like a hierarchy in the repo menu bar, the second icon from the right among the icons.

The Import Order Dialog shows up.

The CO schema has the necessary foreign key constraints to automatically infer the import order. Click the Order Automatically button for Gitora to order the entities.

Not all tables have the foreign key constraints to automatically infer the import order though. In such cases, drag and drop the entity names in the dialog to their correct order in the import. Gitora will start the import from the top of the list.

Below is the order of entities after Gitora sorted them automatically. Click OK to accept and save the order.

On the main screen, click the first icon on the right in the repo toolbar. Click the Sort By Import Order button to view the entities according to the order they will be imported to the database.

Finally, commit the changes to the import order to the repo.

A Note About the repoConfig.json File

repoConfig.json file is the JSON document that stores the Gitora specific information about your repo. It is part of your repo just like any other file. You should commit it to your repo just like any other file.

Moving Changes to Another Database

In the tutorial Getting Started with Gitora For Data , we clones the repo CO_REPO from the DEV database to the TEST database. The repo was empty then. Now we have data in the repo and even some changes.

Go back to the Home screen and open the CO_REPO in the TEST database. A new browser tabs opens displaying the CO_REPO@TEST repo.

From the top menu select git – > Other Gitora Repos – > Pull

The Pull Dialog shows up. Select the DEV database, the CO_REPO and the master branch from the select boxes respectively.

Click the Pull button to move the changes from the CO_REPO@DEV to the CO_REPO@TEST.

The dialog closes and the Repo app is refreshed with the newly pulled commits and entities.

Importing the Data

Gitora For Data generates insert statements based on the data data in the working directory of the git repo. In other words, you should set the state of the files to the commit id you want to import into the database. In this tutorial, we will import the latest version of the data which is already active in the working directory.

Connect to the CO@TEST database using Gitora PL/SQL Editor. Delete any unwanted rows from the CO schema tables. Since our repo contains all the data we need, we deleted all the rows from the schema by shamelessly plugging our Gitora Editor’s AI Chat feature to this tutorial:

Next, go back to the Gitora For Data app and click the Import button, the second icon from the left.

The Import Dialog shows up.

Click the Import button. Gitora will populate the CO schema with the data in the repo and inform you with a notification and a message in the Messages section at the bottom.

In this tutorial we showed how you can use Gitora For Data to:

Export data from a database to a Git repo
Browse and edit the data in the repo and commit the changes.
Move the repo and import the data to another database.

Getting Started with Gitora For Data

Fri, 29 Sep 2023 12:05:38 +0300

Starting the Application the First Time

The first time you start Gitora For Data (usually via http://yourdomain/gitorafordata/index.html) the login screen shows up. Enter the default username and password admin/admin and click the Sign In button.

Since there are no databases registered to Gitora For Data yet, the Create New Database Connection Screen will show up.

Gitora will create database sessions using the credentials you enter on this screen so that it can query the tables and perform DML operations. Therefore it is important that the database user you enter has the necessary privileges to perform these tasks. You can add additional users to a database later but you need at least one.

Click the Save button to register your first database.

We will use the Oracle sample schema CO throughout this tutorial.

The Home Screen

Clicking the Save button takes you to the Home Screen.

The Home Screen is used for the following functions:

Search, register, edit and unregister databases from Gitora.
Create, clone, delete, search and open repos.
Create, edit and delete database users.
Search, create, edit and delete Gitora For Data application users.

The Home Screen consists of two sections. The navigation column and the main area.

By default, the home screen starts with the Databases tab which lists all the databases that are registered to Gitora.

Creating Your First Repo

In Gitora For Data, each registered database is represented with a Database Card on the home screen. The database card can be used to edit and delete a database as well as to search, create, clone, delete and open Git repos associated with the database.

Our first database does not have a repo yet. So let’s create one.

Click the Create Repo link in the DEV database card. The Create Repo dialog shows up.

The dialog displays several fields. Let’s go over them one by one:

Name: This is the name of your repo. It will be the name of the top folder of your Git repo where the .git folder resides.

Database User: Gitora needs to know which database user this repo will connect to so that it can query data from the DEV database.

Export Format: Select the notation the exported data is represented in. (Currently, JSON format is supported. More options will be added based on customer feedback.)

File Generation: Gitora can generate file or files for the rows in a table using the following output strategies:

a) One File Per Entity

Using this strategy, Gitora will create one JSON file that contains all the rows in the table. For example, if you want to export the data from the EMPLOYEES table, Gitora will create a file at EMPLOYEES/EMPLOYEES.json and store all the rows in the EMPLOYEES table in this file.

b) One File Per Row

Using this strategy, Gitora will create a new JSON file for each row in the table. For example, for the table EMPLOYEES it will create files like so: EMPLOYEES/row_0.json, EMPLOYEES/row_1.json, EMPLOYEES/row_2.json etc…

c) One Folder Per Row

Using this strategy, Gitora will create one folder for each row like so: EMPLOYEES/row_0/row.json, EMPLOYEES/row_1/row.json. This option is more suitable if your tables contain LOB columns. For example, if the EMPLOYEES table contained a column named PICTURE_BL, the output would look like the following: EMPLOYEES/row_0/row.json, EMPLOYEES/row_0/PICTURE_BL.png.

Location for LOB Files: Gitora can export LOB data to files. You can choose one of the following options to create the files for LOBs.

a) Entity Folder

Gitora will create the LOB files under the entity folder which is usually named after the table. For example, files for LOB data in the EMPLOYEES table will be created under the EMPLOYEES folder in the repository like so: EMPLOYEES/row_0_PICTURE_BL.png, EMPLOYEES/row_1_PICTURE_BL.png etc…

b) Subfolder under Entity Folder

Gitora will create the LOB files under the lobs directory of each entity. For example the file structure under the EMPLOYEES folder will look like the following: EMPLOYEES/lobs/row_0_PICTURE_BL.png, EMPLOYEES/lobs/row_1_PICTURE_BL.png

c) One Folder Per Row

Gitora will create a folder for each row and place the LOB files of the row under it like so:

EMPLOYEES/row_0/PICTURE_BL.png
EMPLOYEES/row_1/PICTURE_BL.png

Note that, this option can be used in conjunction with the File Generation strategy One File Per Entity. In this case, all rows of the EMPLOYEES table will be in the EMPLOYEES/EMPLOYEES.json file and the files for LOBs will be in folders generated for each row: EMPLOYEES/row_0/PICTURE_BL.png, EMPLOYEES/row_1/PICTURE_BL.png etc…

Row File Naming Strategy: This option determines the strategy Gitora uses to name the files Gitora creates for each row. Gitora can create a file for each row and/or a file for each LOB column in the row. Gitora will use the selected strategy whenever it creates these files.

a) Default

The Default strategy assigns a number to each row starting from 0. The rows are numbered in the order they are received from the Entity’s SQL query. Therefore, it is important to order the data by a column (or columns) that do not change their value over time. By default, Gitora orders rows by their primary key column value(s). If the table does not have a primary key constraint, Gitora uses the first column in the Entity query like so: select * from table order by 1

b) From Primary Key

Gitora generates row file names using the primary key column value(s) of the table. Assuming the primary key of the COUNTRIES table is NAME_TX, the rows Gitora generates will be: COUNTRIES/row_USA.json, COUNTRIES/row_GERMANY.json etc…

Please note that, the primary key values must not contain any characters that cannot be used in file names.

Column Order: Specify the order in which the table columns appear in the JSON document.

a) Default

The columns are ordered as they appear in the SQL query of the Entity. For example, if the query for the COUNTRIES entity is “select region, name from countries” then the JSON document for the country USA will look as follows:

{“region”:”North America”, “name”:”USA”}

b) Alphabetically

As the name of the option suggests, the columns will be ordered alphabetically in the JSON document. For the same query as above, the JSON document will be as follows:

{“name”:”USA”, “region”:”North America”}

Below are the values for each field for our first repo:

Click OK to create your first repo.

The database card for DEV database shows the first repo you created.

Working with a Repo

Clicking the Open button opens a new browser tab and takes you to the Repo App where the actual stuff happens. Therefore, the repo maintenance deserves its own tutorial. Click here to learn how you can edit a repo, export data to a repo, perform Git operations on the data and finally import your data back to a database.

Deleting a Repo

Click the red Delete button next to a repo to remove it and its contents. Select Yes to confirm and your repo will be deleted.

Cloning a Repo

The Clone button in the Database Card clones a repo and associates the clone with a database.

Although you can clone a repo and associate the clone to the same database, it makes more sense to clone a repo and associate it to a new database. This is how you can move your data from one database to another using Gitora For Data.

To achieve this, let’s create another database first.

Click the Register New Database button and repeat the steps you followed to register your first database. It goes without saying that you should use a different name and JDBC connection string for the new database.

Click the Clone button under the TEST Database Card. The Clone Repo dialog shows up.

Fill out the fields as follows:

Name: Enter a name for your new repo. Since we are cloning the CO_REPO repo, it makes sense to name this repo CO_REPO as well.

Database User: Specify the database user Gitora should use to perform export/import functions for this repo. Since this repo manages data in the CO user, it makes sense to select the CO user.

Clone From Database: We want to clone the CO_REPO from the DEV database to the TEST database, so select the DEV database in this select box.

Original Repo: Select the repo you want to clone from the DEV database. In our case, this is the CO_REPO.

Click the OK button to clone the repo.

The TEST database card shows the cloned repo.

Unregistering a Database

Click the Delete Database button on a database card and select Yes to confirm to remove the database and all its associated repos from Gitora For Data.

Editing a Registered Database and Its Users

Click the Edit Database button on the database card. The Edit Database screen shows up.

Use this screen to edit the database name and the JDBC URL to connect to the database.

Use the Register New User button to add additional credentials to connect to the database. Use the Edit and Delete buttons to update and remove the existing credentials respectively.

Working With Gitora For Data Users

Click the Users tab to work with the application users.

Use the Create New User and Delete buttons to add or remove a user respectively. Click on a user to change its password.

Generating and Using API Keys to work with the Gitora For Data API

The Edit User screen is also where you can generate and update a user’s API key. You need a valid API key to be able to work with the Gitora For Data API.

Click the refresh button to generate a new API key. Generating a new key, invalidates the existing key of the user. Click the copy button to copy the key to your clipboard.

Introducing the Gitora PL/SQL Editor 2.0

Tue, 01 Aug 2023 00:36:39 +0300

Today I am happy to introduce the latest version of the Gitora Editor. You can download it here.

There are two new features in this release.

The PL/SQL Debugger
The AI Assistant

The PL/SQL Debugger

Gitora 2.0 has a fully featured PL/SQL Debugger. Best to my knowledge, Gitora PL/SQL Debugger is the first and the only web application with a PL/SQL debugger.

Gitora Debugger also supports multiple debugging session at the same time.

You can learn more about the Gitora PL/SQL Debugger at this link.

The AI Assistant for SQL and PL/SQL

First a foreword: AI is real and it is here. Its implications for knowledge workers will be enormous, including you the database developers.

There is no escaping AI in our line of work. Therefore, while building this version of Gitora, I’ve fully embraced it.

The last few months have been the most interesting, rewarding and productive period of my professional life. I’ve practically stopped using Google search and StackOverflow, two websites I’d consider essential to my work just a few months ago.

I’ve coded the Gitora PL/SQL debugger virtually without reading a single line of documentation about how to build debuggers in Java or the specifics of how to build a Java debugger for PL/SQL. I am not even sure if there is any documentation available about building a PL/SQL debugger on the Internet.

I just talked about these topics with ChatGPT and analyzed the code snippets it produced.

All CSS and almost all of the run-of-the-mill code I needed to write for the debugger and the AI Assistant (oh the irony!) is either written by ChatGPT or GitHub CoPilot. Heck, I even had the previous sentence grammatically verified by ChatGPT. I got it right in my first attempt and ChatGPT congratulated me.

I view AI as an amazing junior pair programmer who I am working with. My goal is to create the same feeling for you with the Gitora AI Assistant.

In Gitora Editor 2.0 the AI Assistant shows up in several places.

Chat with the AI Assistant

You can chat with the AI Assistant to write, debug, explain and improve your SQL and PL/SQL code.

This is a free form conversation with the AI Assistant very much like the experience with the ChatGPT. The difference is that Gitora automatically informs the AI about the context of your message. Behind the scenes, Gitora sends the information about the tables, their structure and their relationships to the AI Assistant, helping it to write SQL and PL/SQL relevant to your context.

You can send the code you are working on and the errors you receive during execution to the AI Assistant with just a click, along with the relevant context of course.

Links for the tutorials with complete details about how to configure and use the Gitora AI Assistant are below:

Configuring the AI Assistant

How Chat with the AI Assistant

PL/SQL Code Assistant

While you are coding, the Gitora AI Assistant uses the OpenAI GPT Turbo to suggest SQL and PL/SQL code and entire functions, procedures in real-time, right from the editor.

The Code Assistant is not aware of your database objects, their structures and relationships yet, so it is more of an experimental feature.

I’ll continue integrating AI to all aspects of database development to create your favorite junior pair programmer. If you think this is interesting, please download the Gitora PL/SQL Editor. You can support my work by providing feedback via email, Twitter or LinkedIn. Obviously, the best way to support my work is to purchase a subscription. 🙂

How to Use the AI Chat to write, debug and explain SQL and PL/SQL

Mon, 31 Jul 2023 22:01:09 +0300

This article explains how to use the Gitora AI Chat feature.

The Gitora AI Assistant can help you write, debug, explain and improve SQL and PL/SQL code.

Gitora AI Chat uses OpenAI GPT. If you have not done so already, please follow the steps at this link to create an OpenAI account, register your API Key with the Gitora and open the PL/SQL Editor.

The AI Chat UI

If one is not already open, click the + sign in the editor and open an SQL Pad.

An SQL Pad will show up. Using the plug icon, assign a database connection to the SQL Pad, if it does not have one already.

Gitora uses this database connection to teach AI about the tables and their relationships in your database. Gitora NEVER queries the data in the tables and send them to the OpenAI servers.

The SQL Pad has two button on the right that are of interest. We’ll start from the robot icon. Click the robot to open the AI Chat window.

The AI Chat window has two sections. The upper section displays your dialog with the AI. The lower section is where you type your messages to the AI.

The Ai Chat window has a three menu button. From left to right:

SQL Only: Toggling this button on will make the AI skip the explanations and reasoning and return only code.

Start Over: Clicking this button will erase all the context and the previous conversation with the AI.

Table Sensor: The AI examines your message and automatically infers what tables it needs to know about. This feature is on by default and I highly recommend to keep it that way. If you have more than 1500 tables in the schema SQL Pad is connected to and if you are not happy with response times of the AI, experiment with turning the Table Sensor off to improve response times.

Chatting with the Gitora AI Assitant

In this example, we are connected to the Oracle Sample Schema CO which contains the following tables:

CUSTOMERS, INVENTORY, ORDER_ITEMS, ORDERS, PRODUCTS, SHIPMENTS, STORES

We ask the AI to write a query for us: List product inventory for each store.

Hint: As you type, the auto suggest feature in the editor recommends completions. Making a selection from the list will add the selected table to the AI’s context explicitly. If the Table Sensor is on, making a selection is unnecessary almost all the time. So do not feel compelled to make a selection or get the table name right. The AI will figure it out. However, if the Table Sensor is off, making an explicit selection from the completions dialog is the only way you can inform the AI about the context of the question.

Pressing the Enter key or clicking the Send button will submit your message. In a few seconds, the AI response will show up.

There are a few things you can do with this response. Hover your mouse over the highlighted SQL in the AI response. A menu will show up.

From left the right, the menu buttons are as follows:

Execute: Runs the Ai generated SQL and displays the results in the SQL Pad.

Info: Hovering over this menu item, lists the tables the AI considered while generating the query.

Hint: If the Table Sensor is on and you do not see a table that you expect the AI to include to the query, in the information popover, then add the table to your next message. For example write something like “Use ORDER_ITEMS table.”

Append to Pad: Appends the query to the SQL Pad.

Paste to Pad: Overwrites the text in the SQL Pad and pastes the query.

Copy: Copies the query to the clipboard.

The AI does not always produce correct SQL queries. If this is the case, you can inform the AI about the error to help it fix its mistake.

For example, if write the following message, the AI creates an invalid query:

product count per store

The AI produces the following query:

SELECT s.store_id, s.store_name, COUNT(p.product_id) AS product_count
FROM stores s
LEFT JOIN products p ON s.store_id = p.store_id
GROUP BY s.store_id, s.store_name;

This query is wrong because there is not relationship between the STORES and the PRODUCTS table. Executing the query using the Execute menu button produces an error that is visible in the SQL Pad’s error tab.

Note the new red button that showed up in the menu. Gitora detected that the query did not run successfully and displayed the “Send Error to AI” button. Click this button to inform the AI about the error. Gitora will automatically package the query and the error and send a message to the AI on your behalf.

Using the AI Assistant to Analyze Errors

The Gitora AI Assistant can also be used to analyze errors during SQL, PL/SQL execution.

In the screenshot below, I wrote a simple query but misspelled the table name.

Clicking the question mark button under the Errors tab sends the error message along with the text (or the selected text) in the SQL pad to the AI Assistant like so:

Using the AI Assistant to Explain Queries

The AI Assistant can also be used to explain SQL queries (and PL/SQL blocks.)

In the screenshot below , the SQL pad contains an SQL query with the PIVOT command.

Clicking the question mark button in the toolbar will send a message to the AI Assistant asking it to explain the code.

These are just a few examples about how you can use the Gitora AI Assistant and its schema-aware capabilities. OpenAI GPT models are very capable and I am sure you will come up with many more use cases.

How to Use The Gitora AI Assistant

Fri, 21 Jul 2023 13:48:51 +0300

This article explains how to configure and use the Gitora AI Assistant.

Create an OpenAI Account

Gitora AI Assistant uses OpenAI GPT to suggest PL/SQL code, functions, procedures and SQL in real time, right from the editor. Therefore it requires an OpenAI account and subscription. The OpenAI subscription is on a pay-as-you-go basis and is extremely affordable. To give you a rough idea, during the development of this feature I’ve spent about a dollar a month to use the OpenAI API’s.

You can create your account from the OpenAI website.

Enter Your Credit Card Information

After you create your account, go to Manage Account -> Billing -> Payment Methods and enter your credit card information. You will only be billed for what you use.

Generate an API Key

Finally, generate your API Key. You will enter this key to the Gitora PL/SQL Editor so that it can start making suggestions while you code.

Start The Gitora PL/SQL Editor

From the home screen, register a database and a database user if you have not already done so. To learn how you can register a database and a database user please read Getting Started with the Gitora PL/SQL Editor.

Click one of the connect buttons in the home screen. The PL/SQL Editor will open in a new tab.

Note the new AI icon on the toolbar of the PL/SQL Editor.

Click the small arrow text to the AI icon. The AI Assistant Settings button will show up.

Click the button. The AI Settings dialog will show up.

Enter your Open API Key to the API Key field.

The settings dialog has two more parameters:

Temperature: This is the setting that tells the AI how creative it should be while making suggestions. It accepts any value between 0 and 2. In my experience, 0 worked best but feel free to experiment with different values.

Delay: The AI Assistant makes suggestions when you stop typing. This is the amount of time it waits in milliseconds, before it starts the process to come up with a suggestion. 1000 milliseconds may be a little bit on the higher end depending on your style. I recommend you to experiment with lower values such as 500, 250 etc…

The shorter the delay, the more requests Gitora will make to the OpenAI API, meaning you will spend more money. The API is extremely affordable though so I don’t think this will be an issue but I thought I’d mention it. At the time of the writing of this tutorial, the API costs about $0.002 per 1,000 tokens. 1000 tokens is about 750 words. Again, for reference, I spent about a dollar a month while building this feature.

After you are done with the AI Settings Dialog, click save.

The AI icon should turn black on the toolbar to indicate that the AI is on. (or if you are in the dark mode, the icon will turn white.) If it is not turn on, click the AI icon to enable it. Clicking the icon again will disable the AI Assistant.

From this point on, by default, the AI Assistant will be enabled whenever you open a new PL/SQL Editor as long as you have a registered OpenAI API Key.

If you’d like to remove your OpenAI API Key, enter a space character as the API Key in the AI Assistant Settings dialog and click save.

Using the Gitora AI Assistant

Open a package or any code object and start coding. You can also open an SQL Pad. When you stop typing, the code suggestions of the AI Assistant will show up as lightly colored text in the editor. Click the tab button to accept the code suggestion. If you’d like to accept just a part of the suggestion, hover over the suggestion. A small dialog window will pop up.

Using this dialog, you can accept individual words in the suggestion.

That’s it! Happy coding!

Configuring the PL/SQL Debugger

Wed, 12 Jul 2023 14:30:48 +0300

Gitora Editor includes a PL/SQL debugger. For the PL/SQL debugger to work, the database session being debugged must be able to access the debugger. This requires you or your DBA to open a port or a range of ports in your Oracle database. To achieve this, follow the steps below:

Execute the script at gitora/GITORA_DEBUGGER_ACL_SCRIPT.sql in the zip file, for every database user that you’d like to use with the debugger. The script is a very small PL/SQL code block:

begin
DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
host => '192.168.1.42',
lower_port => 4000,
upper_port => 4999,
ace => xs$ace_type(privilege_list => xs$name_list('jdwp'),
principal_name => [ORACLE_USER_NAME],
principal_type => xs_acl.ptype_db));
end;

Replace the [ORACLE_USER_NAME] in the text above with the actual name of the Oracle user that you want to be able to use with the debugger and execute the script. Run this script once for every Oracle user that needs to be able to connect to the debugger.

Change the start and end port numbers (both inclusive) as you see fit.

Update the following parameters in the Settings.properties file.

debug.port.range.start: Set this value to the same value you used for the lower_port input parameter.

debug.port.range.end : Set this value to the same value you used for the upper_port input parameter.

debug.server.ip: This is the IP address of the Apache Tomcat server that is running the Gitora Editor web application. This is NOT your desktop’s IP address (although it could be if you are running Gitora locally.) This IP address will be used by the Oracle database session to be able to find and connect to the Gitora debugger.

Below is an example of how the three parameters are set:

debug.port.range.start = 4000
debug.port.range.end = 4999
debug.server.ip = 192.168.1.42

Gitora PL/SQL Debugger

Wed, 12 Jul 2023 14:16:07 +0300

This tutorial explains how to use the PL/SQL debugger that comes with the Gitora PL/SQL Editor.

Open a database object in the editor. Next, click the debug icon in the editor to activate the debug mode.

The icon changes color. The change of color indicates that the open database object (in our example, a PL/SQL package), is now compiled in debug mode. As long as the debug icon has color, every save you make will compile the object in debug mode.

Click left of the line numbers to create a breakpoint. Click again to remove the breakpoint.

Create a new SQL Pad to run the procedure/function with the breakpoint.

Click the Run button to execute the PL/SQL code block. The execution will stop at the breakpoint. The Debug Tab will show up.

On the left side of the editor, you can view the current parameters and their values. Please note that, Oracle does not provide support to view the values of every variable type.

In the middle of the screen, you will see that the execution has stopped at the breakpoint. You can add additional breakpoints, or remove existing ones while debugging.

The debug tab toolbar has five buttons that should be familiar to all programmers. From left to right, you can Step Over, Step In, Step Out of each line of code. The forth button is to resume the execution until the next breakpoint. If there are no breakpoints, the PL/SQL block will execute until completion. The final button suspends all breakpoints for the duration of one execution.

Changing Runtime Values of Variables

Gitora PL/SQL Debugger enables you to change the values of PL/SQL variables during runtime. To change the value of a variable, simply update its value on the left of the screen. To apply your changes to the execution, click the checkbox button at the top of the current parameters view.

Click the X button if you’d like to revert the changes you made to the variable values.

Adding Breakpoints to Multiple Database Objects

In our example, the GITORA_EDITOR.DEBUG_TEST procedure references other procedures, for example the DEBUG_PACKAGE.DEBUG_TEST procedure. You may want to add additional breakpoints to those procedures as well.

To achieve this, locate the procedure in the Schema Navigator and click edit as shown below.

The package opens in another browser tab. Since we activated the debug mode, the new tab is also opened in debug mode. Therefore, the DEBUG_PACKAGE is already compiled in debug mode.

Set a breakpoint in the DEBUG_TEST procedure. Go back to the first browser tab and run the PL/SQL block again.

First, the execution will stop at our initial breakpoint. Click the resume button and the execution will stop at the new breakpoint we created in the DEBUG_PACKAGE.DEBUG_TEST procedure.

Joining a Debug Session

It is also possible to join an existing debug session if you already have a PL/SQL object open in an editor.

Lets assume that we already had the DEBUG_PACKAGE open and would like to add a breakpoint.

Click the triangle icon to the right of the debug button. You will see an additional button

Click Join Existing Debug Session button. The Open Debug Sessions dialog shows up.

Click on the “Debug Session Red” button and the package will become part of your debug session.

Multiple Debug Sessions

Gitora Editor can manage multiple debug sessions concurrently. Each debug session is identified with a unique color for the debug icon. For example, all tabs with a red debug icon belong to the same debug session.

To create a new debug session, open two database objects in separate tabs as shown below

In the GITORA_EDITOR tab, click the debug icon to make it red (if it is not already). In the DEBUG_PACKAGE tab, click the same debug icon. The debug icon will turn blue indicating that the DEBUG_PACKAGE is in a different debug session than the GITORA_EDITOR.

Breakpoints are only visible to the debugger if they are in the same sessions. For example, in the setup above, breakpoints you will create in DEBUG_PACKAGE will not be visible to the other tab that has the GITORA_EDITOR open, because that tab is in a different debug session.

Introduction to the PL/SQL Editor

Wed, 10 May 2023 15:42:57 +0300

In the Gitora Editor Home, click the Connect button next to an Oracle username to open the Gitora PL/SQL Editor in a new tab.

The PL/SQL Editor shows up with an empty SQL Pad that uses the Oracle user you clicked, as its default connection information. The database object browser on the right shows the database objects in the Oracle user you clicked.

Expand the Packages Accordion in the object navigator. The list of packages in the schema will show up. Click the Edit button next to a package.

The Gitora PL/SQL Editor opens the package spec and body in the current browser tab. The editor will open any subsequent database object in a new browser tab.

Before we start editing, let’s go over the list of buttons and features in the editor.

The Toolbar

The toolbar is always at the top of the screen. Below is the list of buttons in the toolbar from left to right and a brief description for each one:

Show/Hide Method List

The Gitora PL/SQL Editor shows a powerful content navigator when a package or an object type is displayed in the editor. This button hides/shows the content navigator. It can be used to create more space for the PL/SQL editors and the SQL Pads.

Undo/Redo

Use these buttons to undo/redo changes you made in the current editor. Since a package and an object type have two editors, one for the spec and one for the body, these editors have separate undo queues.

However, if an editor is split in two using the split editor feature. The split editors share a single undo queue.

Comment Out/In

Select a block of code and click the Comment button to turn it into a block of comment. Conversely, select a block of comment and click the same button to turn the comment to a code block. This feature uses the — notation to create comments and similarly can reverse comments that start with –.

Indent

Select a code block and click the Indent button to shift the block 1 tab size to the right.

Outdent

Select a code block and click the Outdent button to shift the block 1 tab size to the left.

The Context Label

The context label in the middle of the toolbar displays the Oracle username and the database you clicked to open this tab as well as your Gitora Editor user name.

Save

Used to save the changes made to the database object open in the editor. The icon turns dark if there are changes to save.

Split Editor

Splits both the spec and the body editors in two horizontally. The icon turns dark if it is active.

Back/Forward

These buttons work similar to back and forward buttons in a browser. Gitora tracks the locations your cursor has been to in the editors. Clicking the back button takes your cursor to the previous location it was. Conversely, clicking forward button takes the cursor back to the next location.

Find and Replace

The Gitora PL/SQL Editor has a powerful Find&Replace widget that you can use to search for letters, whole words and replace them. You can even search using regular expressions. Clicking the icon the first time displays the widget. Clicking it the second time hides it. You can also use CTRL-F to show the widget.

Feedback

Please use the feedback button to share you comments or inform us about bugs and issues.

Color Mode

Click the color mode button to switch between light and dark mode.

Settings

Clicking the settings button displays the settings window.

In this window, you can set the font size, font family, tab size values for the Gitora PL/SQL editor.

Max Rows value determines the maximum number of rows a query you execute returns.

Text Length sets the maximum length of the text the editor returns. If set, longer text values will be cut at the length you specify.

Tick the Save Layout checkbox, if you’d like the Gitora PL/SQL editor to open reusing the widths and heights you set for the Method List on the left and the Object Navigator on the right.

Click the Save button to store your changes.

About

Click the icon to display the version and build number of the Gitora PL/SQL Editor.

The Workspace

The middle part of the Gitora PL/SQL Editor is your workspace. It consists of three columns. From left to right: the Method List (Package Navigator), the Editors area and the Database Object Navigator.

Each column is separated with a splitter. You can move these splitters left or right to adjust the width each column covers on the screen.

Method List (Package Navigator)

This column displays the procedures and functions in the package or object type that is open for editing in the editor.

The Search Box can be used to filter the methods in the list.

The Refresh button can be used to update the list if any of the new functions or procedures you created is not shown in the list.

The functions and procedures that are both on the spec and the body have a lighter color than the ones that exists only in the body. If a method only exists in the spec, its color is yellow.

Clicking a method name will take the cursor to its location in the active editor.

The Editors

The center of the workspace is where the code editors are. The editor has two types of editors: The PL/SQL editors and the SQL editors.

The Gitora PL/SQL Editor opens the first database object in the current tab. Subsequent objects are opened in new browser tabs.

Both editors provide auto complete suggestions. The default list of suggestions are all the words in the current open database object. After you type a dot character, the editor reads the word left of the dot and shows relevant suggestions depending on whether the word is a schema, a table, a view, a package or an object type. In the picture below, you see the editor recommending a list of method names because the user typed a package name.

Note the arrow sign > in the upper right corner of the suggestions box. Clicking the sign will expand the highlighted selection to display its full text. Change your selection and the expanded area will change with your selection. This is a toggle you can turn on/off with each editor separately.

Gitora detects [schema].[package]. syntax and can show suggestions for database objects in other schemas. In the example below, Gitora recommends the methods in the twi_call package which is in the HR schema.

The SQL Pad

Clicking the plus button next to the Body tab, creates a new SQL Pad which you can use to execute PL/SQL blocks, SQL queries, DML and DDL statements. You can create as many SQL Pads as you’d like.

SQL Pads consist of four rows. The toolbar, the worksheet, the query results and the messages rows. Let’s go over these rows one bye one:

The SQL Pad Toolbar

Each SQL Pad has its own toolbar with five buttons. From left to right:

Execute

Click this button to run your SQL statements.

Commit

Use this button to commit your changes. This button works only with a persistent database connection.

Rollback

Use this button to roll back your changes. This button works only with a persistent database connection.

DBMS Output

Use this button to toggle the DBMS Output on or off.

Connection

Use this button to change the current database connection of the SQL Pad.

When you create a new SQL Pad, by default it is connected to the same database user you clicked on to open the Gitora PL/SQL Editor. This connection is not persistent i.e. the Gitora Editor creates temporary database connections when you run the SQL statements by clicking the Execute button.

To change the database connection an SQL Pad is using click the Connect button. The database connection selection dialog shows up.

The dialog has the following actions:

No Connection: Select this option if you’d like to disconnect the editor from all database connections.

Persistent Connection: Toggle this button to on, if you’d like the connection you will select to be a persistent connection.

New Database: Click this button if the database you’d like to connect to does not exist as an option. This will take you to the Create New Database screen explained the the Introduction to the Gitora Editor Home tutorial.

Under the New Database button, you will see the list of databases you can connect. Expand the database you’d like to connect to see the available Oracle users that you can connect to.

Select the Oracle user you’d like the SQL Pad to use and the dialog will close. Your SQL Pad is now using your selection as its connection.

Select New User if you’d like to add a new Oracle username to the registered usernames. Your SQL Pad will use the new Oracle user you will register.

Persistent Database Connections

SQL Pads in Gitora PL/SQL Editor support persistent database connections. To create a persistent connection toggle the Persistent Connection button in the Connection Selection dialog as shown above.

After you select a connection, Gitora will create a persistent connection that the SQL Pad will to reuse every time you execute an SQL statement.

You can also share a persistent connection among other SQL Pads you create. To share a persistent connection:

Create a new SQL Pad.

Click the Connection button.

Toggle the Persistent Connection button to on. A new row titled Open Sessions will show up.

Clicking on the Open Sessions row will display existing persistent connections. Click the one you’d like the new SQL Pad to use and the new pad will share the same database session with the previous pad you created.

Gitora manages the persistent database connections automatically. Closing the last SQL Pad that uses an open database session will close it. Closing the browser tab will also close any unused database sessions.

The file at /gitora/datastore/GitoraEditor/default_pool_properties.json manages several properties that you can edit.

{"maxSizePerUser":25, "timeout":3600, "timeoutCheck":300}

maxSizePerUser property sets the maximum number of open database sessions per user.

timeout property sets the maximum number of seconds a session can remain idle before being closed by Gitora.

timeoutCheck property sets the number of seconds Gitora waits before checking if any session has timed out.

The Worksheet

The worksheet is where you write your SQL statements.

The Query Result

If you execute an SQL query, the results will show up in this row.

The Messages

The messages row has two tabs. The Errors tab shows the errors received while executing the SQL statement in the pad and the DBMS Output tab shows the results of the DBMS Output if there are any. Each SQL pad has its own message row.

The Database Object Navigator

The Database Object Navigator consists of two tabs. The Database Search tab and the Schema Object Navigator.

The schema object navigator shows the seven most commonly used database objects in the database user you are connected to. Just like in the Method List column, you can filter the lists for each object by its name and click the refresh button to display newly created objects.

Selecting and copying an object’s name with CTRL+C copies the objects name in lowercase to the clipboard. The object name is not clickable to make copying easier.

Tables

Each table has a table widget that shows its columns and the foreign keys. Both the column list and he foreign keys can be filtered and refreshed.

In the Columns tab, the column names with a star * indicate primary key columns.

Views

Each view has a view widget that displays its columns.

Each view also has a dropdown button with a list of actions. Clicking the Edit button opens the view in the Gitora Editor (current browser tab or a new tab). You can also Compile and Drop a view.

Packages (Types)

Package and Types work the same way. So we will only go over packages.

Each package has a widget that displays its procedures and functions. Similar to the Method List column, the private methods are in dark color and the public methods are in a light color.

Uncompiled packages have a red icon.

Each package also has a dropdown button with a list of actions. Clicking the Edit button opens the package spec and body in the Gitora Editor. If the current tab already has an open database object, the object is opened in a new browser tab. Otherwise, it is opened in the current tab. You can also compile or drop the spec and the body of a package.

If a package’s spec or body is in an uncompiled state, the dropdown will show the relevant compile action in red.

If a package is missing the body, the compile and drop actions for the body will not show up in the button dropdown.

Functions

Each function has a dropdown button with a list of actions. Clicking the Edit button opens the function in the Gitora Editor (current browser tab or a new tab). You can also Compile and Drop a function.

Procedures

Each procedure has a dropdown button with a list of actions. Clicking the Edit button opens the procedure in the Gitora Editor (current browser tab or a new tab). You can also Compile and Drop a procedure.

Triggers

Each trigger has a dropdown button with a list of actions. Clicking the Edit button opens the trigger in the Gitora Editor (current browser tab or a new tab). You can also Compile and Drop a trigger.

Messages

The bottom row in the editor shows error messages received from the database when you save a database object. Clicking an error will take the cursor to the location of where the error has occurred and highlight that row for a few seconds.

Database Search

The other tab in the third column of the workspace is the Database Search tab. In this tab, you can search for any text in the entire database code base or only in a schema.

The searches are case insensitive.

The results are grouped by schema and database object.

The icons indicate the type of object that the searched term is found in. The closed package icon indicates a package spec and an open package icon indicates a package body.

Click on an object to view the lines in the object that contain the searched term.

Clicking the line number will open a new Gitora PL/SQL Editor in a new tab. The new tab will have the database object with the search term open in the editor and the line number you clicked on will be the top line in the editor.

Getting Started With the Gitora Editor Home App

Mon, 08 May 2023 16:53:04 +0300

The first time you sign in, the Gitora PL/SQL Editor Home Screen will detect that you do not have any databases saved and ask you to create your first database and the first Oracle username and password for it.

Enter a descriptive name and the JDBC URL to connect to the database as seen in the screenshot above.

If you are a Gitora Version Control (GVC) customer, enter your credentials for this database under the Gitora Version Control Credentials header. The Editor will use this information to automatically sign you in to the GVC every time you open a database session. Otherwise, leave these fields empty.

Enter the Oracle username and password you’d like to use to open a session and select the role you’d like to connect as, if it is different from the default.

If you are a GVC customer and use your Oracle user as your GVC credentials, tick the checkbox otherwise leave it unchecked.

Click save.

The Databases screen shows up.

Please note that Gitora Editor Home does not create databases or database users for you. The screens below are used to add existing databases and database users to your home screen.

The Databases Tab

This is your Gitora Editor Home screen where you can jump to all of your databases with the user you’d like to connect as.

Clicking the Connect button will open a the PL/SQL Editor in a new tab.

Click the Delete button removes the database from your list of databases.

The Create New Database button show you the screen where you created your first database.

Click the Edit button to manage the Oracle users you can use to connect to a database.

The Edit Database screen show up.

The Edit Database Screen

You can edit the name and the JDBC URL on this screen.

If you are a GVC customer, enter your Gitora Version Control user name and password to the credentials fields, if not leave these fields empty.

Click the Create New User button to add a new Oracle user to the database. The Create Database User screen shows up.

Enter your Oracle username and password. Select the role the user should connect as if it is different from the default. If you are a GVC customer, check the Use as Gitora Version Control Credentials checkbox if you are using this Oracle user also as your Gitora User Name.

Click save to add a new user to the database.

Use the Edit button to update the credentials for a user and the Delete button to remove it from the database.

The Users Tab

The Users Tab shows up for users with the admin role and can be used to manage the Gitora Editor users.

You can filter users using the search field. Click the Delete button to remove a user from the application. Click the username to edit a user.

Click the Create New User button, to add a new Gitora Editor user. The Create New User screen shows up.

Enter a username (not to be confused with the an Oracle username. This is your Gitora Editor username.) and a password. Select a role for the user (admin or regular) and click save.

Introducing Gitora 7

Fri, 28 Apr 2023 11:36:59 +0300

We are excited to announce the launch of Gitora 7, which includes a groundbreaking addition to our suite of tools:

The Gitora PL/SQL Editor

The Gitora PL/SQL Editor represents a fresh approach to writing PL/SQL code, drawing on the latest advances in code editors to deliver an unparalleled experience to the PL/SQL community. Packed with modern features that are intuitive and easy to use, this editor represents a significant leap forward in coding in PL/SQL.

Let’s take a quick look at some of the features that make the Gitora PL/SQL Editor so remarkable:

Beautiful Design
The Gitora PL/SQL Editor boasts a beautiful, modern design that makes it easy on the eyes and intuitive to use. With Bootstrap 5 components and Font Awesome icons, you can rest assured that the editor will be both stylish and functional.
Dark Mode
When you’re working long hours on code, the last thing you want is to strain your eyes. That’s why the Gitora PL/SQL Editor comes with a gorgeous dark mode that is easy on the eyes and perfect for long coding sessions.
Single Page Web Application
Designed from the ground up for a multi-monitor, multi-tab world, the Gitora PL/SQL Editor is a single-page web application that allows you to open multiple editors in many browser tabs across multiple monitors. This means that you can work on complicated tasks without losing your place.
Auto Complete Suggestions
The editor’s smart auto-complete suggestions make it easy to find what you’re looking for. Whether you’re typing package, procedure or function names, the editor will suggest relevant options to help speed up your workflow.
Package (and Object Type) Content Navigator
Navigating between package procedures, and functions is a breeze with the package content navigator. With just a single click, you can easily move between different parts of your code.
Split Editor
The split editor lets you work on two sections of your code simultaneously, making it easy to compare code or write related sections side by side.
Go Back/Forward in the Editor
The editor remembers the locations of your cursor, allowing you to easily navigate back and forth between different parts of your code with just a click, much like a browser’s back/forward buttons.
Go to Definition
With the CTRL+click command, you can quickly go to the definition of any database object in the code, allowing you to move between different parts of your project with ease.
Code Folding
Code folding lets you get a better view of the code structure by folding code blocks, making it easier to read and understand large chunks of code.
Integrated with the Gitora Version Control
Finally, the editor is fully integrated with the Gitora Version Control, allowing you to use it independently or from within the Gitora Version Control application. This makes it easy to manage your code changes and keep track of your work as you go.

We hope you’re as excited about the Gitora PL/SQL Editor as we are! With its many powerful features and intuitive design, we’re confident that it will be a game-changer for Oracle database developers everywhere.

Download Gitora 7 today to see what it can do for you!

Gitora 6.5 is available

Mon, 12 Dec 2022 18:18:46 +0300

We are happy to announce that Gitora 6.5 is available for download. This version’s new feature is Jira integration.

Gitora customers can now associate a Git repo with a Jira project and enforce that each commit message in the repo references a Jira issue.

To associate a Jira project with your repo, select the repo from the main screen and select the Repo -> Edit Repo menu option.

Enter your Jira user name (usually an email) your API Token, your Jira domain and the issue key you are using for the project and click save.

From this point on, Gitora will not let developers commit to Git without a reference to a Jira issue in their commit message.

For example, the screenshot below shows a failed commit attempt, because the developer did not reference a Jira issue in the commit message:

Typing GIT-1 in the commit message will reference the Jira issue GIT-1 and the commit will go through. After a push to BitBucket, this reference will show up as a link in BitBucket, pointing back to the referenced Jira issue. Similarly, the Jira issue will show this commit as a related commit.

Gitora will check if the referenced Jira issue in the commit message exists in the Jira issue repository.

To remove the Jira project from a repo, open the repo edit dialog and remove all information related to the Jira project and click save.

You can obtain your Jira API key from your Atlassian account’s security page. Here is a direct link to the API Token management page: https://id.atlassian.com/manage-profile/security/api-tokens

Please note that, your account must have read access to the Jira project so that Gitora can query the Jira issue references.

You can download Gitora 6.5 from this link.

Gitora 6.4 is available

Thu, 24 Nov 2022 12:48:07 +0300

Gitora 6.4 is available for download. This version has the following changes:

Many bug fixes
Minor UI improvements
Completely new internals for the web application.
A new repo level security model. Admins can now determine who can access which repo.
Redesigned Gitora API’s. (https://blog.gitora.com/gitora-api-documentation/)
Enforce Compilation feature.

Enforce Compilation Feature:

Starting with 6.4 you can enforce that database objects developers commit to Git must be in a valid state. To do this, select your repo from the main select box and click the Edit Repo menu option.

The Edit Repo Dialog shows up:

Simply, check the Enforce Compilation checkbox and click save. From this point on, Gitora will ensure that every database object being committed to Git is in a valid state.

What Should be in a Valid State to Commit?

If the Enforce Compilation checkbox is checked, Gitora will follow the rules below to determine if an object can be committed to the repo:

The object must be in a valid state
If the object is a package or an object type and has a body, the body must also be in a valid state.
If the object is being referenced by other database objects, and the references are NOT checked out by other developers, these database objects must also be in a valid state.
If Gitora finds an invalid object, it will attempt to compile it and will not allow the developer to commit if the compilation fails.
Gitora will not allow developers to add a database object to a repo, if it is in an invalid state.

You can download Gitora 6.4 from this link.

Signing In to Gitora For Database Development

Tue, 15 Nov 2022 12:26:32 +0300

After you add a database object to Gitora, it cannot be edited unless the developer authenticates herself to Gitora from the database session she opened to edit the object.

There are two ways to log in to Gitora:

Signing In with a Gitora User

Use the api_gitora.login procedure to authenticate yourself to Gitora. After a successful sign in you can edit the database objects managed by Gitora (based on your Gitora privileges).

Procedure: api_gitora.login(in_user_cd varchar2, in_password_tx varchar2)

Signing In with a Database User

Gitora can recognize Oracle users as valid Gitora users. This is a quick and easy way to give all your developers a Gitora user if each of them use separate Oracle users to log in to the database. There won’t be additional user names and password for your developers to remember and they will not need to authenticate with Gitora after they open a database session, saving them a step in their workflow. Gitora will automatically recognize their database sessions as authenticated.

To achieve this follow the steps below:

Sign in to the Gitora web app as admin.
Select the menu option Database -> Users. The Users screen shows up.
Click the Create New User button. The Create New User screen shows up.
Enter the Oracle User Name of the developer to the User Name field. This will disable the password fields. Select a role for the user. This role specifies the priviliges the user has in Gitora. Click Save and your Oracle User is ready to be used as a Gitora user.

Gitora API Documentation

Mon, 14 Nov 2022 18:40:19 +0300

This is the Gitora API documentation for version 6.2 and above. For the API documentation of the older versions please go to this link.

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

Output of API Calls

Each API call returns a JSON Object. This object has the following three properties:

message: The message returned from the API, if any.

result: returns the word success if the API was executed successfully or the word error if there was an error during the execution.

If the result property returns the value error then the message property contains the error message.

token: Returns the token value to be used to call other API’s. This property is only populated after a successful call to the login API.

Developers must receive a token from the login API before executing any other API call. Therefore, it makes sense to describe the login method first.

Method: authenticate

Use to sign in to Gitora. It returns a token that you can use to execute other API’s.

Parameters:

user: A valid Gitora username.

password: Password of the Gitora user.

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

Example: http://localhost:8080/gitora/api?method=authenticate&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

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.

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:

schema: Schema of the object to check out.

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

name: Name of the object to check out.

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

Example:

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

Method: reset

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

Parameters:

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

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

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: commit

Commits a list of objects to the specified repo.

Parameters:

message: Commit message.

ddls: A JSON array of DDL statement ID’s captured by Gitora.

objects= A JSON array of database objects. Example: [{“schema”:”DEV”, “type”:”PACKAGE”, “name”:”HR_PKG”},{“schema”:”DEV”, “type”:”PROCEDURE”, “name”:”HIRE_EMP”}] . Valid values for type are: TABLE, PACKAGE, VIEW, PROCEDURE, FUNCTION, TRIGGER, SYNONYM, TYPE, SEQUENCE, MATERIALIZED_VIEW.

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= [{"schema":"DEV", "type":"PACKAGE", "name":"HR_PKG"},{"schema":"DEV", "type":"PROCEDURE", "name":"HIRE_EMP"}] &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: Indicates whether the new branch should be set as the active branch. Set to true to make the new branch the active branch, to false if you’d like the keep the current active branch.

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.

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.

type: Type of the repo to be created. Valid values: msr (Multi Schema Repo), ssr (Single Schema Repo)

schema: This parameter is only valid for single schema repos. It indicated which schema the repo is for.

track: Indicates whether this repo should track hard object changes in this repo. Valid values are: Y (for the schema to track the hard object changes), N (for the schema not to track hard object changes.)

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

Example:

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

http://localhost:8080/gitora/api?createrepo&repo=HR_REPO2&type=ssr&schema=HR&track=Y&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.

Example:

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

Method: fetchfromdb

Fetches a branch from a Gitora repo to another.

Parameters:

fromdatabase: The name of the database to fetch from. (Name of the database connection in Gitora.)

fromrepo: The name of the repo to fetch from.

frombranch: The name of the branch to fetch.

torepo: The name of the repo to fetch to. (The destination repo.)

tobranch: The name of the branch in the destination repo.

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

Example:

http://localhost:8080/gitora/api?fetchfromdb&frombranch=feature_1&fromrepo=HR_REPO&fromdatabase=DEV&torepo=HR_REPO&tobranch=feature_1&&token=Hjnf74hehd

Method: fetchfromremote

Fetches a branch from a remote repo to a Gitora repo.

Parameters:

torepo: The name of the Gitora repo. to fetch to.

tobranch: The name of the branch to fetch to.

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

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

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.

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.

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

Example:

http://localhost:8080/gitora/api?fetchfromremote&torepo=HR_REPO&tobranch=feature_1 &remotebranch=feature_1&password=myPersonalAcessToken1&remote=myRemoteHRRepo&user=myGitHubUser&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.

Example:

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

Method: getmyobjects

Returns the list of checked out database objects by the signed in 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 a 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.

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.

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

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

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.

Example:

http://localhost:8080/gitora/api?method=merge&repo=HR_REPO&commitid=Uhee8jGdy&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:

fromdatabase: Name of the database the pull from. (Name of the database connection in Gitora.)

fromrepo: Repo to pull from.

frombranch: Branch name to pull.

torepo: Repo to pull to.

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

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&fromdatabase=DEV&fromrepo=HR_REPO&frombranch=master&torepo=HR_REPO&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: 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.

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: 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=JSON Object specifying the database object to be released. Example: {“schema”:”HR”, “type”:”PACKAGE”, “name”:”HR_PKG”}. Valid values for type are: TABLE, PACKAGE, VIEW, PROCEDURE, FUNCTION, TRIGGER, SYNONYM, TYPE, SEQUENCE, MATERIALIZED_VIEW.

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

Example:

http://localhost:8080/gitora/api?method=release&object= {"schema":"HR", "type":"PACKAGE", "name":"HR_PKG"} &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

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

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

Example:

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

Are You Really Using a Version Control System for Your Database or Are You Ticking a Box?

Thu, 13 Oct 2022 12:32:42 +0300

You use a version control system to solve certain problems, to accomplish certain tasks. These are:

Keep track of who changes what, when and why.
If necessary, use previous versions of the code base for testing, development etc…
Move changes between environments faster, with fewer errors during deployment.
Improve productivity of the team (i.e. less time coordinating manually and more time developing. For example different developers working on the same parts of the code base simultaneously and merging their changes at a later time, hopefully mostly automatically.).

If you are using a version control system but not accomplishing any of the things above, are you really using a version control system?

Here is a perfectly reasonable scenario that I’ve seen in the real world. I’ve seen this scenario with teams using Git with SQL Developer, SVN/Git with another Oracle PL/SQL IDE. Invariably, they all end up here:

In the DEV database, you make changes to the package PKG_HIRING in the HR schema and then commit the package under /HR/PKG_HIRING.sql file in Git.
Next, another developer makes changes to the same package. He commits his changes under /HR/next_version/PKG_HIRING.sql, because… why not? It’s not like there is any enforcement.
A third developer commits his changes to /HR/PKG_HIRING.pkb because for some reason, the tool he uses for editing uses the .pkb suffix for packages.
The fourth developer named John, decides to copy PKG_HIRING to a file and work on it. He thinks he can move his changes to the database later. So he creates /HR/JOHN_DO_NOT_TOUCH/PKG_HIRING.sql
A fifth developer, makes changes to the HR.PKG_HIRING package but forgets to commit the package to Git. Hey it happens…
A sixth developer makes even more changes. He commits the package to Git under HR/PKG_HIRING.sql thereby committing not only his changes but also the fifth developers changes.

Three months later, you are tasked with deploying the latest version of the HR application to the TEST database. Which PKG_HIRING package are you going to deploy to TEST?

I actually know the answer to this question. You will deploy the one in the HR schema. It’s the safest option. I cannot help but wonder tough.. in these past three months, did John save his changes to the database? If so, how did he do it? Did he simply overwrite the package? What if some changes were lost?

At this point, I have to ask… Why do you even have a version control system? Why does that Git/SVN repo even exist? Is it useful at all or are you just doing all this just to tick a box and to be able to say that you are using a version control system?

Gitora solves all these problems above. It creates a version control system around Git and enforces it at the database level.

Let’s repeat the same steps for the six developers but this time let them use Gitora:

In DEV, you make changes to the PKG_HIRING package in the HR schema. When you are done, you open the Gitora web app, you see the list of database objects you changed, you select the ones you want to commit (in this case PKG_HIRING) you add a comment to the commit (such as the ticket number) and click the commit button.
The second developer follows the same process as you. He cannot make any changes to the package until you are done with it. Once you are done, he can make his changes. He opens the Gitora App, commit his changes to Git and is done. Note that, he doesn’t get to choose which folder he saves the PKG_HIRING.sql file to. Gitora creates a well structured working directory with reasonable folder and file names for database objects. The locations of these files are also standard. When there is human decision involved with naming and putting files in the file system, a lot of errors can occur. Gitora prevents these errors.
The third developer’s IDE used the .pkb extension for his file. Since developers don’t get to name the files or choose the folders they save database object scripts to, the third developer also has no choice but to follow the same process as the first two developers. By the way, Gitora works with any IDE. You can use SQL Developer, SQL Navigaor, TOAD or PL/SQL Developer. It doesn’t matter. Everyone in your team can use a different editor if they choose to do so. Gitora still works.
The fourth developer was impatient. He created a new file under JOHN_DO_NOT_TOUCH and saved his changes to that file. With Gitora, he has no direct access to Git and the Git working folder. (Gitora is a server side solution. You don’t install Git to developer’s computers.) So he cannot do that. However, if he wants to do mischief, he still can copy the PKG_HIRING package to a new file in his computer and make changes there. Then, he can simply overwrite everything in the PKG_HIRING package with his version at a later time. This will cause some changes to be lost in the package depending on when he does it. He can even go ahead and commit his changes to Gitora. But hold on a second. At some point, either during development or testing, the mistake he made will be detected. In the first scenario, there is no way to know for certain who erased all the functioning code and exactly what code should be put back to the package. It will be trivial to use Git to figure out who deleted the perfectly functioning code from PKG_HIRING because Gitora always keeps track of who changed what, when and why. Since we can know when the mistake happened, we will know the correct version of the package to put back to. John will take the heat for his egregious mistake and merge his changes to the correct version of the package. No one wants that kind of heat. It is easy to see that Gitora incentivizes the right kind of behavior among teammates by keeping everyone accountable for their actions as well as making it possible to recover from critical mistakes.
The fifth developer simply forgot to commit his changes to Git. With Gitora there are two ways this can be caught. First, the sixth developer who wants to edit the package will contact the fifth developer to ask when the package will be available. Second, Gitora web app always shows which objects are locked by whom. So before preparing a deployment, you can always check if there are any database objects that are locked.
In the first scenario, the sixth developer committed fifth developers changes along with his. With Gitora, the sixth developer will always commit only his changes because there is no way he can gain access to the PKG_HIRING without the fifth developer releasing the package first. Gitora enforces that if an object is being edited by someone, no one else can edit it. With Gitora, version control is not something you do on the side but it is tightly integrated into your workflow and enforced.

And finally, three months later, you are tasked with preparing the deployment to TEST. How are you going to move the changes to the TEST database? With Gitora, all you need to do is to open the Gitora app, connect to the TEST database and pull the HR repo from DEV to TEST and you are done.

Going back to the begining of the article; Gitora makes Git a useful version control system for the Oracle Database.

As shown in the second scenario with Gitora you can:

Keep track of who changes what, when and why.
We caught John misbehaving.
If necessary, use previous versions of the code base for testing, development etc…
We recovered an old version of PKG_HIRING and have John merge his changes to it.
Move changes between environments faster, with fewer errors during deployment.
Done via point and click Gitora Web Application.
Improve productivity of the team (i.e. less time coordinating manually and more time developing. For example different developers working on the same parts of the code base simultaneously and merging their changes at a later time, hopefully mostly automatically.).
The second scenario reduced manual coordination significantly. Gitora can do a lot more. You can have different teams work on the same code base at the same time and merge their changes just like Java, JavaScript developers. However that’s beyond the scope of this article. Please read this article and this article to learn more about how you can implement parallel development with Gitora.

Automatically log in to Gitora when connecting to Oracle

Wed, 07 Sep 2022 17:22:59 +0300

In order to modify database objects that are managed by Gitora source control, the user first needs to log in to Gitora with a user name and password.

Usually this is no problem, but we lately encountered a case where this was a problem.

To be more specific, we still use Oracle Designer (yes, i know..) to maintain our Database Models. From Designer we generate database changes to our development database that is managed by Gitora.
Almost all changes from Designer can be generated as scripts and you can add the Gitora login there,
but we also generate TAPI packages from Designer and these are generated directly to the database without the option of generating scripts. So that was a problem. Also having to manually add the Gitora login to all scripts is quite tedious.

The solution is to use a database after logon trigger.
But we had more requirements:

Log in to Gitora as an actual user, not a database user
Track what applications are used to log on
Log succesfull and failed login attemps

Here is how we solved it:

First we need a table to match the Gitora username and passwords with the possible Operating System user names.
(I will not secure the passwords in this example, i leave that up to you if you need it)

create table GITORA_USERS_MATCH
(
  os_user     VARCHAR2(64) not null,
  gitora_user VARCHAR2(64) not null,
  gitora_pw   VARCHAR2(64) not null
);

alter table GITORA_USERS_MATCH
  add constraint GUH_PK primary key (OS_USER);

Then a second table to log successfull and failed login attempts.

create table GITORA_LOGON_TRG_LOG
(
  logon_message VARCHAR2(512) not null,
  logon_date    DATE not null
);

Now we can create a trigger:

create or replace trigger gitora_auto_logon_trg
   after logon on database
declare
   l_program     varchar2(100);
   l_gitora_user gitora_users_match.gitora_user%type;
   l_gitora_pw   gitora_users_match.gitora_pw%type;

   cursor c_gitora_user
   is
      select guh.gitora_user
      ,      guh.gitora_pw
      from tmi_sys.gitora_users_match guh
      where upper(guh.os_user) = upper(sys_context('userenv','OS_USER'))
      ;

begin
   /* Get the program that is connecting.
      For example:
     'dwfde61.exe'      -- Oracle Designer Generator
     'sqlplusw.exe'     -- Oracle sqlplus
     'sqlplus.exe'      -- Oracle sqlplus
     'SQL Developer'    -- Oracle SQL developer
     'Toad.exe'         -- Toad
     'plsqldev.exe'     -- PL/SQL Developer
     'JDBC Thin Client' 
   */
   select program
   into   l_program
   from   v$session
   where  audsid=sys_context('USERENV','SESSIONID');

   insert into tmi_sys.gitora_logon_trg_log 
      (logon_date
      ,logon_message
      ) 
   values 
      (sysdate
      ,'logon: os_user: '''||sys_context('userenv','OS_USER')||''' program: '||l_program
      );

   open  c_gitora_user;
   fetch c_gitora_user
   into  l_gitora_user
   ,     l_gitora_pw;
   close c_gitora_user;

   if l_gitora_user is null
   then
      -- log failure to match os_usr to Gitora user
      insert into tmi_sys.gitora_logon_trg_log 
         (logon_date
         ,logon_message
         )
      values 
         (sysdate
         ,'os_user name '''||sys_context('userenv','OS_USER')||''' cannot be matched to a Gitora user)'
         );
   else
      -- try to log on to Gitora. 
      begin
         gitora.api_gitora.login(l_gitora_user,l_gitora_pw);
      exception
         when others
         then
            -- just log, no need to raise
            insert into tmi_sys.gitora_logon_trg_log 
               (logon_date
               ,logon_message
               ) 
            values 
               (sysdate
               ,'Login to Gitora failed for username '||l_gitora_user
               );
         end;
   end if;
exception
  when others
  then
     -- this trigger should never cause a user to not be able to log in to the database.
     -- It only needs to check if an os_name can be linked to a Gitora user.
     null; 
end;

With this in place, you can connect to the database with any tool you want and log in to Gitora automatically.

Michiel Arentsen, Rhenus

Managing Tables with Single Schema Repos

Thu, 05 May 2022 16:56:42 +0300

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:

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.
Pull from HR_HARD_OBJECTS_REPO to HR_JOE_HARD_OBJECTS_REPO and to HR_JANE_HARD_OBJECTS_REPO.
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

Thu, 05 May 2022 16:54:31 +0300

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.

Create a single schema Gitora repo that manages the LOGISTICS schema. Let’s call it the REPO_LOGISTICS.
Add all relevant database objects in the LOGISTICS schema to the LOGISTICS_REPO.
Create another single schema Gitora repo that manages the LOGISTICS_TEST schema. Let’s call it the REPO_LOGISTICS_TEST
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 separate 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:

Create a schema for each developer: LOGISTICS_JOE, LOGISTICS_MARY, LOGISTICS_PAUL.
Create a single schema Gitora repo for each schema. Let’s call them REPO_LOGISTICS_JOE, REPO_LOGISTICS_MARY, REPO_LOGISTICS_PAUL respectively.
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

Thu, 05 May 2022 16:54:19 +0300

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:

If you are using one shared development schema in a single database
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

Thu, 05 May 2022 16:54:03 +0300

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

The Single Schema Repo Creation Dialog show up.

Enter a unique repo name. (In this example, we’ll call it SSR_1)
Select the schema the SSR is associated to. (In this example it will be associted to the HR schema)
Leave the Manage Schema Changes unchecked for now.
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.

Open the REPO_LOGISTICS_TEST repo in Gitora.
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.

Reserving Database Objects for Authorized Users

Tue, 02 Mar 2021 12:01:45 +0300

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

Tue, 02 Mar 2021 10:35:25 +0300

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

Thu, 11 Feb 2021 20:32:22 +0300

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 code base using only one development database and send only code related to one project to the test database?

Update: Gitora 6 introduced Single Schema Repos (SSR). SSR’s enable developers to work on different projects with different deadlines in the same code base using only one development database. Please read our Gitora 6 announcement post for more.

User Privileges in Gitora Enterprise

Tue, 26 Jan 2021 13:40:10 +0300

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

Sun, 24 Jan 2021 16:17:22 +0300

This is the Gitora API documentation for version 6.1 and below. For the latest API documentation please go to this link.

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.

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.

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

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:

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

Thu, 21 Jan 2021 16:57:40 +0300

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

Wed, 20 Jan 2021 16:07:25 +0300

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

Thu, 02 Apr 2020 22:43:52 +0300

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

Tue, 31 Mar 2020 21:31:03 +0300

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

Thu, 07 Sep 2017 07:26:48 +0300

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

[sql]
ALTER TABLE COUNTRIES MODIFY (COUNTRY_NAME VARCHAR2 (200))

ALTER TABLE EMPLOYEES ADD (MIDDLE_NAME VARCHAR2 (25))

ALTER TABLE COUNTRIES ADD (CURRENCY_NAME VARCHAR2 (200))
[/sql]

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:

[sql]
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;
[/sql]

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

Thu, 25 May 2017 20:58:57 +0300

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:

If you are using one shared development database
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:

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.

ODTUG Webinar about Version Control for PL/SQL

Thu, 23 Feb 2017 20:24:53 +0300

This week I hosted a webinar for ODTUG members about how to implement a version control solution for the Oracle Database using Git. Many thanks to the 119 attendees who joined the live event. I am very happy to see that version control is now being recognized as a serious pain point among Oracle Database customers.

Please see below for the video and the slides of the presentation:

Webinar Video and Slides

Thu, 09 Feb 2017 00:11:39 +0300

Last week, we hosted another webinar to talk about Gitora and how it helps Oracle developers manage their PL/SQL code base. Below are the slides we used during the webinar:

You can watch the recording of the webinar below:

Gitora in 30 Minutes

Mon, 16 Jan 2017 20:09:11 +0300

Gitora is the version control tool for PL/SQL. It hooks Git to the Oracle Database and enables you to manage your PL/SQL code base easily. Below is a 30 minute demo video which explains the benefits of Gitora and how it works.

Rhenus Uses Gitora

Mon, 26 Dec 2016 23:10:51 +0300

It’s been a little over three months since we released Gitora 2.0 and the first success stories have already started to surface. Here is one of them:

Rhenus Logistics, the leading logistics company from Germany uses Gitora to manage their Oracle Database.

Problem

Rhenus IT uses both Java and PL/SQL to serve their users and customers. They have a team of about 10 PL/SQL developers. The team manages more than 20,000 database packages, views, functions, procedures, object types and triggers spread over 30+ database schemas.

Rhenus IT wanted to move to a continuous delivery environment in which they can be more agile and deliver solutions to the business faster. Managing the PL/SQL code was the hardest piece of the puzzle.

Solution

After experimenting with other solutions in the market, Rhenus decided to move forward with Gitora.

Gitora enabled Rhenus Developers to:

Use Git, the prominent open source version control system used by millions of developers.

Move their database code between development and various staging databases automatically.

Move code between source and target databases very fast because Gitora only executes differences between source and target databases, without comparing the code bases in both databases first (which can be very time consuming).

Enforce check-in, check-out of database objects at the database level.

Automate build process for the database code using Gitora API’s.

Implement an affordable continuous delivery solution compared to alternatives.

Michiel Arentsen, the System Architect at Rhenus who implemented the solution at Rhenus has started an excellent blog in which he writes about his Gitora implementation. We highly recommend you to check it out. Below are the list of blog posts he wrote which should be very useful to anyone who is currently implementing Gitora at his/her company:

Using Gitora in PL/SQL Developer dual or multi session mode

Automatically log in to Gitora when connecting to Oracle

A fast way to load your database objects to a Gitora repository

Automatically add new database objects to Gitora

Start Gitora as a Windows service

Gitora 2.1 is available with tagging support

Tue, 06 Dec 2016 12:13:01 +0300

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

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

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

A dialog shows up.

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.

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

Tue, 29 Nov 2016 20:41:37 +0300

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

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

Gitora, Version Control for PL/SQL from Gitora

Gitora Webinar

Wed, 09 Nov 2016 20:55:58 +0300

OK, so you read the web site, downloaded Gitora, installed it successfully, created a few test repositories, added a few packages, issued a few Git commands from the Gitora UI. And it all works fine. But now what? How do you actually start using Gitora in your development life cycle? How can you actually benefit from it?

In order to show you how you can use Gitora in your daily work we are hosting a free webinar on November 22nd. You can register at: http://www.prohuddle.com/webinars/Gitora/Version_Control_for_PLSQL_Developers.php

During the webinar we will cover the following topics with a live demo:

How can you use Gitora to manage your PL/SQL code base?
Why is using version control with PL/SQL is hard and how does Gitora help?
Why is Gitora the best solution for the problem?
How will using version control with PL/SQL will help you?

The webinar is free but space is limited. Sign up today.

Kind Regards,
Yalim Gerger
Founder

Installing Gitora Manually

Thu, 29 Sep 2016 15:34:16 +0300

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

For Linux and Mac OS, install Git manually from https://git-scm.com/. For Windows, Git is already included to this setup.
Move Gitora2 folder to the place you want to locate Gitora middle tier components.
e.g /Users/username/
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.
Set GITORA_ROOT parameter to the absolute path of the Gitora2 folder from step 1..
e.g /Users/username/Gitora2
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
For Mac OS and Linux, set GIT_EXECUTABLE parameter to the path of git executable.
e.g. /usr/bin/git
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

Connect to the Oracle Database with the SYS user
Run 01_SYS.sql
Disconnect from SYS
Connect to the database with the GITORA user
Run 02_GITORA.sql
Ensure that there are no invalid packages in GITORA schema.
Create a row in table GITORA.T_TEMP_APPLICATION
Copy the contents of Gitora.xml to this newly created row
Issue a commit to save this row to the database.
Run 03_GITORA.sql
Disconnect from GITORA user
Connect to the database with SYS user
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.
For Windows, change the value of “folderSeparator” parameter from ‘/’ to ‘\’.
Run 04_SYS.sql
Disconnect from SYS.

Starting Up Gitora

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
Open your browser and type http://[MIDDLE TIER IP ADDRESS]:7997/gitora/main.html name=Gitora

Generating a Diff Script with Gitora

Mon, 26 Sep 2016 14:52:31 +0300

Gitora enables developers to move changes between databases with a single click.

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

Assume that we are connected to the preprod database and would like to generate a sync script to upgrade prod to the same state the preprod database is in.

Open the Gitora Application. Select a repo. Next, click the Git –> Utilities –> Get Script button from the menubar. A dialog shows up.

The Starting Commit ID is the Git Commit ID that is currently deployed in prod. Target Commit ID is the Git Commit ID that we would like to upgrade the prod database to.

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

If you’d like the script to include soft objects (i.e. database objects that execute with CREATE OR REPLACE such as packages, views etc…) check the Include Soft Objects checkbox.

If you’d like the script to include hard objects (i.e. database objects that doesn’t execute with CREATE OR REPLACE such as tables) check the Include Hard Objects checkbox.

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

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

Please note that the table generation is master-detail relationhip aware i.e. the generated tables will be in the correct order with master tables coming before detail tables that reference them.

Introducing Gitora 2.0

Thu, 22 Sep 2016 19:55:02 +0300

Today, we are happy to announce the general availability of Gitora 2.0. We listened to the feature requests coming from the community and we think we are addressing the majority of them with this new version.

Object Type Support

Gitora now supports Object Types. Object Types are supported for the Oracle version 11g and above.

Generate Diff Scripts

Gitora 2.0 helps you create diff scripts between two commit points in your Git repository. Simply, enter the starting Commit Point ID and the target Commit Point ID and Gitora will generate a diff script for you to run in your target database.

Clone Source Code from Another Database

Gitora 2.0 supports cloning Git repositories from remote databases. Connect your local Gitora to the remote Gitora (which manages a remote database) and move the code base from one database to the other automatically.

Pull(Merge), Fetch Source Code from Another Database

Similar to cloning, developers can now pull(merge) source code from a remote database to the source code in a local database automatically if both database are running Gitora 2.0.

Many small improvements and bug fixes

Gitora 2.0 also comes with a number of improvements such as:
– A nicer Git repository browser
– Ability to view changes made in each object prior to issuing a commit
– Cancel any edits made to a PL/SQL object since check-out by clicking a button.

New Gitora Editions

Gitora 2.0 comes in three editions:

Gitora Community Edition

Every feature from Gitora 1.0 continues to be free in Gitora 2.0 Community Edition. We even added new features to it such as object type support, ability to view changes made in each object and canceling edits, along with many bug fixes.

Gitora Professional Edition

We believe proper version control is a big problem in the PL/SQL community, hurting the productivity of many PL/SQL developers and discouraging organizations from using PL/SQL. We think we can help. In order to justify further development on Gitora to help the community to solve this problem, remote database features in Gitora 2.0 will be available in the professional addition. The professional edition also comes with email support and unlimited access to 2.X released of Gitora. We think the benefits you will get from Gitora Professional Edition will far outweigh the small price tag we put on it.

Gitora Enterprise Edition

We know that large enterprises usually have their own unique needs. They might need customizations, new features, integration with other products and services they use, training, more timely and intensive support covered with an SLA etc… For these types of customers, we offer a fully customizable version of Gitora.

Gitora 2.0 Professional Edition comes with a long trial period and even if you decide not to purchase it, it gracefully downgrades to the community edition.

So what are you waiting for? Go download Gitora 2.0! 🙂

Benefits of using Gitora, Git for PL/SQL Developers

Tue, 04 Aug 2015 14:33:10 +0300

Outside of the Database World (Java, JavaScript etc..) developers use version control systems more effectively. When used appropriately in the software development life cycle, a version control tool can shorten delivery times significantly by improving the manageability of the code base.

Using version control with PL/SQL (and other database objects) has always been challenging. In our experience very few, if any, IT departments use version control systems to manage their database. Most are content with a basic check-in check-out mechanism.

We created Gitora to help database developers manage their code base better. Gitora achieves this by bridging the gap between the Oracle Database and Git, the most prominent and popular version control system used by millions of developers around the world.

With Gitora you can:

Perform the version control operations using a point and click interface. This reduces the barrier to entry for Git. Only a basic understanding of version control principles is good enough to get value from the product.

Move your code base automatically to a specific version (for example to match it to the version in production.)

Create new branches to work on new features without affecting the master code base.

Change between different branches of your code base automatically.

Merge your branches to the master code base automatically.

Push your changes to remote repos in cloud services such as GitHub, GitLab and BitBucket.
Pull changes from other databases and merge these changes with your database code.

Browse the Git repository and see your commit history and changes associated with each commit.

Collaboration vs. Parallel Development

Gitora can be used in collaboration mode in which all database developers work in the same Oracle Schema(s). In this case Gitora supports a check-in check-out mechanism. This check in/out mechanism is tool independent. It works with SQL Developer, TOAD and PL/SQL Developer (or any other tool for that matter).

More importantly, Gitora can also be used in parallel development mode in which every database developer works in her own schema(s). In this way of working, (which is exactly how Java, .NET, JavaScript developers etc.. are working) each developer has her own copy of the database code and is free to make changes to them related to the task she has at hand. In parallel mode, no developer blocks the other because she is the only one who checks out the objects in her own schema(s). This improves development times significantly because more than one developer can work on the same logical object at the same time.

The software development team establishes a workflow to merge the changes of each developer and propagate these changes to the master code base. Gitora (via Git) also helps with this process with automated merging of changes. In the event of a conflict (where Git cannot figure out how to merge changes done by two developers to the same code unit) Gitora asks the user to resolve the conflict. Gitora creates multiple versions of the database code objects in question and helps the developers to resolve the issue. (Please see Introduction to Gitora, Git for PL/SQL developers for more information on this topic)

Best to our knowledge, Gitora is the only tool that is specifically designed to be used for parallel development with PL/SQL. We think parallel development is where a software team starts to get a lot of value from using a version control system. This helps establishing a formal workflow of incorporating changes to the master code base and to production.

Gitora integrates to your software development lifecycle. We cannot overstate how important this is. Gitora is not something you do on the side and it does not have back doors where you can circumvent version control. It becomes an essential part of your daily workflow. There are version control tools that people use on the side by copying and pasting scripts. This is a very error prone process because it requires developers to “remember” to do version control. Some version control tools only work within a specific tool (such as TOAD) and do not prevent the developer from opening another tool (such as PL/SQL developer) and modify code without using proper version control mechanisms.

For more information about Gitora, we recommend you to visit the following links:

Gitora Webinar Recording (and Slides)

Six Common Question About Gitora

What is the Difference between Gitora and SQL Developer’s Git Interface

Webinar Video and Slides

Mon, 09 Mar 2015 14:47:46 +0200

Below you can find the recording and the slides of the Gitora Webinar. Thanks to everyone who attended. What a turnout!

Introducing Gitora, the free version control tool for PL/SQL from Yalim K. Gerger on Vimeo.

Introducing Gitora, free version control tool for PL/SQL from Yalım K. Gerger

Six Questions About Gitora

Mon, 26 Jan 2015 15:57:21 +0200

Recently. we received an email from a Gitora user with six questions. We think our answers might be interesting for others as well. So here they are:

1. Where is the remote repository created?
Gitora does not use a remote repository in its first version. Everything is handled using local repositories. You can still use a remote repository if you want. There is nothing in Gitora preventing you from doing that.

2. How do you lock database objects?
The users decide which database objects Gitora should manage. When a DDL is executed, a database level trigger created by Gitora ensures that the Oracle user running the DDL is signed in to Gitora and checked out the database object it is manipulating if it is an object managed by Gitora. If the object is checked out by another user already, the trigger throws an exception. There is a PL/SQL API for a database user to sign in to Gitora in her database session. Optionally, she can use the Gitora App to check out an object. Gitora is also quite pragmatic and automatically checks out the object if it is not currently checked out by anyone else.

3. Is there any relation between Gitora users and Database Users? If there isn’t any relation, how do I create Gitora users?
There is no relation between Gitora users and database users. You can use the Gitora App to create Gitora users. Then, to check out an object managed by Gitora, you can sign in to Gitora by either using its PL/SQL API or the Gitora App.

4. Do I have to log in to Gitora every time I create a new database session?
You have to log in to Gitora in a database session only if you want to modify a database object or check out a database object managed by Gitora. Signing in is a single line API call that probably can be automated by your PL/SQL development tool.

5. Where is the version history stored?
Everything related to versioning is done and stored in the Git repository. Gitora is only a bridge between the Oracle Database and the Git server.

6. How can we integrate Gitora to TOAD? Is there a plug-in?
There is no need for a plug-in. Gitora works with any PL/SQL development tool. It has a small set of PL/SQL API’s that you can call from any development tool. Gitora also has a web app you can use to perform common version control tasks.

What is the Difference between Gitora and SQL Developer’s Git Interface?

Wed, 21 Jan 2015 17:29:15 +0200

We’ve been getting this question a lot lately, so I thought it is a good idea to write a blog post about it.

In SQL Developer, you work in two ways:

You edit objects in the database and then you manually create files in a folder managed by Git.
You edit files managed by Git and execute them in the database.

SQL Developer helps you run Git commands on these files. When you issue a Git command that changes your code base, you have to manually carry over the changed code units to the database by running the scripts.

In Gitora, if you modify a PL/SQL code unit in the database, you do not need to manually copy the updated script to a folder managed by Git. Gitora does that automatically. Similarly, if you issue a Git command using Gitora’s point and click interface, Gitora automatically updates the PL/SQL code units in tha database. Gitora also has a check out mechanism that works at the database level, meaning that if you check out a PL/SQL code unit, no one else can edit it until you release or commit it. This is enforced at the database level. So there are no back doors.

So the advantages of Gitora’s approach are:

– A lot less manual work. Every edit you make is synced to the file system by Gitora. Every Git command you execute, updates your database code automatically.

– A lot less human errors. Copying files back and forth manually is very error prone.

– Much easier team work. Gitora’s check out mechanism prevents others from making changes to objects you are working on.

– Well structured working directory. Gitora creates a well structured working directory with reasonable folder and file names for database objects. The locations of these files are also standard. When there is human decision involved with naming and putting files in the file system, a lot of errors can occur. Gitora prevents these errors.

– No back doors. Gitora enforces that if an object is being edited by someone, no one else can edit it. Version control is not something you do on the side but it is tightly integrated into your workflow and enforced.

– It works with any editor. You can use SQL Developer, SQL Navigaor, TOAD or PL/SQL Developer. It doesn’t matter. Everyone in your team can use a different editor if they choose to do so. Gitora still works.

Yalim K. Gerger

Introduction to Gitora, Git for PL/SQL Developers

Fri, 31 Oct 2014 16:52:14 +0200

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

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

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

Reset
Create Branch
Change Branch
Merge Branch
Fetch
Pull
Push

Gitora Web App

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

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

Creating A Version Control Repository

Open Gitora Web App and select Git->Repo-> New Repo from the menu bar. The Create a New Repo Dialog shows up.

Enter a name for your repository (A Gitora repository can contain PL/SQL objects from any database schema.) Click Save. Click OK in the Alert Box which shows the message received from Git. Note that the Gitora Web App makes the new repository you created the active one and the repository viewer focuses on it.

Adding Database Objects to a Gitora Repository

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

To add database objects to a Gitora repository, select Git-> “Add/Remove Objects” item from the menu bar.

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

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

Finally, select one or more objects from the list of available ones and add them to the list of managed objects. Add as many objects of different types as necessary.

A Note About Adding a Large Number of Objects

The Dialog supports adding tens even hundreds of objects at once, using the Add All button. However, this may take time because Gitora will extract the DDL of these objects and create files. If the number of objects you are adding to the repo at once is very high, the browser may prompt you that the application is unresponsive or the session in the Tomcat Server might expire (in about an hour).

If you are building a large Git repo, we recommend that you either add the objects in chunks or use the Gitora API’s.

Click “Done” to close the dialog.

A Gitora repository can manage database objects from multiple schemas. To add database objects from another schema simply change the schema name selected in the dialog’s select box and continue as described above.

Collaboration vs. Parallel Development

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

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

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

Editing a Database Object Managed by Gitora

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

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

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

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

logout;signs out of Gitora

No Sign In Development

Gitora 5 can be configured to recognize Oracle Users as valid Gitora users. This eliminates the need to sign in to Gitora using the PL/SQL API above. We recommend this approach in environments where every developer has her own Oracle User.

To achieve this, log in to Gitora as an admin. Next, click the [Database Name]-> Users menu item from the menu bar. The Manage Users page shows up.

Click the Add button on the page. The Add User dialog shows up.

Enter the Oracle username to the User Name field (LISA in the screenshot). Check the Oracle User checkbox. The password fields will be disabled. The user will use her Oracle credentials to log in to Gitora. If you are using Gitora Enterprise, select a database role for the user, as well.

Click the Save button.

From this point on, the user (LISA in the example) can log in to the Gitora application with her Oracle username and password. She also doesn’t need to sign in to Gitora first to modify database objects managed by it because Gitora will recognize her as a valid user.

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

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

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

Committing Database Object Modifications

At any time the developer can view the list of objects she checked out from the “Git -> Commit” menu item.

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

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

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

The page has a section named “Managed Schema DDL’s”. We’ll talk about this section in a different blog post.

Gitora requires a developer to enter a short description of the changes she is commiting to the Commit Changes text area. This description comes in very handy when going over the history logs.

Clicking the Commit button commits the selected objects to the Git repo.

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

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

Releasing an Object

If the developer wants to remove her edit lock on an object she checked out, she can do so by right clicking the object in the navigation tree and clicking the Release menu item. Please note that this will cancel all her changes to the object and the object will revert back to the latest state it is in on the active branch of the repo.

Resetting to a Commit ID

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

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

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

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

Please note that the reset command (just like every other command in Gitora) will only update the soft objects in the database. Soft objects are defined as objects that work with the CREATE OR REPLACE command. Therefore, it will not change any table, sequence or materialized view in the database.

Creating a Branch

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

To create a new Branch click the “Git -> Create Branch” menu item. A dialog shows up.

Enter a name for the new branch. Enter the name of another branch, a tag name or a Commit ID as the starting point of the new branch. Keep the checkbox checked if you want to make this branch the active branch in the database.

Click the “Create Branch” button to create the new branch. Once it is created, the code base automatically switches over to the newly created branch if the Make Active Branch checkbox is checked.

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

Changing Branches

In order to change the current branch of the repository, open Gitora Web App, select a repo from the main select box and select the “Git -> Change Branch” menu item. A dialog shows up.

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

Important Note: Git commands executed by Gitora only update soft objects. Soft objects are defined as database objects that work with the CREATE OR REPLACE command. Therefore Gitora does not change any tables, sequences and materialized views in the database.

Merging a Branch to another Branch

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

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

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

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

A conflict may occur if;

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

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

It creates the database object in an uncompiled form with changes from both source and destination in it.
It creates the database object with “$M” (short for my object) suffix in its name which represents the content of the object in the destination branch before the merge.
It creates the database object with “$T” (short for their object) suffix in its name which represents the object in the source branch.

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

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

Resolving Conflicts in Table, Sequence and Material View DDL’s.

Gitora 5 keeps track of table DDL’s just like it keeps track of soft objects. However, it does not update the database with the new definition of a table during a merge. Yet, a merge conflict might still occur in a table DDL if the table DDL was modified in two different branches.

In such a case, Gitora will show the table in the merge conflict screen. The table name will have a .sql suffix to indicate that the conflict is in a file managed by Git but the database is not affected. Gitora also provides an edit button for the user to edit the DDL text and resolve the conflict.

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

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