Skip to content

Instantly share code, notes, and snippets.

@sliekens

sliekens/ibm-data-db2.md

Last active January 10, 2026 11:55
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save sliekens/dacbd8cdef93d20bf7fcfc2bdafbce43 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
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.

Local Development

The following uses IsOsPlatform() to detect the OS at build time. This works well when you're building and running on the same machine.

.NET 9

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

.NET 8

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

Build Server / Cross-Compilation

When building on a different OS than your target (e.g., building on Windows for Linux deployment, or using a CI/CD pipeline), use RuntimeIdentifier (RID) conditions instead:

.NET 6+ (using RuntimeIdentifier)

<PropertyGroup>
    <!-- Can be overridden with: dotnet publish -r win-x64 -->
    <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
    <ProcessorArchitecture>amd64</ProcessorArchitecture>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Net.IBM.Data.Db2-lnx" Version="9.0.0.400" Condition="$(RuntimeIdentifier.StartsWith('linux'))" />
  <PackageReference Include="Net.IBM.Data.Db2-osx" Version="9.0.0.400" Condition="$(RuntimeIdentifier.StartsWith('osx'))" />
  <PackageReference Include="Net.IBM.Data.Db2" Version="9.0.0.400" Condition="$(RuntimeIdentifier.StartsWith('win'))" />
</ItemGroup>

Then publish with the target RID:

# Build on Windows, deploy to Linux
dotnet publish -r linux-x64

# Build on Windows, deploy to macOS
dotnet publish -r osx-x64

# Build on Linux, deploy to Windows
dotnet publish -r win-x64

⚠️ Important: The RuntimeIdentifier condition only works when you explicitly set the RID (via -r flag or <RuntimeIdentifier> property). For a hybrid approach that works both locally and on build servers:

<PropertyGroup>
    <ProcessorArchitecture>amd64</ProcessorArchitecture>
</PropertyGroup>
<ItemGroup>
  <!-- Cross-compilation: use RuntimeIdentifier when specified -->
  <PackageReference Include="Net.IBM.Data.Db2-lnx" Version="9.0.0.400"
    Condition="$(RuntimeIdentifier.StartsWith('linux'))" />
  <PackageReference Include="Net.IBM.Data.Db2-osx" Version="9.0.0.400"
    Condition="$(RuntimeIdentifier.StartsWith('osx'))" />
  <PackageReference Include="Net.IBM.Data.Db2" Version="9.0.0.400"
    Condition="$(RuntimeIdentifier.StartsWith('win'))" />

  <!-- Local development: fallback to build OS when no RID specified -->
  <PackageReference Include="Net.IBM.Data.Db2-lnx" Version="9.0.0.400"
    Condition="'$(RuntimeIdentifier)' == '' AND $([MSBuild]::IsOsPlatform('Linux'))" />
  <PackageReference Include="Net.IBM.Data.Db2-osx" Version="9.0.0.400"
    Condition="'$(RuntimeIdentifier)' == '' AND $([MSBuild]::IsOsPlatform('OSX'))" />
  <PackageReference Include="Net.IBM.Data.Db2" Version="9.0.0.400"
    Condition="'$(RuntimeIdentifier)' == '' AND $([MSBuild]::IsOsPlatform('Windows'))" />
</ItemGroup>

NuGet Package Lock Files

If your project uses NuGet lock files (packages.lock.json) with locked mode enabled, you'll run into problems with cross-platform teams.

The problem: When you enable RestorePackagesWithLockFile and RestoreLockedMode, NuGet expects the lock file to match exactly. But since the IBM Db2 packages use conditional PackageReference elements based on the OS, each platform generates a different lock file. A developer on Windows will have Net.IBM.Data.Db2 in their lock file, while a developer on Linux will have Net.IBM.Data.Db2-lnx.

This also causes CI/CD failures: if your developers are on Windows but your build server runs Linux, the lock file committed from Windows won't match what the Linux build server expects, causing restore to fail with "lock file validation failed".

Solution: Generate multiple lock files — Create separate lock files for each platform by embedding the RuntimeIdentifier in the lock file name:

<PropertyGroup>
  <NuGetLockFilePath Condition="'$(RuntimeIdentifier)' != ''">packages.$(RuntimeIdentifier).lock.json</NuGetLockFilePath>
</PropertyGroup>

To generate or update all three lock files at once:

dotnet restore -r linux-x64 --force-evaluate
dotnet restore -r osx-x64 --force-evaluate
dotnet restore -r win-x64 --force-evaluate

This creates packages.linux-x64.lock.json, packages.osx-x64.lock.json, and packages.win-x64.lock.json.

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.

For Docker/Linux/Mac, it might be necessary to adjust file permissions of the license file (confirmation is needed). At least one other person had problems where copying the license to the correct folder wasn't enough.

(I don't have a license, so I can't write more about this topic.)

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 Possible Cause Fix
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 Missing libxml2 dependency on Linux Install libxml2.so: 
apt-get install libxml2
Unable to load DLL 'db2app64.dll' or one of its dependencies: The specified module could not be found. (0x8007007E) The clidriver folder is not in the application directory or PATH 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 "...IBM.Data.Db2.dll", "AMD64". This mismatch may cause runtime failures. Project is configured for AnyCPU instead of 64-bit IBM only supports 64-bit. Add to your csproj: 
<PropertyGroup>
  <ProcessorArchitecture>amd64</ProcessorArchitecture>
</PropertyGroup>
@sliekens
Copy link
Author

sliekens commented Jan 10, 2026

I added some new notes about cross-platform teams, builds, CI/CD scenarios, and package lockfiles.

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