Skip to content

Instantly share code, notes, and snippets.

@sliekens

sliekens/ibm-data-db2.md

Last active April 23, 2025 20:43
Show Gist options
  • Save sliekens/dacbd8cdef93d20bf7fcfc2bdafbce43 to your computer and use it in GitHub Desktop.
Save sliekens/dacbd8cdef93d20bf7fcfc2bdafbce43 to your computer and use it in GitHub Desktop.
Download ZIP
IBM DB .NET Core Provider
Raw
ibm-data-db2.md

IBM Db2 data provider for .NET Core / .NET 5+

/edit I made this page in Feb 2020 because there was no documentation publicly available, and I wanted to share what little information I could find. I'm not associated with IBM.

More official documentation can be found here: https://community.ibm.com/community/user/datamanagement/blogs/vishwa-hs1/2020/07/12/db2-net-packages-download-and-configure

⚠️ NOTE TO IBM ⚠️ (You can skip this section unless you work for IBM)

If you work for IBM, please make the following changes to these packages:

Publish a single package for all platforms: it's bad that you publish lnx and osx variants instead of including them in the main package. It's perfectly possible to do so with architecture-specific folders.

(I was told the lnx and osx variants exist because of NuGet package size limitations. My question is then: why the f--- are your packages that big? It's a f------ client library. I've seen SERVERS that fit within the package size limitations. Get your f------ sh-- together. You are IBM for f--- sake, not some small indie company.)

You should create a single package with native code in runtimes/{rid}/native/ folders.

Examples:

  • runtimes/win-x64/native/clidriver/
  • runtimes/linux-x64/native/clidriver/
  • runtimes/osx-x64/native/clidriver/

You can do the same trick for managed .NET assemblies, but the folder name is lib instead of native. You must also create and include a platform-agnostic reference assembly for development.

Examples:

  • runtimes/win-x64/lib/net8.0/IBM.Data.Db2.dll
  • runtimes/linux-x64/lib/net8.0/IBM.Data.Db2.dll
  • runtimes/osx-x64/lib/net8.0/IBM.Data.Db2.dll
  • ref/net8.0/IBM.Data.Db2.dll compilation symbols, only referenced at compile-time, this must be compiled for AnyCPU

Resources:

Thank you

NuGet Packages

.NET Core 3.1

.NET 5: they renamed the packages

.NET 6+: they renamed the packages again, maybe this was the last rename. 🤞

Installation

You'll probably want to be smart about which package you reference in your csproj file.

.NET 9

<PropertyGroup>
    <ProcessorArchitecture>amd64</ProcessorArchitecture>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Net.IBM.Data.Db2-lnx" Version="9.0.0.100" Condition="$([MSBuild]::IsOsPlatform('Linux'))" />
  <PackageReference Include="Net.IBM.Data.Db2-osx" Version="9.0.0.100" Condition="$([MSBuild]::IsOsPlatform('OSX'))" />
  <PackageReference Include="Net.IBM.Data.Db2" Version="9.0.0.100" Condition="$([MSBuild]::IsOsPlatform('Windows'))" />
</ItemGroup>

.NET 8

<PropertyGroup>
    <ProcessorArchitecture>amd64</ProcessorArchitecture>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Net.IBM.Data.Db2-lnx" Version="8.0.0.300" Condition="$([MSBuild]::IsOsPlatform('Linux'))" />
  <PackageReference Include="Net.IBM.Data.Db2-osx" Version="8.0.0.300" Condition="$([MSBuild]::IsOsPlatform('OSX'))" />
  <PackageReference Include="Net.IBM.Data.Db2" Version="8.0.0.300" Condition="$([MSBuild]::IsOsPlatform('Windows'))" />
</ItemGroup>

.NET 7

<PropertyGroup>
    <ProcessorArchitecture>amd64</ProcessorArchitecture>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Net.IBM.Data.Db2-lnx" Version="7.0.0.400" Condition="$([MSBuild]::IsOsPlatform('Linux'))" />
  <PackageReference Include="Net.IBM.Data.Db2-osx" Version="7.0.0.400" Condition="$([MSBuild]::IsOsPlatform('OSX'))" />
  <PackageReference Include="Net.IBM.Data.Db2" Version="7.0.0.400" Condition="$([MSBuild]::IsOsPlatform('Windows'))" />
</ItemGroup>

.NET 6

<PropertyGroup>
    <ProcessorArchitecture>amd64</ProcessorArchitecture>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Net.IBM.Data.Db2-lnx" Version="6.0.0.500" Condition="$([MSBuild]::IsOsPlatform('Linux'))" />
  <PackageReference Include="Net.IBM.Data.Db2-osx" Version="6.0.0.500" Condition="$([MSBuild]::IsOsPlatform('OSX'))" />
  <PackageReference Include="Net.IBM.Data.Db2" Version="6.0.0.500" Condition="$([MSBuild]::IsOsPlatform('Windows'))" />
</ItemGroup>

.NET 5

<PropertyGroup>
    <ProcessorArchitecture>amd64</ProcessorArchitecture>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Net5.IBM.Data.DB2-lnx" Version="5.0.0.500" Condition="$([MSBuild]::IsOsPlatform('Linux'))" />
  <PackageReference Include="Net5.IBM.Data.DB2-osx" Version="5.0.0.500" Condition="$([MSBuild]::IsOsPlatform('OSX'))" />
  <PackageReference Include="Net5.IBM.Data.DB2" Version="5.0.0.500" Condition="$([MSBuild]::IsOsPlatform('Windows'))" />
</ItemGroup>

.NET Core 3.1

<PropertyGroup>
    <ProcessorArchitecture>amd64</ProcessorArchitecture>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="IBM.Data.DB2.Core-lnx" Version="3.1.0.500" Condition="$([MSBuild]::IsOsPlatform('Linux'))" />
  <PackageReference Include="IBM.Data.DB2.Core-osx" Version="3.1.0.500" Condition="$([MSBuild]::IsOsPlatform('OSX'))" />
  <PackageReference Include="IBM.Data.DB2.Core" Version="3.1.0.500" Condition="$([MSBuild]::IsOsPlatform('Windows'))" />
</ItemGroup>

You could just install the one package you need, but don't forget to sign up for the "Works on My Machine" certification program.

Build

Building the project creates an extra folder clidriver in your output directory:

bin/
+-- $(Configuration)/           typically Debug or Release
    +-- $(TargetFramework)/     e.g. netcoreapp3.1
        +-- clidriver/
            +-- adm/            Linux/Mac only
            +-- bin/
            +-- bnd/
            +-- cfg/
            +-- cfgcache/       Linux/Mac only
            +-- conv/
            +-- db2dump/        Linux only
            +-- lib/
            +-- license/
            +-- msg/

License

If you have a license, copy it to clidriver/license/ before deploying your application.

Configuration

Windows

Set DB2_CLI_DRIVER_INSTALL_PATH to your clidriver path

Add clidriver/bin to PATH

DB2_CLI_DRIVER_INSTALL_PATH=X:\app\clidriver
PATH=%PATH%;X:\app\clidriver\bin

Linux

Set DB2_CLI_DRIVER_INSTALL_PATH to your clidriver path

Add clidriver/lib (and maybeclidriver/lib/icc) to LD_LIBRARY_PATH.

Add clidriver/bin to PATH

DB2_CLI_DRIVER_INSTALL_PATH=/app/clidriver
LD_LIBRARY_PATH=/app/clidriver/lib:/app/clidriver/lib/icc
PATH=$PATH:/app/clidriver/bin

MacOS

Set DB2_CLI_DRIVER_INSTALL_PATH to your clidriver path

Add clidriver/lib and clidriver/lib/icc to DYLD_LIBRARY_PATH

Add clidriver/bin to PATH

DB2_CLI_DRIVER_INSTALL_PATH=/app/clidriver
DYLD_LIBRARY_PATH=/app/clidriver/lib:/app/clidriver/lib/icc
PATH=$PATH:/app/clidriver/bin

Troubleshooting

Error: Unable to load shared library 'libdb2.so' or one of its dependencies. In order to help diagnose loading problems, consider setting the LD_DEBUG environment variable: liblibdb2.so: cannot open shared object file: No such file or directory

Possible fix: install libxml2.so

apt-get install libxml2

Error: Unable to load DLL 'db2app64.dll' or one of its dependencies: The specified module could not be found. (0x8007007E)

Make sure the clidriver directory is placed in the directory of your program.

warning MSB3270: There was a mismatch between the processor architecture of the project being built "MSIL" and the processor architecture of the reference "/home/vscode/.nuget/packages/net.ibm.data.db2-lnx/6.0.0.300/lib/net6.0/IBM.Data.Db2.dll", "AMD64". This mismatch may cause runtime failures. Please consider changing the targeted processor architecture of your project through the Configuration Manager so as to align the processor architectures between your project and references, or take a dependency on references with a processor architecture that matches the targeted processor architecture of your project.

IBM only supports compiling for 64-bit, you need to compile for 64-bit only. In your csproj:

<PropertyGroup>
  <ProcessorArchitecture>amd64</ProcessorArchitecture>
</PropertyGroup>
@elmarkos23
Copy link

For me it worked manually copying the clidriver folder and only using the linux xq nuget my deployment was in docker linux

@sliekens
Copy link
Author

Update: apt-get install libxml2-dev can be replaced by apt-get install libxml2 without dev headers, they are not needed to run applications.

@sjahongir
Copy link

Issue: Unable to load db2app64.dll with DB2 provider in .NET 6 application on Docker

Description

I'm trying to connect to Informix using the DB2 provider in a .NET 6 application running on Docker. However, I'm encountering the following error when connecting:

Exception: Unable to load shared library 'db2app64.dll' or one of its dependencies. In order to help diagnose loading problems, consider setting the LD_DEBUG environment variable: libdb2app64.dll: cannot open shared object file: No such file or directory

Environment

  • .NET Version: 6.0
  • Docker Base Image: mcr.microsoft.com/dotnet/runtime:6.0
  • DB2 Package: Net.IBM.Data.Db2-lnx (version 6.0.0.500)

Dockerfile

FROM mcr.microsoft.com/dotnet/runtime:6.0 AS build-env

# Install necessary packages and dependencies
RUN apt-get -y update && apt-get install -y libxml2

ENV DB2_CLI_DRIVER_INSTALL_PATH=/app/clidriver
ENV LD_LIBRARY_PATH=$DB2_CLI_DRIVER_INSTALL_PATH/lib
ENV LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$DB2_CLI_DRIVER_INSTALL_PATH/lib/icc
ENV PATH=$PATH:$DB2_CLI_DRIVER_INSTALL_PATH/bin:$DB2_CLI_DRIVER_INSTALL_PATH/lib

# Copy your application code
COPY ./ app/
WORKDIR /app

# Run your .NET application
CMD ["sh", "-c", "dotnet TestInformixWithDb2.dll && tail -f /dev/null"]

Project File (csproj)

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net6.0</TargetFramework>
        <ImplicitUsings>enable</ImplicitUsings>
        <Nullable>enable</Nullable>
        <ProcessorArchitecture>amd64</ProcessorArchitecture>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Net.IBM.Data.Db2-lnx" Version="6.0.0.500" />
    </ItemGroup>

    <ItemGroup>
        <None Update="Dockerfile">
            <CopyToOutputDirectory>Always</CopyToOutputDirectory>
        </None>
    </ItemGroup>
</Project>

@sliekens
Copy link
Author

@sjahongir I suspect that the problem is your CMD: sh -c {command} starts a new shell with a new environment, it won't inherit the ENV that you set above it.

CMD ["sh", "-c", "dotnet TestInformixWithDb2.dll && tail -f /dev/null"]

In this scenario, you also need to set the environment variables in the {command} portion:

CMD ["sh", "-c", "export DB2_CLI_DRIVER_INSTALL_PATH=$DB2_CLI_DRIVER_INSTALL_PATH && export LD_LIBRARY_PATH=$LD_LIBRARY_PATH && export PATH=$PATH && dotnet TestInformixWithDb2.dll && tail -f /dev/null"]

But I'm wondering what's the use for tail -f /dev/null, do you really need it? You can make this a lot simpler without it by using ENTRYPOINT:

ENTRYPOINT ["dotnet", "TestInformixWithDb2.dll"]

Good luck 👍

@sjahongir
Copy link

sjahongir commented Nov 24, 2024 •
edited
Loading

Thanks @sliekens for your answer.
I am able to connect to Informix using the Db2 provider.

I have another question:
Currently, the connection is being made via the DRDA port.
I would like to ask if it is possible to connect to Informix using the SQLI (oncotcp) port instead, with the Db2 provider?

@sliekens
Copy link
Author

@sjahongir I think you will need to use the Informix provider instead. See:

I don't think the Informix provider is on NuGet so you will need to install CSDK and copy the DLL from the install dir. I really can't believe IBM is still in business, who keeps giving them money? And why?

@sjahongir
Copy link

@sliekens
I have already used the Informix provider, but there are performance issues as reading and writing are very slow with this package.
In addition, the former Informix-specific provider (IBM.Data.Informix) is now deprecated.

According to IBM documentation:

Important: The Informix .NET provider (IBM.Data.Informix.dll) is deprecated and might be discontinued in a later release. Start using the Db2 .NET provider (IBM.Data.Db2.dll) to connect to Informix database servers.

@sliekens
Copy link
Author

sliekens commented Nov 25, 2024 •
edited
Loading

@sjahongir IBM.Data.Informix.dll is for .NET Framework, search for Informix.Net.Core.dll

A lot of the IBM documentation is for .NET Framework, with some .NET core sprinkled in between. Some of it gated behind paywalls, especially the binary downloads. It's the reason why I created this gist. Absolutely terrible. IBM is the most developer-hostile company I ever worked with.

@sjahongir
Copy link

@sliekens I used this package for .NET Core:
<PackageReference Include="Informix.Net.Core" Version="4.700.7.2021" />

@sliekens
Copy link
Author

sliekens commented Nov 27, 2024 •
edited
Loading

@sjahongir I would be careful with that, that's not published by IBM. Probably somebody took the DLL and redistributed it on nuget, which is very likely against the IBM license terms, and you can't count on IBM support when it goes wrong. You should find a way to download the CSDK and get the official DLL. https://www.ibm.com/support/pages/download-informix-products

@ArveSystad
Copy link

ArveSystad commented Feb 18, 2025 •
edited
Loading

After a bunch of digging and harsh struggle:

If you're running in a Linux based container, and you get this error:

Exception was thrown by handler. DB2Exception: ERROR [58004] [IBM] SQL1042C An unexpected system error occurred. SQLSTATE=58004

...inspect your container and verify the LD_LIBRARY_PATH environment variable, and make sure the value does not start with :, coming from the attempt of prepending existing values like shown above. Specifically, our var looked like :/app/clidriver/lib:/app/clidriver/lib/icc, which causes it to fail. Note the : in the start.

If it's empty from before, don't attempt prepending it, like shown for a dockerfile style setup below:

ENV LD_LIBRARY_PATH="/app/clidriver/lib:/app/clidriver/lib/icc"

@mtafasahin
Copy link

Thank you so much for the detailed information! It really saved us a lot of time. The proper use of NuGet for the correct OS and setting the LD_LIBRARY_PATH worked perfectly. I truly appreciate your help!

@onurbos
Copy link

onurbos commented Feb 27, 2025

I appreciate to you about it. I got this error on .net 8 same you. I solved it via your documentation.

@sliekens
Copy link
Author

@ArveSystad good point, I didn't know it would crash when the path starts with :, I now removed the dangerous code from the gist

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment