Installing the Windows DBC server driver and ODBC/JDBC client drivers to connect BI apps to Luminesce

You can install the Luminesce DBC server driver on a Windows computer—and Luminesce ODBC/JDBC client drivers on Windows, Mac or Linux client computers—to allow end users to query Luminesce providers directly from familiar BI apps such as DBeaver or Excel running on those client computers. Find out more about native BI integration.

Note: In a Windows-only environment, it might be simpler to install either our Power BI Connector or, for other ODBC-aware BI apps, our standalone ODBC driver locally. For general or background information on connecting ODBC and JDBC applications to remote data stores in networked environments, read the Simba documentation.

To do this, you require:

• For the server computer:
  • The Luminesce DBC server driver MSI. Contact us for delivery options, or alternatively for information about a Docker image containing a pre-installed DBC server.
  • Administrative privileges on a Windows computer with .NET Framework 4.7.2+ installed. The Luminesce DBC server driver is available for 32-bit and 64-bit versions of Windows, but not for any other platforms.
• For client computers:
  • The Luminesce ODBC client driver MSI and/or the Luminesce JDBC client driver MSI or JAR (the JDBC MSI simply copies the JAR file to a particular location).
  • Administrative privileges on client computers that support SimbaClient for ODBC and/or SimbaClient for JDBC (see the Specifications tab half way down this Simba page for supported platforms).

Installing the Luminesce DBC server driver on Windows

You must use the SERVER argument with the msiexec command to choose whether to install the driver as a Windows service or run it as an executable. The basic syntax is as follows:

where:

• <service-or-exe> is 5 to install as a Windows service, or 4 to run it as an executable.
• <domain-prefix> is the prefix of the LUSID domain to connect to, for example acmecorp to connect to acmecorp.lusid.com.
• <client-id> and <client-secret> are the credentials of a valid LUSID application. See how to generate a client ID and secret. Note the client secret is stored in plain text in the Registry.

The following msiexec command line arguments are optional:

Command line argument	Explanation
ADDLOCAL=Driver32-bit	Installs just the 32-bit variant.
ADDLOCAL=Driver64-bit	Installs just the 64-bit variant. If you omit ADDLOCAL arguments, or specify both, the 32-bit and 64-bit drivers are installed. However, note if you choose SERVER=5 to install as a Windows service then the 32-bit variant is ignored, since only one variant can be registered as a service.
SERVER32LISTENPORT=<port>	Specifies a port for the 32-bit variant to listen for connections from client computers on. If you omit this argument, the port is 14232.
SERVER32LISTENADDRESS=<ipv4-or-ipv6>	Specifies an address for the 32-bit variant to listen for connections from client computers on. If you omit this argument, the server driver listens for connections on ::1 and therefore expects the client driver to be installed on the same computer.
SERVER64LISTENPORT=<port>	Specifies a port for the 64-bit variant to listen for connections from client computers on. If you omit this argument, the port is 14264.
SERVER64LISTENADDRESS=<ipv4-or-ipv6>	Specifies an address for the 64-bit variant to listen for connections from client computers on. If you omit this argument, the server driver listens for connections on ::1 and therefore expects the client driver to be installed on the same computer.

Note if you choose SERVER=5 to install as a Windows service you should configure the Startup Type (or start manually):

Setting up SSL

The Luminesce DBC server requires SSL for client/server communications. You should generate a suitable server certificate and key file pair and make them available as follows:

• C:\Program Files\Finbourne\Luminesce ODBC\Certificates\SimbaSSL\dbc_server_cert.pem
• C:\Program Files\Finbourne\Luminesce ODBC\Certificates\SimbaSSL\dbc_server_key.pem

Note if you change this location and/or file names you will need to configure the client driver.

Accessing logs

By default, logs are written to:

• Windows service:
  • 32-bit build: C:\Windows\Temp\FinbourneLuminesce\Server32Logs
  • 64-bit build: C:\Windows\Temp\FinbourneLuminesce\Server64Logs
• Executable:
  • 32-bit build: C:\Windows\Temp\FinbourneLuminesce\ODBC32Logs
  • 64-bit build: C:\Windows\Temp\FinbourneLuminesce\ODBC64Logs

You can adjust the base directory (C:\Windows\Temp\FinbourneLuminesce) using the LOGPATH argument when running the MSI.

Installing the Luminesce ODBC client driver on Windows

1. Launch the MSI in your preferred way, for example at the command line:
   msiexec /i Finbourne.Honeycomb.ODBCClientWin64.<version>.msi
   The MSI is currently unsigned, but it's safe to override any warnings:
   
2. On the Custom Setup screen, we recommend the default option of installing both 32-bit and 64-bit builds (even on a 64-bit system, since a typical Excel installation is 32-bit):
   

Setting up SSL

You should generate a suitable client certificate and make it available as follows: C:\Program Files\Finbourne\Luminesce ODBC Client\dbc_ca.pem

Note if you change this location and/or file name you will need to configure the client driver settings (below).

Configuring driver settings

If you installed the 64-bit build:

1. Search for the ODBC Data Sources (64-bit) app from the Windows Start menu:
   
2. In the ODBC Data Source Administrator (64-bit) dialog, open the System DSN tab and choose to Configure the 64-bit build (the 32-bit build is listed but must be configured using the equivalent ODBC Data Source Administrator (32-bit) dialog):
   
3. In the Luminesce ODBC Driver Configuration dialog, assuming the Luminesce DBC server driver is installed on a different computer, enter the IP address (replacing ::1) and port (replacing 14264) on which it is listening for connections:
   

If you installed the 32-bit build as well, repeat steps 1-3 for that variant.

Using a BI app to query a Luminesce provider

You can follow the generic instructions on this page for an example of using Excel to query the Lusid.Instrument provider supplied by FINBOURNE.

The steps are the same except you select Luminesce Remote (instead of Luminesce) in the From ODBC dialog:

Accessing logs

By default, logs are written to:

• 32-bit build: C:\Windows\Temp\FinbourneLuminesce\ODBCClient32Logs
• 64-bit build: C:\Windows\Temp\FinbourneLuminesce\ODBCClient64Logs

You can adjust the base directory (C:\Windows\Temp\FinbourneLuminesce) using the LOGPATH argument when running the MSI.

Installing the Luminesce JDBC client driver

If you have a:

• 64-bit Windows computer, request the Luminesce JDBC client driver MSI and run it in the standard way to copy the FinbourneLuminesceJDBCClient42_<version>.jar file to a suitable location.
• Mac or Linux computer, request the Luminesce JDBC client driver FinbourneLuminesceJDBCClient42_<version>.jar file and simply copy it to a suitable location.

Setting up SSL

You should generate a suitable client certificate and make it available in a suitable directory.

You will need to provide the full path when you configure the client driver (see below for an example).

Connecting from a JDBC-aware application

The following example showcases using DBeaver for Windows to query the Lusid.Instrument provider supplied by FINBOURNE.

The first time you use DBeaver, you need to set up the Luminesce JDBC client driver:

1. Select Database > Driver Manager > New to create a new driver.
2. On the Libraries tab, click the Add File button and navigate to the location of the FinbourneLuminesceJDBCClient42_<version>.jar file.
3. Click the Find Class button to populate the Driver class:
   
4. On the Settings tab, enter a Driver Name and create the driver:
   
5. Select Database > New Database Connection and locate the driver:
   
6. In the Connection Settings dialog, specify a suitable JDBC URL using the syntax:
    
   jdbc:simba://<dbc-server-ip>:<dbc-server-port>;UseSsl=Required;SSLCACertfile=<client-cert-path>
   
   where:
   • <dbc-server-ip> is the IP address the Luminesce DBC server is listening for connections on.
   • <dbc-server-port> is the port the Luminesce DBC server is listening for connections on.
   • <client-cert-path> is the path to the client certificate created for the client computer in the section above.
   The picture below shows an example JDBC URL connecting to a Luminesce DBC server that is installed on a computer in the same local network, is listening on the default port of 14264, and has a client certificate installed in the user's home directory:
   
7. Enter your LUSID domain Username; you are prompted for the password when you connect:
   

Uninstalling drivers

On Windows, you can uninstall any Luminesce driver using Add or remove programs in the standard way, for example: