You can install the Luminesce DBC server driver on a Windows computer—and Luminesce ODBC/JDBC client drivers on Windows, Mac, UNIX 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 easier to install either the Power BI Connector or, for other ODBC-aware BI apps, our standalone ODBC driver locally.
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 (Windows, UNIX, Linux, Mac OS X, AIX and Solaris) and/or SimbaClient for JDBC (any operating system able to run a Java Virtual Machine 1.8+).
Note: The instructions on this page do not enable SSL and are therefore recommended for PoC or testing environments only. We highly recommend enabling SSL to protect communications between the server and client computers in a production environment. More information.
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:
msiexec /i Finbourne.Luminesce.ODBCWin64.<version>.msi SERVER=<service-or-exe> [DOMAIN=<domain-prefix> CLIENTAPPLICATION="<client-id>" CLIENTSECRET="<client-secret>"]
where:
<service-or-exe>is5to install as a Windows service, or4to run it as an executable.<domain-prefix>is the prefix of the LUSID domain to connect to, for exampleacmecorpto connect toacmecorp.lusid.com. This is required unless you intend to run the DBC server driver across multiple LUSID domains and connect using bearer token authentication.<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. This is required unless you intend to connect to the DBC server driver using bearer token authentication.
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. |
LOGPATH | Specifies an accessible directory to write logs to. |
Note if you choose SERVER=5 to install as a Windows service you should configure the Startup Type (or start manually):
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.Luminesce.ODBCClientWin64.<version>.msi
The 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):
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 Client 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>.jarfile to a suitable location. - Mac or Linux computer, request the Luminesce JDBC client driver
FinbourneLuminesceJDBCClient42_<version>.jarfile and simply copy it to a suitable location.
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>.jarfile. - On the Settings tab, enter a suitable Driver Name and the Class Name, which is
com.finbourneluminesce.client.core.jdbc42.SCJDBC42Driver, and then click OK to 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>
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.
- 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: