The configuration of applications to use Heimdall can vary wildly, however in this document, we will attempt to explain common application configurations, and provide generic information sufficient so that any application can be Heimdall enabled.
Overall Process (JDBC)
In the most general terms, to enable a JDBC application to use Heimdall is:
- copy the “heimdalldriver.jar” file into your application’s class path. This is part of the overall software install on the management server;
- copy any/all grid-cache libraries from the libs/ directory in your Heimdall install. If your application is already using the desired grid-cache libraries (such as Lettuce for Redis, or the Hazelcast libraries), in general this step can be skipped, OR please be careful about the versions of libraries being copied. For initial testing, if the cache is set to “local only” then no additional libraries are necessary.
- Copy the JDBC URL from the Virtual Database tab into the application configuration, replacing the <Heimdall ServerIP:Port> field with the appropriate hostname and port (default 8087) for the Heimdall GUI;
- Append “?hduser=<username>&hdpassword=<password>” to the JDBC URL where the user is allowed access to the GUI, and the password is the user’s password. This can be configured on the Access Control tab, and the user can be marked as a read-only user if desired to limit access;
- Copy the appropriate JDBC class fields into the application configuration;
- Restart the application.
Once restarted, Heimdall will generate log messages to the applications stdout, and will prepend “Heimdall:” to each log message. Please see Heimdall Logging for more information on logging. Please note–when a VDB is configured in proxy mode, it is ALSO able to be used in JDBC mode, but the opposite is not true–in JDBC mode, the proxy will not be allowed for security reasons.
Overall Process (Proxy):
When a Virtual Database (VDB) is configured in proxy mode, then it is expected that one or more proxy instances will be configured, and that the application will connect to the configured port using the credentials provided (set in the Proxy settings). Anonymous authentication can also be set, but if used, it is suggested that only localhost proxy support be enabled. In proxy mode, the application in general only needs to have the following configured (in black). This example is from the Bitnami AWS image for Magento 1.9, in /opt/bitnami/apps/magento/htdocs/app/etc/config.xml:
<initStatements>SET NAMES utf8</initStatements>
Another example, from the Bitnami AWS image for WordPress (/opt/bitnami/apps/wordpress/htdocs/wp-config.php):
// do not use the name “localhost” as this will trigger unix socket use, which does not work in proxy mode
IMPORTANT: As noted in this example, with many drivers, using the word “localhost” for MySQL and PostgreSQL will trigger local socket usage, which will not work, even if the proxy is operating on the same node. Instead, use “127.0.0.1” or create another alias in the /etc/hosts file (or equivalent) to point to 127.0.0.1.
The Database name will match the Heimdall Virtual Database name, and in order to prevent some odd database mapping issues, should in general also match the name of the database instance the application itself uses on the database server. This is as a result of some applications using the configured database name as part of queries generated against the database. If these two do not match, such queries will fail. This seems to be most important with MySQL applications.
The username used to connect to the proxy should match the username configured in the Data Source configuration as well. Like the database name, this is as a result of some queries containing the username, and will fail of they do not match.
With MySQL, if foreign characters are being used, the database needs to be configured as the server character set of UTF8MB4, not just “UTF8”. This is due to the JDBC drivers being used, which negotiate the wireline character set based on the server’s configured character set. If the server is configured as UTF8, even if a table is configured as UTF8MB4, this will cause some corruption of characters that require larger numbers of bytes, such as some Chinese and other characters.
Many applications that support SQL Server (Jira, Confluence, Jive, etc) ship with the JTDS JDBC driver. This is supported in JDBC mode, but as the latest non-experimental version (1.3.1) uses an old version of the TDS protocol (version 7.1, as shipped with SQL Server 2000), it is not supported in SQL Proxy mode. Please note, the JTDS driver is no longer developed (https://sourceforge.net/p/jtds/discussion/129584/thread/050f9892/), and Microsoft now provides their JDBC driver under the MIT license: https://github.com/Microsoft/mssql-jdbc.