10. Verifying the Installation of Database Client Libraries

For all of the databases that HammerDB supports it is necessary to have a third-party client library installed that HammerDB can use to connect and interact with the database. Note that if you use the official HammerDB Docker images this step has already been done for you and all of the third-party client libraries have been pre-installed. This client library will also typically be installed with database server software. HammerDB does not statically link the 3rd party libraries to minimise executable size and provide flexibility in the third-party libraries used. For example if a bug is detected in a particular library then this can be upgraded without requiring the HammerDB libraries to be rebuilt. However as the client libraries are dynamically linked it is essential that the correct client libraries are already installed and environment variables set to ensure that HammerDB can find the correct libraries. Note that it is only necessary to load the libraries for the database that your are testing.

The HammerDB command line tool can be used to check the status of library availability for all databases.

To run this utility run the following command

./hammerdbcli

and type librarycheck, with the following example on Linux

ubuntu@ubuntu22:/opt/HammerDB-5.0$ ./hammerdbcli 
HammerDB CLI v5.0
Copyright © HammerDB Ltd hosted by tpc.org 2019-2025
Type "help" for a list of commands
Initialized Jobs on-disk database /tmp/hammer.DB using existing tables (69,632 bytes)
hammerdb>librarycheck
Checking database library for Oracle
Success ... loaded library Oratcl for Oracle
Checking database library for MSSQLServer
Success ... loaded library tdbc::odbc for MSSQLServer
Checking database library for Db2
Success ... loaded library db2tcl for Db2
Checking database library for MySQL
Success ... loaded library mysqltcl for MySQL
Checking database library for PostgreSQL
Success ... loaded library Pgtcl for PostgreSQL
Checking database library for MariaDB
Success ... loaded library mariatcl for MariaDB

hammerdb>

and the following example on Windows

C:\Program Files\HammerDB-5.0>hammerdbcli
HammerDB CLI v5.0
Copyright © HammerDB Ltd hosted by tpc.org 2019-2025
Type "help" for a list of commands
Initialized Jobs on-disk database C:/Temp/hammer.DB using existing tables (2,048,000 bytes)
hammerdb>librarycheck
Checking database library for Oracle
Success ... loaded library Oratcl for Oracle
Checking database library for MSSQLServer
Success ... loaded library tdbc::odbc for MSSQLServer
Checking database library for Db2
Success ... loaded library db2tcl for Db2
Checking database library for MySQL
Success ... loaded library mysqltcl for MySQL
Checking database library for PostgreSQL
Success ... loaded library Pgtcl for PostgreSQL
Checking database library for MariaDB
Success ... loaded library mariatcl for MariaDB

In the examples it can be seen that all required libraries are loaded. If the libraries do not load successfully, they will report the name of the library that is required but cannot be found.

Checking database library for Db2
Error: failed to load db2tcl - couldn't load file "/tmp/tcl_POJlXA": libdb2.so.1: cannot open shared object file: No such file or directory
Ensure that Db2 client libraries are installed and the location in the LD_LIBRARY_PATH environment variable
Checking database library for MySQL
Error: failed to load mysqltcl - couldn't load file "/tmp/tcl_EN8Ifg": libmysqlclient.so.24: cannot open shared object file: No such file or directory
Ensure that MySQL client libraries are installed and the location in the LD_LIBRARY_PATH environment variable

On Windows library locations are set in the Environment Variables under the PATH option.

Figure 1.21. Environment Variables

Environment Variables

.The following examples shows the settings for the IBM Db2, PostgreSQL and MySQL libraries.

Figure 1.22. Path environment variable

Path environment variable

On Linux the library locations are set in LD_LIBRARY_PATH environment variable the .profile file in the home directory.

# The following three lines have been added by IBM DB2 instance utilities.
if [ -f /home/ubuntu/sqllib/db2profile ]; then
    . /home/ubuntu/sqllib/db2profile
fi

export LD_LIBRARY_PATH=/opt/mariadb-11.4.4/lib:/opt/postgresql-17.2/lib:/opt/mysql-8.4.4-linux-glibc2.28-x86_64/lib:$LD_LIBRARY_PATH

The following table shows the libraries that are required for each database version and the versions that HammerDB v5.0 have been built against. All libraries are 64-bit. Note that some databases are considerably more flexible than others in library versions and therefore the following section is important to ensure that you install the correct library for your needs. If you need to change a required client library than you may do so by building from source against a client library of your choosing.

Table 1.3. 3rd party libraries

Database / OSDatabase versionLibrary
Oracle LinuxVersion independent buildlibclntsh.so
Oracle WindowsVersion independent buildOCI.DLL
SQL Server LinuxVersion independent buildlibodbc.so
SQL Server WindowsVersion independent buildODBC32.DLL
Db2 Linux12.1libdb2.so
Db2 Windows12.1DB2CLI64.DLL
MySQL Linux8.4.4libmysqlclient.so (libmysqlclient.so.24)
MySQL Windows8.4.4LIBMYSQL.DLL
MariaDB Linux11.4.4libmariadb.so (libmariadb.so.3)
MariaDB Windows11.4.4LIBMARIADB.DLL
PostgreSQL Linux17.2libpq.so (libpq.so.5)
PostgreSQL Windows17.2LIBPQ.DLL

10.1. Oracle Client

When using the Oracle instant client Oratcl uses the additional environment variable ORACLE_LIBRARY to identify the Oracle client library. On the Windows the Oracle client library is called oci.dll in a location such as: C:\Oracle\WINDOWS.X64_213000_db_home\bin. On Linux the library is called libclntsh.so where this is typically a symbolic link to a product specific name such as libclntsh.so.21.1 for Oracle 21c. A freely downloadable Oracle client from Oralce is called the Oracle Instant Client, for example:

instantclient-basic-linux.x64-21.17.0.0.0dbru.zip

Extract, this into a chosen directory, the following example, extracts the instant client into a newly created lib directory under the HammerDB directory. Note HammerDB will look for the libraries under a lib directory under the ORACLE_HOME as per a full Oracle Database install, therefore rename the extracted instant client directory to lib.

mv instantclient_21_17/ lib

It will contain libclntsh links and a library file such as follows:

ubuntu@ubuntu22:/opt/HammerDB-5.0/lib$ ls -l libclntsh.so*
lrwxrwxrwx 1 ubuntu ubuntu       17 Apr  9 16:10 libclntsh.so -> libclntsh.so.21.1
lrwxrwxrwx 1 ubuntu ubuntu       17 Apr  9 16:10 libclntsh.so.10.1 -> libclntsh.so.21.1
lrwxrwxrwx 1 ubuntu ubuntu       17 Apr  9 16:10 libclntsh.so.11.1 -> libclntsh.so.21.1
lrwxrwxrwx 1 ubuntu ubuntu       17 Apr  9 16:10 libclntsh.so.12.1 -> libclntsh.so.21.1
lrwxrwxrwx 1 ubuntu ubuntu       17 Apr  9 16:10 libclntsh.so.18.1 -> libclntsh.so.21.1
lrwxrwxrwx 1 ubuntu ubuntu       17 Apr  9 16:10 libclntsh.so.19.1 -> libclntsh.so.21.1
lrwxrwxrwx 1 ubuntu ubuntu       17 Apr  9 16:10 libclntsh.so.20.1 -> libclntsh.so.21.1
-rwxr-xr-x 1 ubuntu ubuntu 84281056 Dec 23 14:16 libclntsh.so.21.1

In your .profile file set the LD_LIBRARY_PATH, ORACLE_HOME and ORACLE_LIB to this location.

export LD_LIBRARY_PATH=/opt/HammerDB-5.0/lib
export ORACLE_HOME=/opt/HammerDB-5.0/lib
export ORACLE_LIBRARY=/opt/HammerDB-5.0/lib/libclntsh.so

10.2. SQL Server

On SQL Server on Windows the client libraries and necessary environment variables are set automatically during the SQL Server installation. Note that on 64-bit Windows the 64-bit ODBC client library is named ODBC32.DLL in the following location. C:\Windows\System32\odbc32.dll. On Linux follow the SQL Server on Linux installation guide to install 'mssql-tools' with the unixODBC developer package. On Linux refer to the release notes on compiling unixODBC with the fastvalidate option.

10.3. Db2

For DB2 on Linux the client library libdb2.so.1 is required either in the lib64 directory for 32. Similarly on Windows the db2cli64.dll is required. These libraries are included with a standard DB2 installation or also with a standalone DB2 client install.

10.4. MySQL

HammerDB version 5.0 has been built and tested against a MySQL 8.4 client installation. On Linux this means that HammerDB will require a MySQL client library called libmysqlclient.so.24. This client library needs to be referenced in the LD_LIBRARY_PATH as shown previously in this section. On Windows libmysqll.dll is required and should be referenced in the PATH environment variable.

10.5. MariaDB

HammerDB version 5.0 has been built and tested against MariaDB 11.4.4 client installation. On Linux this means that HammerDB will require a MariaDB client library called libmariadb.so.3. This client library needs to be referenced in the LD_LIBRARY_PATH as shown previously in this section. On Windows the client library is called libmariadb.dll and should be referenced in the PATH environment variable.

10.6. PostgreSQL

For PostgreSQL the client library is called libpq.dll on Windows and libpq.so on Linux however note that additional libraries are also required. For Windows this means setting your PATH environment variable such as the following: D:\PostgreSQL\pgsql\bin; On Linux it is required to set the LD_LIBRARY_PATH environment variable in the same way described for Oracle previously in this section to the location of the PostgreSQL lib directory. Alternatively for installations of EnterpriseDB the client directory also contains the necessary files for a HammerDB installation.