Developers

Omnis Technical Note TNSQ0040Updated May 2026

Installing PostgreSQL Client Libraries

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

Windows
macOS
Linux
Troubleshooting

Introduction

Historically, Omnis Studio ships with its dynamic client library; libpq.dll/libpq.so alongside the Omnis exectable. On macOS, the libpq.dylib resides in the Omnis.app/Contents/Frameworks folder, and this is digitally signed as part of Omnis Studio's code signature. This technote discusses how you can replace or provide your own the client library, plus any required dependencies should you need to.

Installing PostgreSQL Client on Windows

The easiest way to obtain Windows client libraries is by copying them from an exisitng PostgreSQL installation or from an archive/ binary distribution of PostgreSQL. The following table summarises the files required for different versions of the client.

PostgreSQL 15.4 and later	libpq.dll libssl-3-x64.dll libcrypto-3-x64.dll libintl-9.dll libwinpthread-1.dll libiconv-2.dll *
PostgreSQL 13.0 and later	libpq.dll libssl-1_1-x64.dll libcrypto-1_1-x64.dll libintl-9.dll libwinpthread-1.dll libiconv-2.dll *
PostgreSQL 12.6 and lower	libpq.dll ssleay32.dll libeay32.dll libintl-8.dll libiconv-2.dll *

On Windows, these files are normally found inside the bin folder of the server / downloaded archive.
* This file is supplied with Omnis Studio. Studio 12 also includes libssl-3-x64.dll and libcrypto-3-x64.dll

Installing PostgreSQL Client on macOS

Recent versions of the macOS PostgreSQL client library have several dependencies on other files supplied as part of the client installation. The easiest way to provide the latest client files on macOS is using Homebrew:

% arch -arm64 brew install libpq

% cd /Applications/Omnis\ Studio\ 12\ xxxxx.app/Contents/Frameworks

% ln -s /opt/homebrew/Cellar/libpq/18.4/lib/libpq.5.dylib libpq.dylib

• The ln command assumes that Homebrew will install libpq to the location indicated. Use brew list libpq to show the exact location of libpq.x.dylib
• The cd command should change directory into the installed Omnis Studio package. xxxxxx should be replaced with the installed Studio revision number, or replace the path as appropriate.
• Making changes to the Omnis Studio package may invalidate the code-signature, and you may need to re-sign the Omnis Studio.app

Installing PostgreSQL Client on Linux

The following table summarises the required client files and dependencies for different versions of the PostgreSQL client.

PostgreSQL 15.4 and later	libpq.so→libpq.x.so libssl.so→libssl.3.so libcrypto.so→libcrypto.3.so libldap-2.5.so.0
PostgreSQL 13.0 and later	libpq.so→libpq.x.so libssl.so→libssl.1.1.so libcrypto.so→libcrypto.1.1.so
PostgreSQL 12.6 and lower	libpq.so→libpq.x.so libssl.so→libssl.1.1.so libcrypto.so→libcrypto.1.1.so

On Linux, these files are normally found inside the lib folder of the server / downloaded archive.
Most Linux distributions now include libssl and libcrypto but it is not detrimental to provide your own copies of these files.
Note that libpq.so is normally a symlink that points to the dot-versioned target library.

Troubleshooting

In the event that the PostgreSQL DAM does not logon, check the Omnis Tracelog for any errors.

"Client or interface function not available": This error is reported by the session object if a client API call is not available. It normally indicates that the libpq library could not be found, or (more likely) one or more dependencies could not be found. The Omnis tracelog may give an indication of which file(s) are missing. Provide the missing file and repeat if necessary. In rare cases, check that the supplied file(s) are of the correct 64-bit architecture (and are arm64/Universal binaries for macOS).

On macOS, Omnis Studio "crashes" on startup after replacing the client library. This indicates that Omnis Studio tried to startup with an invalid code signature. (Modiying the contents of the Omnis Studio.app can invalidate the code signature). Refer to technote TNMA0001 for more details.

Links & 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 TNSQ0031: Making SSL Connections using the PostgreSQL DAM.
• Technote TNSQ0043- Locating External Client LIbraries
• PostgreSQL website: https://www.postgresql.org