Using IntelliJ Plugin for Development

Browse tables and execute queries on your Oracle NoSQL Database Cloud Service instance or Oracle NoSQL Database Cloud Simulator from IntelliJ.

The Oracle NoSQL Database Cloud Service IntelliJ plugin connects to a running instance of Oracle NoSQL Database Cloud Service or Oracle NoSQL Database Cloud Simulator and allows you to:

This article has the following topics:

Setting Up IntelliJ Plug-in

Learn how to set up the IntelliJ plug-in for Oracle NoSQL Database Cloud Service instance or Oracle NoSQL Database Cloud Simulator.

Prerequisite:

Install IntelliJ IDEA. You can download IntelliJ IDEA from JetBrains.

Procedure:

You can install the plugin as follows:

  1. Open the Oracle NoSQL DatabaseConnector page, JetBrains plug-in repository .

  2. Select Get.
  3. From the Versions menu, select Download for the latest version of the Oracle NoSQL Database Connector.
  4. In the pop-up window, follow the on-screen instructions under How to Install ‘Oracle NoSQL Database Connector’.

Restart the IDE. You will see the Schema Explorer icon on the right panel.

After you successfully set up your IntelliJ plugin, create a NoSQL project, and connect it to your Oracle NoSQL Database Cloud Service instance or Oracle NoSQL Database Cloud Simulator.

Creating a NoSQL Project in IntelliJ

Learn how to create a NoSQL project in IntelliJ.

Perform the following steps:

  1. Open IntelliJ IDEA. Click File > New > Project.
  2. Enter a value for Project Name and Project Location. Select Create.
  3. Select a build system and JDK path.
  4. IntelliJ creates your NoSQL project directory, which includes a sample Java file. If you have selected Maven as the build system, your project directory also includes a pom.xml file.
  5. Make sure Notifications are enabled for your Oracle NoSQL project. To enable Notifications, press Alt+\ to open Main Menu. Click View, expand Tool Windows > Notifications. A Notification Icon notification-bell-icon appears on the right tool window bar.

After you successfully created a NoSQL project in IntelliJ, you can connect your project to Oracle NoSQL Database Cloud Service or Oracle NoSQL Database Cloud Simulator.

Connecting to Oracle NoSQL Database Cloud Service from IntelliJ

Learn how to connect your NoSQL project to Oracle NoSQL Database Cloud Service using the IntelliJ plugin

Perform the following steps:

  1. Open your NoSQL project in IntelliJ.

  2. Click the task icon task-icon in the Schema Explorer window to open the Settings dialog for the plugin.

  3. Expand Tools > Oracle NoSQL in the Settings Explorer, and click Connections.

  4. Select Cloud from the drop-down menu for the Profile type. You can view all the existing connections for the Cloud profile type under the Connections dropdown.

  5. Click Add Connection. You have two options to create a connection.

    1. Using configuration file: You specify the configuration file path, which points to the location of the OCI configuration file stored on your local system. This file contains the essential parameters required to connect to Oracle NoSQL Database Cloud Service such as region, tenant ID, user ID, fingerprint, passphrase, and private key path.

      Enter the required values for the following connection parameters and select ADD. Then select OK.

      Table - Connection Parameters Configuration File Option

      Parameter Description Sample Value
      Connection Name A unique name, that is given to a specific connection specification is mandatory from the plugin version 1.5.1. Updating the Connection Name field is recommended after upgrading the plugin from version 1.4.0 or lower.

      Note: You can add multiple connections and the stored connection specifications are persistent.      		 ndcs_con1
      Configuration File Path of a directory where the configuration file is stored in the local system. For more information about the configuration file and its contents, see User Principals method in Authentication to connect to Oracle NoSQL Database. ~/.oci/config
      Profile Name of the profile.

      Note: You can create multiple profiles with different values for these entries, and then you can specify which profile to load.      		 DEFAULT
      Compartment (Optional) The compartment OCID/compartment name for your NoSQL database schema.

      Note: When you specify the compartment name, you need to specify the entire hierarchy with a colon separating each entry.      		 developers:dev1.

      Here dev1 is a compartment under the compartment developers.



      Note: If no value is specified, it defaults to the Root compartment.

      The plugin connects to the region specified in the configuration file.

      If you use Session token-based authentication, your configuration file includes the designated profile for session-token along with the token path. To connect to Oracle NoSQL Database Cloud Service, you must select the configuration file option and specify the appropriate profile.

    2. Advanced: You directly specify the connection parameters required to connect to Oracle NoSQL Database Cloud Service. Enter the required values for the following parameters and select ADD. Then select OK.

    Table - Connection Parameters Advanced Option

    Parameter Description Sample Value
    Connection Name A unique name, that is given to a specific connection specification is mandatory from the plugin version 1.5.1. Updating the Connection Name field is recommended after upgrading the plugin from version 1.4.0 or lower.

    Note: You can add multiple connections and the stored connection specifications are persistent.    		 ndcs_con1
    Endpoint Regional network access point to the Oracle NoSQL Database Cloud Service. https://nosql.us-ashburn-1.oci.oraclecloud.com (for the Ashburn Oracle NoSQL Database Cloud Service region identifier in the North America region. See Data Regions and Associated Service Endpoints for a list of service endpoints.
    Tenant ID and User ID Tenancy’s OCID and User’s OCID for your Oracle NoSQL Database Cloud Service. See Where to get the Tenancy’s OCID and User’s OCID in Oracle Cloud Infrastructure Documentation.
    Fingerprint and Passphrase(Optional) The fingerprint and passphrase of the signing key created while generating and uploading the API Signing Key. See the following resources in Oracle Cloud Infrastructure Documentation:

    - To generate the signing key with an optional passphrase, see How to Generate an API Signing Key.
    - To get the key’s fingerprint, see How to Get the Key’s Fingerprint.
    Private Key The private key generated for the user. For the application user, an API signing key must be generated and uploaded. See How to Generate an API Signing Key to generate the signing key with an optional passphrase.
    Compartment (Optional) The compartment OCID/compartment name for your NoSQL database schema.

    Note: When you specify the compartment name, you need to specify the entire hierarchy with a colon separating each entry.    		 developers:dev1.

    Here dev1 is a compartment under the compartment developers.



    Note: If a value is not specified, it defaults to the Root compartment.

    Note:

    • Starting with version 1.5.4, the IntelliJ plugin automatically downloads the latest Oracle NoSQL Java SDK and sets the SDK path when creating a connection.

    • If you are updating the plugin from version 1.4.0 or lower, all the stored connections migrate to the new version. In this case, the Connection Name will be the same as Endpoint. Follow the below step to change the Connection Name.

  6. The IntelliJ Plugin saves the connection details in the connection name specified. To modify the connection details, choose the connection name in the drop-down for Connections. Click Modify Connection. You can change any of the connection parameters (mentioned above) and click OK to save the settings. To remove a connection name from the plugin, choose the connection name and click Delete Connection. Once you confirm the action to delete, the connection name is removed from the plugin.

  7. Click the Web icon in the Schema Explorer. The list of existing connections is displayed in the drop-down box. The connection name will be displayed in the NoSQL tool window in the following format:

    Table - Connection Display

    Option used to create a connection Display in the NoSQL tool window
    Advanced Connection Name:Endpoint:Compartment Name/OCID (if other than root)
    Use Configuration File Connection Name:Configuration file path:Profile:Compartment Name/OCID (if other than root)

    Choose the connection and click OK. The IntelliJ plugin connects your project to Oracle NoSQL Database Cloud Service and displays its schema in the Schema Explorer window.

After you successfully connect your project to your Oracle NoSQL Database Cloud Service, you can manage the tables and data in your schema.

Connecting to Oracle NoSQL Database Cloud Simulator from IntelliJ

Learn how to connect your NoSQL project to Oracle NoSQL Database Cloud Simulator using the IntelliJ plugin.

Perform the following steps:

  1. Download and start Oracle NoSQL Database Cloud Simulator. See Downloading the Oracle NoSQL Database Cloud Simulator .

  2. Open your NoSQL project in IntelliJ.

  3. Click the task icon task-icon in the Schema Explorer window to open the Settings dialog for the plugin.

  4. Expand Tools > Oracle NoSQL in the Settings Explorer, and click Connections. You can view all the existing connections for the Cloudsim profile type under the Connections dropdown.

  5. Select Cloudsim from the drop-down menu for the Profile type.

  6. Click Add Connection. Enter values for the following connection parameters, and click OK.

    Table - Connection Parameters

    Parameter Description Sample Value
    Connection Name A unique name, that is given to a specific connection specification is mandatory from plugin version 1.5.1. Updating the Connection Name field is recommended after upgrading the plugin from version 1.4.0 or lower.

    Note: You can add multiple connections and the stored connection specifications are persistent.    		 nosql_sim1
    Service URL The IP address and port on which the Oracle NoSQL Database Cloud Simulator is running. The default value is http://localhost:8080
    Tenant Identifier Unique identifier to identify the tenant. The default value is exampleId. Retain this value if you want to test the examples.

    Note:

    • Starting with version 1.5.4, the IntelliJ plugin automatically downloads the latest NoSQL Java SDK and sets the SDK path when creating a connection.

    • If you are updating the plugin from version 1.4.0 or lower, all the stored connections migrate to the new version. In this case, the Connection Name will be the same as Endpoint. Follow the below step to change the Connection Name.

  7. The IntelliJ Plugin saves the connection details in the connection name specified. To modify the connection details, choose the connection name in the drop-down for Connections. Click Modify Connection. You can change any of the connection parameters (mentioned above) and click OK to save the settings. To remove a connection name from the plugin, choose the connection name and click Delete Connection. Once you confirm the action to delete, the connection name is removed from the plugin.

  8. Click the Web icon in the Schema Explorer. The list of existing connections is displayed in the drop-down box. The connection name will be displayed in the NoSQL tool window in the following format:

    Connection Name:service Url : Tenant Identifier

    Choose the connection and click OK. The IntelliJ plugin connects your project to the Oracle NoSQL Database Cloud Simulator and displays its schema in the Schema Explorer window.

Note: Before connecting your project to Oracle NoSQL Database Cloud Simulator, it must be started and running. Otherwise, your connection request will fail in IntelliJ.

After you successfully connect your project to your Oracle NoSQL Database Cloud Simulator, you can manage the tables and data in your schema.

Creating applications using Oracle NoSQL Java SDK from IntelliJ

Learn to create applications from IntelliJ plugin using the Oracle NoSQL Java SDK package.

After connecting to the Oracle NoSQL Database Cloud Simulator or Oracle NoSQL Database Cloud Service, you can create applications using Oracle NoSQL Java SDK.

In this topic, you will run a sample application available within the Oracle NoSQL Java SDK package to create a table in Oracle NoSQL Database Cloud Simulator or Oracle NoSQL Database Cloud Service.

Perform the following steps:

  1. Download the latest Oracle NoSQL Database Java SDK from GitHub.

  2. Extract (unzip) the downloaded file in a local repository.

  3. Launch IntelliJ IDEA and open your NoSQL project.

  4. If you are using the Maven build system, ensure that you have added the required dependencies in pom.xml. For details, see Oracle NoSQL Java SDK GitHub.

  5. From the extracted Oracle NoSQL Database Cloud Service Java SDK directory, navigate to the oracle-nosql-java-sdk > examples folder. Copy the BasicTableExample and Common java files to your NoSQL project directory.

    The BasicExampleTable program creates a table called audienceData, adds two rows into this table, queries the inserted rows, deletes the inserted rows, and finally drops the audienceData table.

  6. Before running the application program, you must provide the necessary arguments to connect:

    a. From the menu, select Run > Edit Configurations.

    b. Select Add New Configuration and then select Application.

    c. In the window that appears on the right, enter your main class in the Name field.

    d. Under Build and run, specify the Java JDK path and enter the main class.

    e. Enter the required program arguments. Select Apply and then select Okay.

    Table - Program Arguments

    Connection Type Program Arguments More Information
    Cloudsim http://localhost:8080 If you started the Oracle NoSQL Database Cloud Simulator on a different port, you must replace 8080 with that port number.
    Cloud Region [-configFile <path-to-config-file>]

    For example:

    us-ashburn-1 -configFile D:\OCI_PROP\config    		 The first argument indicates the data region of your Oracle NoSQL Database Cloud Service. The second argument passes a configuration file that contains the credentials to connect to the Oracle NoSQL Database Cloud Service. For information on configuration file content, see Authentication to connect to Oracle NoSQL Database.

    If you don’t specify the config file, the script uses the default constructor for the SignatureProvider class, which looks for the config file at:

    $HOME/.oci

  7. To run this program, select Run or press Shift + 10.

    Note: If you want to run the program from a terminal, use the following sample commands:

    Compile the program using the maven build system using:

    mvn compile

    Run the program by supplying the program arguments:

    mvn exec:java -Dexec.mainClass=BasicTableExample -Dexec.args="<region>"

    Example: mvn exec:java -Dexec.mainClass=BasicTableExample -Dexec.args="us-ashburn-1"

  8. View the output in the Run tool window at the bottom. Verify the logs to confirm that the code execution is successful. You can see the display messages that indicate table creation, rows insertion, and so on.

Sample output:

  Creating table audienceData
  Created table audienceData
  Put row: {"cookie_id":123,"audience_data":{"audience_segment":{"sports_lover":"2018-11-30","book_reader":"2018-12-01"},"ipaddr":"10.0.00.xxx"}} result=non-null Version
  Got row: {"cookie_id":123,"audience_data":{"audience_segment":{"sports_lover":"2018-11-30","book_reader":"2018-12-01"},"ipaddr":"10.0.00.xxx"}}
  Inserted row via query, result:
  {"NumRowsInserted":1}
  Got row inserted by query: {"cookie_id":106,"audience_data":{"audience_segment":{"foodie":"2020-06-01","sports_lover":"2020-05-10"},"ipaddr":"10.0.00.xxx"}}
  Put row from json: {"cookie_id":456,"audience_data":{"ipaddr":"10.0.00.yyy","audience_segment":{"sports_lover":"2019-01-05","foodie":"2018-12-31"}}}
  Got row inserted as JSON: {"cookie_id":456,"audience_data":{"audience_segment":{"sports_lover":"2019-01-05","foodie":"2018-12-31"},"ipaddr":"10.0.00.yyy"}}
  Query results for SELECT * from audienceData WHERE cookie_id = 456:
  {"cookie_id":456,"audience_data":{"audience_segment":{"foodie":"2018-12-31","sports_lover":"2019-01-05"},"ipaddr":"10.0.00.yyy"}}
  Deleted key {"cookie_id":456} result=true
  Dropping table audienceData

  Process finished with exit code 0

Note: As the BasicExampleTable deletes the inserted rows and drops the audienceData table, you can’t view this table in the Schema Explorer. If you want to see the table in the Schema Explorer, comment the code that deletes the inserted rows and drops the table, and rerun the program.

Managing Tables Using the IntelliJ Plugin

Learn how to create tables and view table data in Oracle NoSQL Database Cloud Service or Oracle NoSQL Database Cloud Simulator from the Schema Explorer .

Perform the following steps:

  1. Locate the Schema Explorer, and click the Refresh icon icon to reload the schema.

  2. Locate your table under your tenant identifier, and expand it to view its columns, primary key, and shard key details. If you created a sample application as described in the Creating applications using Oracle NoSQL Java SDK from IntelliJ topic, you will be able to see the audienceData table.

  3. Double-click the table name to view its data. Alternatively, you can right-click the table and select Browse Table.

  4. A record viewer window appears in the main editor. Click Execute to run the query and display table data.

  5. To view individual cell data separately, double-click the cell.

Perform DDL operations using IntelliJ

You can use IntelliJ to perform DDL operations.

Some of the DDL operations that can be performed from inside the IntelliJ plugin are

CREATE TABLE

DROP TABLE

CREATE INDEX

DROP INDEX

ADD COLUMN

DROP COLUMN

Freeze/UnFreeze Schema

You need to freeze the schema of a singleton table before making it a Global Active table. Once you freeze the schema of the table, you cannot make any changes to the schema. To freeze the schema of a singleton table, it should have at least one JSON column. Right-click on the table and choose Freeze/Unfreeze. Once you confirm, the schema of the table gets frozen. Similarly, to unfreeze the schema of the table, right-click on the table and choose Freeze/Unfreeze. Once you confirm, the schema of the table is changed back to mutable which means the schema can be altered.

Note: The table regional replicas need to be dropped (the table must be a singleton table) before the unfreeze operation can be performed.

Manage Replicas

See Regional Table Replicas to understand what are replicas and how to convert a singleton table to a Global active table by adding regional replicas.

Add Replica

You can add a regional replica to a singleton table, to make it a Global active table or add a replica to an existing Global active table. The table should be frozen before you add a replica to it. Right-click on the table and choose Add Replica from Regional Replicas. You can choose a replica from the dropdown of the Replication region. You can decide on the Read Units and Write Units of the table in that replication region. The Disk Storage value for the table cannot be changed/edited in the replica. Click Add Replica. The table gets replicated in the region.

View Replica

Right-click on the table and choose View Replicas from Regional Replicas. You can view the list of replicas for the table.

Drop Replicas

Right-click on the table and choose Drop Replicas from Regional Replicas. Click Add and choose a replica to be removed. You can choose more than one replica to be dropped at a single time. Click Remove if you want to remove the replica from the list of replicas that need to be dropped. Click Drop Replicas. Once you confirm, the table is dropped from all the selected replicas.

Edit Reserved Capacity

You can edit the reserved capacity and the usage model of a table. Right-click on the table and choose Edit Reserved Capacity. You can choose one of the two capacity modes - Provisioned capacity or On-demand capacity. Edit the values and click Apply Changes.

If the table that is edited is a Global Active table:

Perform DML operations using IntelliJ

You can add data, modify existing data and query data from tables using IntelliJ plugin.

Insert data

Modify Data - UPDATE ROW/DELETE ROW

Query tables

Note: The drop-down will only show SQL statements related to the table you are working on.

Schema Explorer

In the Schema Explorer window, you can verify the full data type of a particular column. Locate the particular column and the data type is followed by the column name.

Authorization Requirements for IntelliJ Plugin

Learn about the authorization requirements needed in Oracle NoSQL Database Cloud Service to use IntelliJ Plugin.

The IntelliJ plugin allows you to access Oracle NoSQL Database Cloud Service using either API-key authentication or session token authentication methods. Access to resources in Oracle NoSQL Database Cloud Service such as tables, tablespaces, and APIs is managed through Identity and Access Management (IAM) policies. This ensures that only authenticated users, who are members of groups with the appropriate inspect, read, use, or manage table permissions in a given compartment, can interact with these resources. For more information, see Managing Access to NDCS Tables.

When using IntelliJ plugin to manage tables in Oracle NoSQL Database Cloud Service tables, your effective IAM permissions determine which resources you can read from or write to. If a user attempts an action for which they lack authorization, the IntelliJ plugin will return the corresponding authorization error as provided by OCI IAM.

For example, the OCI IAM denies any insert operation on an Oracle NoSQL Database Cloud Service table if your user group only has the “read” permission for NoSQL tables. The following error message is displayed in the IntelliJ plugin:

Error executing Insert Row : Authorization failed or requested resource not found (5.4.18)