Developers

Omnis Technical Note TNSQ0039Updated July 2021

Using the Dynamic MySQL DAM

for Omnis Studio 10.2 or above
by Gary Ashford, Omnis Engineering

Introduction
The "dynamic" MySQL DAM allows selection of the MySQL client library in a given deployment and this makes it possible to update the client library without the need for a replacement DAM. Using the latest release of the client library ensures support for the latest MySQL features including enhanced encryption and SSL support. The client library and its dependencies can be obtained from a standard MySQL client or server distribution and applied to the system.

Note: For Studio 11.2, see also: TNSQ0043

Show discussion for: Studio 10.2 build 30997 and later Studio 10.2 pre build 30997

Downloading the Clientware
The required client libraries can be extracted from any standard distribution of MySQL Database Server, including the MySQL Community Server, available from the MySQL Developer Site.

The following table shows the name of the client library required on each supported platform, together with the required dependencies. These must all be extracted and placed in a location where Omnis will find them when it starts up.

	Windows	macOS	Linux
Client Library	libmysql.dll	libmysqlclient.dylib→ libmysqlclient.xx.dylib	libmysqlclient.so→ libmysqlclient.xx.so
MySQL 8.0.35 and later	libssl-3-x64.dll libcrypto-3-x64.dll	libssl.dylib→libssl.3.dylib libcrypto.dylib→libcrypto.3.dylib	libssl.so→libssl.3.so libcrypto.so→libcrypto.3.so
MySQL 8.0.18 and lower	ssleay32.dll libeay32.dll	libssl.dylib→libssl.1.1.dylib libcrypto.dylib→libcrypto.1.1.dylib	libssl.so→libssl.1.1.so libcrypto.so→libcrypto.1.1.so
Notes	On Windows, these files are normally found inside the bin folder of the server / downloaded archive.	On macOS, these files are normally found inside the lib of the server / downloaded archive.	On Linux, these files are normally found inside the lib of the server / downloaded archive.

Assuming a .zip or .tar archive is downloaded, the client library (and its symbolic link file) can normally be found inside the "lib" folder. The dependencies can be found either in the "lib" folder or inside the "bin" folder.

*The Windows client currently requires the Microsoft Visual C++ Redistributable for Visual Studio 2015 to be installed. This provides the additional library dependency: vcruntime140_1.dll (Newer clients may require a later version of the C++ redistributable).

Installation
We recommend placing the client library and its dependencies in the following locations:

	Windows	macOS	Linux
Install Location	"Omnis" folder (in the same folder as omnis.exe)	"Omnis.app/Contents/Frameworks" folder libssl and libcrypto dylibs are installed to Omnis.app/Contents/lib	/usr/local/lib

On macOS, libmysqlclient.x.dylib looks for libssl.dylib and libcrypto.dylib in the @loader_path/../lib folder by default. libssl.1.1.dylib, libcrypto.1.1.dylib plus their symlinks should therefore be placed in a folder named Omnis.app/Contents/lib, creating this folder as necessary.

On Linux, the client libraries can also be placed inside the Omnis folder because the omnisX64 script appends to the LD_LIBRARY_PATH environment variable.

Testing the DAM
After starting Studio, check the Trace Log in case there is an error loading the MySQL DAM. When loaded, the MYSQLDAM should appear in the $extobjects section, viewed using the Notation Inspector.

Failure to load the MYSQLDAM indicates that either the client library or one of its dependencies could not be located, or may be of the wrong architecture. Please refer to technote TNEX0009 for help in diagnosing & resolving dynamic library dependencies.

References

• Please note that libssl and libcrypto are part of the OpenSSL project which is released under the dual OpenSSL and SSLeay licence, available here.
• Technote TNSQ0030: Making SSL Connections using the MySQL DAM.
• Technote TNGI0030: Notarizing your Omnis application for macOS.