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>
@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