Metabase IRIS Driver

A custom driver for connecting Metabase to InterSystems IRIS databases. This driver enables Metabase to query, analyze, and visualize data from IRIS databases using the native IRIS JDBC driver.

Here’s a video demo: https://youtu.be/yoaQBg331M4

Table of Contents

Quick Start (Docker)
Building Driver Locally
Development Process
Contributing
License

Quick Start (Docker)

NOTE: If you are following this guide on a Windows machine, you would need to change the iris image in the docker-compose.yaml file.

# docker/docker-compose.yaml

image: containers.intersystems.com/intersystems/irishealth-community-arm64:latest-preview # Change this line

image: containers.intersystems.com/intersystems/irishealth-community:latest-preview # To this

This Quick Start guide is fully contained and comes with a Metabase instance, an IRIS instance and automatically injects the driver for you. If you have your own IRIS/Metabase instance that you want to test the driver on, simply remove the appropriate services in the docker-compose.yaml file (see here for more details) or download the latest driver from the releases page of this repo and use it accordingly. A guide to using community drivers in Metabase can be found here.

For this guide, Docker as well as some basic understanding of IRIS is needed.

Clone this repository and navigate to the docker folder
```
git clone 

cd metabase-iris-driver/docker
```
Start with docker compose:
```
docker compose up -d
```
The following containers will start spinning up:
- metabase: Contains the Metabase instance and listens at port 3000
- setup: Runs the setup.sh script once the metabase container is healthy which creates an admin account with the default credentials
- iris: Contains the IRIS instance and listens at ports 52773 (Web Server Port) and 1972 (Superserver Port)
- iris-setup: Runs the iris-setup.sh script once the iris container is healthy to change the default password to sys.
Both the setup and iris-setup containers will spin down once the respective scripts have finished running. These containers are simply for convinience and do not impact the functionality of the driver in any way.
Add some sample data in IRIS. To keep things simple we are going to add one table with some data to the USER namespace. Execute the following queries:
```
CREATE TABLE Data.Test (
   name varchar(20), 
   city varchar(3), 
   age int
)
```
```
INSERT INTO Data.Test (name, city, age) VALUES ('test', 'nyc', 23)
```
Now you should have a table that looks something like this:
Navigate to Metabase The default URL is localhost:3000

Login using the default credentials:

Username: admin@metabase.local
Password: Metapass123

In the side panel, click on Add a database

Enter the following information:

Database type: Intersystems IRIS
Display name: IRIS                # Feel free to choose whatever you want
Host: iris                        # ONLY if the IRIS instance is running in a container called iris
Superserver Port: 1972            # To check navigate to the IRIS Management Portal > About
Namespace: USER                   # The namespace you want to connect to
Username: _SYSTEM                 # The user you want to connect as
Password: sys                     # Password of the above user

And press Save

Metabase will start syncing table data from IRIS. Once it is done, navigate to localhost:3000/browse/databases and view the tables

You should see this:

Components and Configurations

This method consists of three components which are easily modifiable to your specific needs.

docker-compose.yaml

This simple docker compose file defines four containers metabase, setup, iris and iris-setup.

metabase

Initalises a Metabase instance with a volume defined at ./metabase-data and injects the driver to the appropriate /plugins folder as required in the container.

Parameters:

ports: : # Maps host port to container port

environment.MB_JDBC_DATA_WAREHOUSE_MAX_CONNECTION_POOL_SIZE # Defines the maximum pool size from Metabase to IRIS. Max: 25 (Depending on IRIS license)

volumes # Ensures data is kept beyond the lifetime of a container and injects the driver. NOTE: for the driver to work, it has to be placed in the /plugins folder in the container (this is handled by the 2nd volume instruction)

healthcheck # Runs a curl command in the container to ensure that the Metabase instance is running. The setup container is dependent on this healthcheck

setup (Optional): See below for more information

iris

Initalises an IRIS instance with a volume defined at ./iris-data

Parameters:

ports: : # Maps host port to container port. For IRIS you need to map both the Web Server Port and Superserver Port

environment # Username and password of the default admin user

volumes # Ensures IRIS data is kept beyond the lifetime of a container

healthcheck # Opens an iris terminal session and runs a pwd command to ensure the IRIS instance is running. The iris-setup container is dependent on this healthcheck

iris-setup (Optional): See below for more information

setup.sh

This bash file is used in the setup container to create an admin account which works by making curl requests to the Metabase API. For more information refer to the Metabase API docs

Parameters:

ADMIN_EMAIL
ADMIN_PASSWORD
METABASE_HOST # Depends on the name of the metabase container in the docker compose file
METABASE_PORT # Depends on the docker compose file

# NOTE: You can choose to change these variables by editing this file or through the entrypoint variable in the setup container definition

iris-setup.sh

Similar to setup.sh, this bash script helps with the password change that is required when you log into IRIS for the first time.

Parameters:
```
URL           # Management Portal URL of the IRIS instance 
NEW_PASSWORD  
```

Building Driver Locally

This section outlines the steps one would need to take to build the driver locally in the event any changes to the functionality of the driver is required. All commands below assume you’re working on macOS. Wherever applicable, you’ll find links documenting equivalent instructions for other operating systems.

Prerequisites for Building

Install Clojure CLI: https://clojure.org/guides/install_clojure
```
brew install clojure/tools/clojure
```

Clone Metabase (for building within Metabase context):

git clone https://github.com/metabase/metabase.git

cd metabase

Build Steps

Copy the driver files to Metabase:

cp -r /path/to/metabase-iris-driver/iris-jdbc modules/drivers/

Edit the modules/drivers/deps.edn file to include the iris-jdbc driver in the dependancy list:
```
metabase/iris-jdbc          {:local/root "iris-jdbc"}
```
Make the necessary edits. See Development Process for more information

Build the driver:

clojure -X:build:drivers:build/driver :driver :iris-jdbc

Locate the built JAR:

ls resources/modules/iris-jdbc.metabase-driver.jar

Use the driver
```
~
├── metabase.jar                   
├── plugins
    └── iris-jdbc.metabase-driver.jar   
```
Place the driver in the /plugins folder (create the folder if you haven’t) next to the metabase.jar file and restart your Metabase instance. Alternatively if you’re using following the quick guide and using docker, simply replace the existing driver file and restart the Metabase container.

Development Process

This section attempts to outline the development process I took in order to build this driver. Do note that this is not a exhaustive guide but rather an introductory alternative to the Metabase docs which may be confusing for someone who has never worked on a driver or Clojure before. Additionally, as Metabase is a product that is constantly changing, there is no guarentee that this process will continue to work in the future.

Structure of driver

All Metabase drivers follow the follwing structure:

iris-jdbc
├── deps.edn                   # Dependancy file
├── resources
│   └── metabase-plugin.yaml   # Driver metadata
└── src
    └── metabase
        └── driver
            └── iris_jdbc.clj  # Main driver code

Contributing

Contributions are welcome! Take a look at the issues tracker for ideas!

Development Guidelines

Follow Clojure coding conventions
Add docstrings to public functions
Test with multiple IRIS versions if possible
Update documentation for new features

License

This project is licensed under the MIT License. See the LICENSE file for details.

Note: This driver is not officially supported by Metabase yet and as such will not work on Metabase Cloud.

metabase-iris-driver Works