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
The example on this page uses Java. To follow the instructions, you need the following:
To add a new connector:
-
Clone the Datagrok's public repository from GitHub:
git clone https://github.com/datagrok-ai/public.git
-
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 thegrok_connect
package:<dependency>
<groupId>com.orientechnologies</groupId>
<artifactId>orientdb-jdbc</artifactId>
<version>3.2.21</version>
</dependency> -
Implement the provider:
-
Go to the providers package in the grok connect folder:
cd public/connectors/grok_connect/src/main/java/grok_connect/providers
-
Create a
.java
file and name using the standard naming convention. For example:OrientDbJdbcProvider.java
-
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.
-
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.
-
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; -
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.
-
Register your provider class in ProviderManager by adding it to the
providersList
in the constructor.
-
-
Build Grok Connect:
Go to the connectors folder with the parent
pom.xml
and run the following command:mvn package -DskipTests
Testing your connector
A live instance of your chosen database.
Testing options:
-
Using
GrokConnectShell
:-
Open
connectors/examples/query.json
and add the necessary details. -
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:
-
From the
/public/connectors
folder, run:java -jar ./target/<NAME OF GROK CONNECT JAR>.jar grok_connect.GrokConnect
-
Open the platform in a browser and go to Data > Databases.
-
In the Database Manager, right-click your new connector and select Add connection... A parameter dialog opens.
-
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.
-