Skip to main content

Connecting Your Application to InterSystems IRIS

Connect your Python, Java, .NET, or C++ application to an InterSystems IRIS® cloud service, cluster, or instance in three easy steps!

  1. Download the InterSystems driver for DB-API (Python), JDBC (Java), ADO.NET (.NET), or ODBC (C++).

  2. Gather the connection information for the InterSystems IRIS target you want to connect to, which includes:

    • The host identifier (hostname or IP address) and superserver port of the target.

    • Credentials to authenticate to InterSystems IRIS with sufficient privileges to execute the actions to be taken through the connection.

      Note:

      The examples include the username Admin for illustration only; the actual credentials you’ll use depend on the target.

    • The namespace to connect to.

    For the connection information for an InterSystems IRIS cloud service, such as InterSystems IRIS Cloud SQL, go to your deployment’s Deployment Details page in the InterSystems Cloud Services Portal. For detailed information about the connection information for InterSystems IRIS clusters and instances on various platforms, see InterSystems IRIS Connection Information.

    If you want to deploy an instance of InterSystems IRIS for the purpose of making and testing a programmatic connection, see Deploying InterSystems IRIS; options include a free Community Edition instance.

  3. Add the needed code to your application, as explained here.

The rest of this document describes how to connect to InterSystems IRIS from:

Each section illustrates the code in multiple steps, but includes at the end a copyable display of all of the code.

Important:

Application connections to external entities encompass multiple options and can be coded in different ways. The purpose of this document is to provide a single illustrative example that can be quickly examined and understood. Each section also contains a link to more comprehensive documentation for the use of that particular connection type with InterSystems products.

The InterSystems IRIS target you are connecting to may require TLS encryption or other means to protect external connections, and your own security policy may require practices designed to secure connections to external systems. For this reason, each section provides the additional steps required to modify the provided example to connect to an InterSystems IRIS target on which the superserver is configured to require TLS, using a self-signed certificate provided by the target. Again, this is a single, simple example; even within the relatively narrow case presented there are alternatives approaches to coding the TLS connection. (For information about configuring the InterSystems IRIS superserver to require TLS, see Configuring the InterSystems IRIS Superserver to Use TLS

For more detailed online learning content about the use of some of these languages with InterSystems products, see Connecting to InterSystems Products with External Languages. For information about all of the connections tools available from InterSystems, see Connection Tools.

Connect from Python using DB-API

Before using these instructions, you should make sure that:

  • Your development system has the Python IDE of your choice installed and has network access to your InterSystems IRIS target.

  • You have downloaded the InterSystems DB-API driver, intersystems_irispython-version-py3-none-any.whl, to your development system.

  • You have gathered the connection information for the InterSystems IRIS target you want to connect to.

To code a DB-API connection to InterSystems IRIS, follow these steps:

  1. Install the DB-API driver:

    C:\> pip install intersystems_irispython-version-py3-none-any.whl
  2. Import the iris module and create a main method:

    First two lines of code, importing the module and defining the method

  3. Use the connection information for the InterSystems IRIS target to define the connection string, in the form host-identifier:superserver-port/namespace, and the credentials:

    Connection string and credentials added to the main method

    You can also define the host identifier, port, and namespace separately, as shown for the credentials here, and pass all five to iris.connect when creating the connection, as shown for the connection string and credentials in the next step.

  4. Finally, create the connection by calling iris.connect:

    All of the needed code, including the connection

You can copy the code used here from the listing below. For more information about using Python and DB-API with InterSystems IRIS, see Python DB-API Support.

import iris
 
def main():
    connection_string = "host-identifier:superserver-port/namespace"
    username = "username"
    password = "password"
 
    connection = iris.connect(connection_string, username, password)
 
    # when finished, use the line below to close the connection
    # connection.close()
 
if __name__ == "__main__":
    main()
Connecting with TLS

To extend the instructions above to connect with TLS encryption using a self-signed X.509 certificate provided by the InterSystems IRIS target, do the following:

  1. Obtain or download the self-signed certificate as instructed and place it in a secure location.

  2. Modify the code provided above in these ways:

    1. Import the ssl module in addition to the iris module.

    2. Before creating the connection, specify the TLS context and verify the existence of the required certificate.

    import iris
    import ssl
     
    def main():
        connection_string = "host-identifier:superserver-port/namespace"
        username = "username"
        password = "password"
     
        context = ssl.SSLContext(ssl.PROTOCOL_TLS)
        context.load_verify_locations(“path-to-cert/cert-file.pem”)
    
        connection = iris.connect(connection_string, username, password, sslcontext=context)
     
        # when finished, use the line below to close the connection
        # connection.close()
     
    if __name__ == "__main__":
        main()

Connect from Java using JDBC

Before using these instructions, you should make sure that:

  • Your development system has version 1.8 of the JDK and the Java IDE of your choice installed and has network access to your InterSystems IRIS target.

  • You have downloaded the InterSystems JDBC driver, intersystems-jdbc-version.jar, to your development system.

    Note:

    If InterSystems IRIS is installed locally or in a container on your development system, you can also find the file in install-dir\dev\java\lib\JDK18 or install-dir/dev/java/lib/1.8, where install-dir is the InterSystems IRIS installation directory (install-dir in a container is /usr/irissys).

  • You have gathered the connection information for the InterSystems IRIS target you want to connect to.

To code a JDBC connection to InterSystems IRIS, follow these steps:

  1. Add the InterSystems JDBC driver, intersystems-jdbc-version.jar, to your local CLASSPATH.

    generated description: java classpath

  2. Create a main method and import the com.intersystems.jdbc.* libraries.

    First two lines of code, importing libraries

  3. Use the connection information for the InterSystems IRIS target to define the connection string, in the form host-identifier:superserver-port/namespace, and the credentials:

    Connection string and credentials in public class JDBCConnection

  4. Set a new data source using IRISDataSource (or the standard driver manager you may have used to connect to other databases). Set the URL, User, and Password using the connection string and credentials for your target.

    Connection string and credentials used to define data source

  5. Finally, create the connection.

    All of the needed code, including the connection

You can copy the code used here from the listing below. For more information about using Java and JDBC with InterSystems IRIS, see Using Java with InterSystems Software.

import com.intersystems.jdbc*;
import java.sql.Connection;
public class JDBCConnection{
  public static void main (String[] args) throws Exception {
      String dbUrl = 
        "jdbc:IRIS://host-identifier:superserver-port/namespace"; 
      String user = "username";
      String pass = "password";

      IRISDataSource ds = new IRISDataSource();
      ds.setURL(dbUrl);
      ds.setUser(user);
      ds.setPassword(pass);
      Connection dbconnection = ds.getConnection();
      System.out.println("Connected to InterSystems IRIS via JDBC.");
      }
}
Connecting with TLS

To extend the instructions above to connect with TLS encryption using a self-signed X.509 certificate provided by the InterSystems IRIS target, do the following:

  1. Obtain or download the self-signed certificate as instructed and place it in a secure location.

  2. On the operating system command line, issue the following command, supplying a keystore password and confirming Trust this certificate? [no]: yes as requested:

    keytool -importcert -file path-to-cert/cert-file.pem 
      -keystore keystore.jks
  3. In the directory containing the Java file in which you are coding the connection, create a configuration file named SSLConfig.properties and including these properties:

    trustStore=path-to-keystore/keystore.jks
    trustStorePassword=keystore-password
  4. In the code provided above, modify the connection string definition by adding true in the final optional field, which specifies the use of TLS, as follows:

    String dbUrl = 
      "jdbc:IRIS://host-identifier:superserver-port/namespace/:::true";

For detailed information about connecting with TLS from Java applications, see Configuring Java Clients to Use TLS with InterSystems IRIS.

Connect from .NET using ADO.NET

Before using these instructions, you should make sure that:

  • Your development system has the .NET framework and Visual Studio (or another .NET IDE of your choice) installed, and has network access to your InterSystems IRIS target.

  • You have downloaded the InterSystems ADO.NET client assembly, InterSystems.Data.IRISClient.dll, to your development system.

    If InterSystems IRIS is installed locally or in a container on your development system, you can also find the file in install-dir\dev\dotnet\bin\net5.0 (or install-dir/dev/dotnet/bin/net5.0 on UNIX®/Linux), where install-dir is the InterSystems IRIS installation directory (install-dir in a container is /usr/irissys).

  • You have gathered the connection information for the InterSystems IRIS target you want to connect to.

To code an ADO.NET connection to InterSystems IRIS, follow these steps:

  1. Add the InterSystems ADO.Net client assembly, InterSystems.Data.IRISClient.dll, as a dependency and declare it in the application, then create a namespace with an internal class that has a main method.

    InterSystems ADO.Net client assembly shown as dependency in Solution Explorer

  2. Use the connection information for the InterSystems IRIS target to define the connection string:

    Connection string code

  3. Finally, pass the connection string as an argument to the IRISADOConnection method and create the connection:

    All of the needed code, including the connection

You can copy the code used here from the listing below. For more information about using .NET and ADO.NET with InterSystems IRIS, see Using .NET with InterSystems Software.

using System;
using InterSystems.Data.IRISClient;
 
namespace ADODemo
{
   internal class Program
   {
      static void Main(string[] args)
      {
         string connectionString = "Server = host-identifier; " +
           "Port = superserver - port; Namespace = namespace;" +
           "User ID = username; Password = password";
         IRISADOConnection connection = new IRISADOConnection(connectionString);
         connection.Open();
         // when finished, use the line below to close the connection
         // connection.Close();
      }
   }
}
Connecting with TLS

To extend the instructions above to connect with TLS encryption using a self-signed X.509 certificate provided by the InterSystems IRIS target, do the following:

  1. Obtain or download the certificate as instructed and place it in a secure location.

  2. Install the certificate using the instructions for your platform, below. (Both Windows and UNIX/Linux systems provide several ways to install certificates.)

    • On Windows, open a Command Prompt window and enter the following command to add the certificate to the Trusted Root Certification Authorities\ store under Current User:

      certutil -user -addstore Root path-to-certificate\certificate-file.pem 
    • On the UNIX or Linux command line, follow these steps:

      1. Enter the following command to install the Dotnet Certificate Tool, dotnet-certificate-tool (see https://github.com/gsoft-inc/dotnet-certificate-tool):

        dotnet tool install --global dotnet-certificate-tool
      2. Use the tool to add the certificate to the Root store under CurrentUser (besure to include --store-name Root as shown):

        certificate-tool add --cert path-to-certificate\certificate-file.pem 
          --store-name Root
        Note:

        If the certificate is not in PEM format, use the appropriate flag in place of --cert; if the certificate is password-protected, include the --password flag. For more information, see the README file on GitHub.

  3. In the code provided above, modify the connection string definition by adding SSL = true to specify the use of TLS, as follows:

    string connectionString = "Server = host-identifier; 
      Port = superserver-port; Namespace = namespace; 
      User ID = username; Password = password; SSL = true"; 

For more detailed information about connecting with TLS from .NET applications, see Configuring .NET Clients to Use TLS with InterSystems IRIS.

Connect from C++ using ODBC

Before using these instructions, you should make sure that:

  • Your development system has Visual Studio (or another C++ development environment of your choice) installed, and has network access to your InterSystems IRIS target.

  • You have downloaded the platform-specific InterSystems ODBC driver to your development system. (If InterSystems IRIS is installed locally on your development system, the driver is already installed and you do not need to download it.)

  • You have gathered the connection information for the InterSystems IRIS target you want to connect to.

To code an ODBC cconnection to InterSystems IRIS, follow these steps:

  1. If InterSystems IRIS is not installed locally, install the InterSystems ODBC driver as follows:

    • On Windows, simply execute the downloaded installer.

    • On Linux or MacOS, create the directory in which you want to install the driver, for example /usr/irisodbc, and unpack the downloaded .tar file in that directory, then execute the ODBCinstall script.

  2. Import the required libraries and create a main method:

    Beginning of code including libraries and start of main method

  3. Initialize variables, and allocate the environment and connection handles:

    Code initializing variables and allocating environment and connection handles

  4. Define the connection string, which is a series of key value pairs specifying the connection information for the InterSystems IRIS target (note that the Database key is used to specify the InterSystems IRIS namespace) and call the method that creates the connection, SQLDriverConnect, passing in arguments such as the handle variables and connection string.

    All of the needed code, including the connection string and the connection

You can copy the code used here from the listing below. For more information about using C++ and ODBC with InterSystems IRIS, see Using the InterSystems ODBC Driver.

#ifdef WIN32
#include <windows.h>
#endif
#include <sqlext.h>
#ifdef UNICODE
#include <sqlucode.h>
#endif
#include <stdio.h>
 
int main()
{
     RETCODE rc;                        /* Return code for ODBC functions */
     HENV henv = NULL;                 /* Environment handle */
     HDBC hdbc = NULL;                /* Connection handle */
     unsigned char szOutConn[600];
     SQLSMALLINT *cbOutConn = 0;
     
     SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
     SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
     SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
     
     SQLTCHAR connect_cmd[255] = "Driver=InterSystems IRIS 
       ODBC35;Host=host-identifier;Port=superserver-port;
       Database=namespace;UID=username;PWD=password;\0";
     rc = SQLDriverConnect(hdbc, NULL, (SQLCHAR*) connect_cmd, SQL_NTS, 
       szOutConn, 600, cbOutConn, SQL_DRIVER_COMPLETE);
 
     if (rc == SQL_SUCCESS)
     {
                 printf("Successfully connected!!\n");
     }
     else
     {
                 printf("Failed to connect to IRIS\n");
                 exit(1);
     }          
 
     SQLDisconnect(hdbc);
     SQLFreeHandle(SQL_HANDLE_DBC, hdbc);    /* Free connection handle */
     SQLFreeHandle(SQL_HANDLE_ENV, henv);    /* Free environment handle */
     
     return 0;
}
Connecting with TLS

To extend the instructions above to connect with TLS encryption using a self-signed X.509 certificate provided by the InterSystems IRIS target, do the following:

  1. Obtain or download the certificate as instructed and place it in a secure location.

  2. Choose a location and name for a connection and configuration definitions file and set the environment variable ISC_SSLconfigurations to the full path (including filename) of this file. The default name and location is C:\Program Files\Common Files\InterSystems\IRIS\SSLDefs.ini on Windows, however you can place the file where you like as long as you set the environment variable. On UNIX/Linux, you must set the environment variable so the driver can locate the file.

  3. Create the definitions file with the following contents:

    [ConnectionName]
    Address=host-identifier
    Port=superserver-port
    SSLConfig=TLSConfigName
    
    [TLSConfigName]
    VerifyPeer=0
    CertFile=path-to-certificate\certificate-file.pem
    TLSMinVersion=minimum-supported-tls-version
    TLSMaxVersion=maximum-supported-tls-version

    The connection definition includes the host identifier and superserver port for the InterSystems IRIS target that appear in the connection string variable connect_cmd in the code above, as well as the name of the TLS configuration definition. In the TLS configuration definition, VerifyPeer=0 indicates that in order to establish an encrypted connection, the client will not require a certificate from the server to verify its identity, but only present its own for the server to verify. Certfile is the self-signed certificate provided by the InterSystems IRIS target, to be presented to the target’s superserver when the client connects. For information about the correct values for TLSMinVersion and TLSMaxVersion, see Which TLS Versions Does My Instance of InterSystems IRIS Support? For more detailed information about the definitions file and its contents, see Connecting from a Windows Client Using a Settings File.

    Important:

    Generally speaking, the best practice when using TLS encryption is to require peer verification, so that both server and client must verify the certificate of the other party before establishing an encrypted connection. However, in the limited case presented here, only the client’s certificate is verified.

  4. Create a DSN entry defining the InterSystems IRIS target as an ODBC data source. This entry contains the connection information for the target, corresponding to the fields of the connection string in the code — host identifier (Host), superserver port (Port), namespace (Database), username (UID), and password (PWD) . The steps to follow depend on your platform:

    • On Windows:

      1. Open the ODBC Data Source Administrator from the Control Panel by selecting Administrative Tools and then ODBC Data Sources (32 bit or 64 bit, depending on your system).

      2. On the User DSN or System DSN tab, select Add, then on the Create New Data Source panel select InterSystems IRIS ODBC35.

      3. Create a name and description for the source, enter the connection information in the appropriate locations, set Authentication Method to Password with SSL/TLS, and enter the name of the TLS configuration in the definitions file you created in the previous step as SSL/TLS Server Name.

        InterSystems ODBC Data Source Setup dialog

      4. Optionally test the connection information using the Test Connection button, then click OK.

    • On Linux:

      1. Using the file extract-directory/dev/odbc/redist/ssl/irisodbc.ini.template as a template and the connection information, create an ODBC initialization file (typically called odbc.ini) in a location available to the connection code with values as described for the Windows DSN above, as shown here:

        [ODBC Data Sources] 
        IRIS-TLS = IRIS-TLS 
        
        [IRIS-TLS] 
        Driver = /home/guest/iris/bin/libirisodbc35.so 
        Description = demo TLS connection
        Host = host-identifier 
        Port = superserver-port 
        Namespace = namespace 
        UID = username 
        Password = password 
        Protocol = TCP 
        Query Timeout = 1 
        Static Cursors = 0 
        Trace = off 
        TraceFile = logfile.log 
        Service Principal Name = iris/target-domain-name 
        Authentication Method = 2 
        Security Level = 10 
        SSL Server Name = tls-config-in-definitions-file
        Note:

        You can find the template file in the same location under the installation directory of an installed instance, which is /usr/irissys in a container.

      2. Set the environment variable ODBCINI to the full path (including filename) of the ODBC initialization file.

    • On UNIX, follow the instructions in Defining an ODBC Data Source on UNIX.

  5. In the code provided above, modify the connection string definition to replace the connection information fields with the DSN you defined, as shown (using the name IRIS-TLS, as in the examples):

         SQLTCHAR connect_cmd[255] = _T("DSN=IRIS-TLS;\0"); 
         rc = SQLDriverConnect(hdbc, NULL, (SQLCHAR*) connect_cmd, SQL_NTS,
           szOutConn, 600, cbOutConn, SQL_DRIVER_COMPLETE); 

For more detailed information about connecting with TLS using ODBC, see Connecting from a Windows Client Using a Settings File.

Feedback