Create custom connectors

The Datagrok server uses the Grok Connect service to connect and retrieve database data. You can extend Grok Connect using a JVM language.

Adding a new connector

prerequisites

The example on this page uses Java. To follow the instructions, you need the following:

• Git to fetch repository with code
• Java 8 to run and compile code
• Maven to build a project. For languages other than Java, add the appropriate Maven plugin to pom.xml and configure it according to the documentation.
• Code editor of your choice.

To add a new connector:

1. Clone the Datagrok's public repository from GitHub:

   git clone https://github.com/datagrok-ai/public.git

2. Add a JDBC driver:

   • As a jar file to public/connectors/grok_connect/src/main/java/grok_connect/lib folder.
   • Using pom.xml if the driver is available on public repositories.

   For example, let's add the OrientDB connector to Grok Connect. Since it's available on Maven, insert the following dependency in the pom.xml of the grok_connect package:

   <dependency>
       <groupId>com.orientechnologies</groupId>
       <artifactId>orientdb-jdbc</artifactId>
       <version>3.2.21</version>
   </dependency>

3. Implement the provider:

   1. Go to the providers package in the grok connect folder:

      cd public/connectors/grok_connect/src/main/java/grok_connect/providers

   2. Create a .java file and name using the standard naming convention. For example:

      OrientDbJdbcProvider.java

   3. In your code editor, open this JAVA file and create a Java class with the same name. Extend it from JdbcDataProvider, which provides basic functionality for all JDBC providers.

      For our example, paste this code to your file:

      public class OrientDbJdbcProvider extends JdbcDataProvider {
          public OrientDbJdbcProvider() {
          }
      }

      Note: For simplicity, we omit all imports.

   4. Set the driverClassName field using the full driver class name. For our example, within the class constructor:

      driverClassName = "com.orientechnologies.orient.jdbc.OrientJdbcDriver";

      Note: To get the driver class name, use the documentation for your chosen JDBC driver.

   5. In the constructor, configure the connection:

      descriptor = new DataSource();
      descriptor.type = "OrientDb";
      descriptor.description = "Query OrientDb";
      descriptor.connectionTemplate = new ArrayList<>(DbCredentials.dbConnectionTemplate);
      descriptor.connectionTemplate.add(new Property(Property.BOOL_TYPE, DbCredentials.SSL));
      descriptor.credentialsTemplate = DbCredentials.dbCredentialsTemplate;

   6. Override the getConnectionStringImpl method for your database.

      For our example, add the following code to the class:

      @Override
      public String getConnectionStringImpl(DataConnection conn) {
          return String.format("jdbc:orient:remote:%s/%s", conn.getServer(), conn.getDb());
      }

      To complete this step, you need to know how the JDBC connection string is built for your database. Refer to the appropriate documentation.

   7. Register your provider class in ProviderManager by adding it to the providersList in the constructor.

4. Build Grok Connect:

   Go to the connectors folder with the parent pom.xml and run the following command:

   mvn package -DskipTests

Testing your connector

prerequisites

A live instance of your chosen database.

Testing options:

• Using GrokConnectShell:

  1. Open connectors/examples/query.json and add the necessary details.

  2. Go to the /public/connectors/grok_connect folder and run the following command:

     java -cp ./target/<NAME OF GROK CONNECT JAR>.jar grok_connect.GrokConnectShell --q <ABSOLUTE PATH TO query.json>

• Using Datagrok running locally:

  1. From the /public/connectors folder, run:

      java -jar ./target/<NAME OF GROK CONNECT JAR>.jar grok_connect.GrokConnect

  2. Open the platform in a browser and go to Data > Databases.

  3. In the Database Manager, right-click your new connector and select Add connection... A parameter dialog opens.

  4. In the parameter dialog, fill in the connection parameters and click TEST. Upon successful connection, the database appears in the Database Manager under the respective data source.

  Note: It may take Datagrok some time to recognize a running Grok Connect. To speed up the process, restart the container.