Skip to main content

Connecting Your Application to InterSystems IRIS

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

  1. Download the InterSystems driver packageOpens in a new tab 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 serviceOpens in a new tab, 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 InformationOpens in a new tab.

    If you want to deploy an instance of InterSystems IRIS for the purpose of making and testing a programmatic connection, see Deploying InterSystems IRISOpens in a new tab; options include a free Community EditionOpens in a new tab 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.

You may also be interested in Connecting to InterSystems Cloud ServicesOpens in a new tab, a set of two-minute videos that present connection instructions for each language. For more detailed online learning content about the use of some of these languages with InterSystems products, see Connecting to InterSystems Products with External LanguagesOpens in a new tab. For information about all of the connections tools available from InterSystems, see Connection ToolsOpens in a new tab.

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 encryptionOpens in a new tab 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 TLSOpens in a new tab.)

Connect from Python using DB-API

Before using these instructions, you should make sure that:

  • Your development system has the Python IDEOpens in a new tab of your choice installed and has network access to your InterSystems IRIS target.

  • You have downloadedOpens in a new tab the InterSystems DB-API driver, intersystems_irispython-version-py3-none-any.whl, 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\python, where install-dir is the InterSystems IRIS installation directory (install-dir in a container is /usr/irissys).

  • You have gathered the connection informationOpens in a new tab 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 SupportOpens in a new tab.


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_CLIENT)
        context.verify_mode=ssl.CERT_REQUIRED
        context.check_hostname = False
        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()
    
Note:

Before using this minimal TLS configuration in production, please consult TLS/SSL wrapper for socket objectsOpens in a new tab in the Python documentation.

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 IDEOpens in a new tab of your choice installed and has network access to your InterSystems IRIS target.

  • You have downloadedOpens in a new tab 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 informationOpens in a new tab 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.

    The InterSystems JDBC driver in the Classpath Variables window of the IDE

  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 SoftwareOpens in a new tab.


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 IRISDataSource definition by adding ds.setConnectionSecurityLevel(10);, which specifies the use of TLS, to the other settings as follows:

    
          IRISDataSource ds = new IRISDataSource();
          ds.setURL(dbUrl);
          ds.setUser(user);
          ds.setPassword(pass);
          ds.setConnectionSecurityLevel(10);
    
    

For detailed information about connecting with TLS from Java applications, see Configuring Java Clients to Use TLS with InterSystems IRISOpens in a new tab.

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 IDEOpens in a new tab of your choice) installed, and has network access to your InterSystems IRIS target.

  • You have downloadedOpens in a new tab 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 informationOpens in a new tab 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 SoftwareOpens in a new tab.

Note:

Other references to this code in the InterSystems documentation may use the IRISConnection method instead of the IRISADOConnection; the former is simply an alias to the latter, identical in practice.


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-toolOpens in a new tab):

        
        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 IRISOpens in a new tab.

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 downloadedOpens in a new tab 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 informationOpens in a new tab for the InterSystems IRIS target you want to connect to.

Note:

The ODBC driver is also used to connect C applications to InterSystems IRIS.

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, execute the downloaded installer, ODBC-version-win_x64.exe.

    • On Linux or MacOS:

      1. Create the directory in which you want to install the driver, for example /usr/irisodbc.

      2. Unpack the downloaded .tar file, ODBC-version-platform.tar.gz, in that directory.

      3. 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 DriverOpens in a new tab.


#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=1
    VerifyHost=0
    CAfile=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=1 and VerifyHost=0 indicate that in order to establish an encrypted connection, the client will verify the server’s certificate — that is, the self-signed certificate provided by the InterSystems IRIS target, specified in CAfile — but will not verify that the Common Name or subjectAlternativeName fields of the certificate match the host name or IP address as specified in the connection definition. For information about the correct values for TLSMinVersion and TLSMaxVersion, see Which TLS Versions Does My Instance of InterSystems IRIS Support?Opens in a new tab For more detailed information about the definitions file and its contents, see Connecting from a Windows Client Using a Settings FileOpens in a new tab.

    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, 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

        Important:

        The Password with SSL/TLS setting for Authentication Method is not required when using a definitions file, such as ssldefs.ini, as described in this procedure; it is included for legacy purposes only. If the definitions file is properly configured, the connection should use SSL/TLS automatically with Password as the authentication mechanism. If there are problems with the definitions file, the connection attempt may proceed without using SSL/TLS; if the server allows unencrypted connections, the connection may succeed.

      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 UNIXOpens in a new tab.

  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 FileOpens in a new tab.

FeedbackOpens in a new tab