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>
is5
to install as a Windows service, or4
to run it as an executable.<domain-prefix>
is the prefix of the LUSID domain to connect to, for exampleacmecorp
to connect toacmecorp.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
- 32-bit build:
- Executable:
- 32-bit build:
C:\Windows\Temp\FinbourneLuminesce\ODBC32Logs
- 64-bit build:
C:\Windows\Temp\FinbourneLuminesce\ODBC64Logs
- 32-bit build:
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
- Launch the MSI in your preferred way, for example at the command line:msiexec /i Finbourne.Honeycomb.ODBCClientWin64.<version>.msiThe MSI is currently unsigned, but it's safe to override any warnings:
- 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:
- Search for the ODBC Data Sources (64-bit) app from the Windows Start menu:
- 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):
- 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 (replacing14264
) 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:
- Select Database > Driver Manager > New to create a new driver.
- On the Libraries tab, click the Add File button and navigate to the location of the
FinbourneLuminesceJDBCClient42_<version>.jar
file. - Click the Find Class button to populate the Driver class:
- On the Settings tab, enter a Driver Name and create the driver:
- Select Database > New Database Connection and locate the driver:
- 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.
- 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: