Python support for IBM Db2 for LUW and IBM Db2 for z/OS

Python, DB-API components for IBM Db2 for LUW and IBM Db2 for z/OS

Provides Python interface for connecting to IBM Db2 for LUW and IBM Db2 for z/OS

Components

The ibm_db contains:
- ibm_db driver: Python driver for IBM Db2 for LUW and IBM Db2 for z/OS databases. Uses the IBM Data Server Driver for ODBC and CLI APIs to connect to IBM Db2 for LUW.
- ibm_db_dbi: Python driver for IBM Db2 for LUW that complies to the DB-API 2.0 specification.

<a name="api"></a> API Documentation

For more information on the APIs supported by ibm_db, please refer to below link:

https://github.com/ibmdb/python-ibmdb/wiki/APIs

Pre-requisites

Install Python 3.9 <= 3.14. The minimum python version supported by driver is python 3.9 and the latest version supported is python 3.14. MacOS arm64 is supported Python 3.9 onwards.

To install ibm_db on z/OS system

Please follow detailed installation instructions as documented here: ibm_db Installation on z/OS

SQL1598N Error - It is expected in absence of valid db2connect license. Please click here and read instructions.
SQL0805N Error - You need to rebind CLI packages to fix this error. Please read detailed instructions here.

For MacOS M1/M2/ Apple Silicon chip system

MacOS with Silicon Chip - Supported from v3.2.5 onwards using v12.x clidriver. MacOS with Intel Chip - Supported using v11.x clidriver only. By default v11.5.9 clidriver will get downloaded.

Linux/Unix:

If you face problems due to missing python header files while installing the driver, you would need to install python developer package and retry install. e.g:

    zypper install python-devel
     or
    yum install python-devel

If you have installed DB2_RTC* i.e. DB2 Runtime Client and want ibm_db to use it instead of clidriver, please read this comment and take action.

clidriver v12.1 on Linux uses x86_64_v2 instruction set which is not supported by cibuildwheel and wheel image creation fails using v12.1 clidriver. So, default version of clidriver on Linux platform is v11.5.9 only.
You can force installation of ibm_db on Linux with clidriver v12.1 using below commands:

export CLIDRIVER_VERSION=v12.1.0
pip install ibm_db --no-binary :all: --no-cache-dir

Windows:

If a db2 client or server or dsdriver or clidriver is already installed in the system and user has already set installed path to PATH environment variable, then user needs to set environment variable IBM_DB_HOME manually to the installed path before installing ibm_db.
To verify it, just execute db2level command before installation of ibm_db. If it works, note down the install directory path and set system level environment variable IBM_DB_HOME as install path shown in output of db2level command.
If user has installed clidriver in F:\DSDRIVER and if the "PATH" environment variable has F:\DSDRIVER\bin, then user should also set IBM_DB_HOME to F:\DSDRIVER.

Docker Linux containers:

You may need to install gcc, python, pip, python-devel, libxml2 and pam if not already installed. Refer to Installation for more details.

Manual Installation

To install ibm_db from source code after clone from git, or to know the detialed installation steps for various platforms, please check INSTALL document.

Installation

Python Wheels are built for Linux, MacOS and Windows operating systems for multiple python versions (from python version 3.7 to 3.13). For other platforms, package gets installed from source distribution. For MaxOS arm64, python wheels are available from version 3.9 onwards.

You can install the driver using pip as:

pip install ibm_db

This will install ibm_db and ibm_db_dbi module.

When we install ibm_db package on Linux, MacOS and Windows, pip install ibm_db command install prebuilt Wheel package that includes clidriver too and ignores IBM_DB_HOME or IBM_DB_INSTALLER_URL or CLIDRIVER_VERSION environment variables if set. Also, auto downloading of clidriver does not happen as clidriver is already present inside wheel package.
For platforms not supported by python-wheel, ibm_db will get installed from souce distribution. GCC compiler is required on non-windows platform and VC++ compiler on Windows platform to install ibm_db from souce distribution.
If db2cli validate command works in your system and installed db2 client/server has include directory, ibm_db installation from souce distribution will not download clidriver, but it will use the existing client/server from the system.
To inforce auto downloading of clidriver OR to make setting of environment variable IBM_DB_HOME or IBM_DB_INSTALLER_URL or CLIDRIVER_VERSION effective; install ibm_db from source distribution using below command:

pip install ibm_db --no-binary :all: --no-cache-dir

If you want to use your own URL for clidriver.tar.gz/.zip please set below environment variable:

export IBM_DB_INSTALLER_URL=full_path_of_clidriver.tar.gz/.zip
pip install ibm_db --no-binary :all: --no-cache-dir

To install using specific version of clidriver from https://public.dhe.ibm.com/ibmdl/export/pub/software/data/db2/drivers/odbc_cli/:

export CLIDRIVER_VERSION=v11.5.9
pip install ibm_db --no-binary :all: --no-cache-dir

ibm_db will override value of CLIDRIVER_VERSION to v12.1.0 for MacARM64 and to v11.5.9 for Macx64 platform.
When ibm_db get installed from wheel package, you can find clidriver under site_packages directory of Python. You need to copy license file under site_packages/clidriver/license to be effective, if any.

Note: For windows after installing ibm_db, recieves the below error when we try to import ibm_db :

Python 3.11.4 (tags/v3.11.4:d2340ef, Jun  7 2023, 05:45:37) [MSC v.1934 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import ibm_db
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: DLL load failed while importing ibm_db: The specified module could not be found.
>>>

We need to make sure to set dll path of dependent library of clidriver before importing the module as:

import os
os.add_dll_directory('path to clidriver installation until bin')
import ibm_db

e.g:
os.add_dll_directory('C:\\Program Files\\IBM\\CLIDRIVER\\bin')
import ibm_db

Refer https://bugs.python.org/issue36085 for more details.

<a name="docker"></a>For installing ibm_db on docker Linux container, you can refer as below:

yum install python gcc pam wget python-devel.x86_64 libxml2
use, `yum install python3` to install python 3.x

if pip or pip3 does not exist, install it as:
wget https://bootstrap.pypa.io/get-pip.py
docker cp get-pip.py /root:<containerid>
cd root
python3 get-pip.py

Install python ibm_db as:
pip install ibm_db
or
pip3 install ibm_db

Uninstalling the ibm_db driver :

pip uninstall ibm_db

The ODBC and CLI Driver(clidriver) is automatically downloaded at the time of installation and it is recommended to use this driver. However, if you wish to use an existing installation of clidriver or install the clidriver manually and use it, you can set IBM_DB_HOME environment variable as documented below:

<a name="envvar"></a>Environment Variables: IBM_DB_HOME :

Set this environment variable to avoid automatic downloading of the clidriver during installation. You could set this to the installation path of ODBC and CLI driver in your environment.<br> e.g:
```
Windows :
set IBM_DB_HOME=C:/Users/userid/clidriver

Other platforms:
export IBM_DB_HOME=/home/userid/clidriver
```
Note: You must need to install ibm_db using command pip install ibm_db --no-binary :all: --no-cache-dir on Linux, Windows and MacOS to make setting of IBM_DB_HOME effective. If you want to use Runtime Client or clidriver downloaded from fix central which do not have include file, please read this comment.

You are required to set the library path to the clidriver under IBM_DB_HOME to pick this version of the ODBC and CLI Driver.<br> e.g:
```
Windows:
set LIB=%IBM_DB_HOME%/lib;%LIB%

AIX:
export LIBPATH=$IBM_DB_HOME/lib:$LIBPATH

MAC:
export DYLD_LIBRARY_PATH=$IBM_DB_HOME/lib:$DYLD_LIBRARY_PATH

Other platforms:
export LD_LIBRARY_PATH=$IBM_DB_HOME/lib:$LD_LIBRARY_PATH
```
The ODBC and CLI driver is available for download at Db2 LUW ODBC and CLI Driver. Refer to (License requirements) for more details on the CLI driver for manual download and installation.
Installing using Anaconda distribution of python

conda install -c conda-forge ibm_db

Supported Platform for Anaconda Installation

Platform	Architecture	Supported	Version
Linux	amd64 (x86_64)	Yes	Latest
Linux	ppc64le	Yes	Latest
Darwin	Mac OS x64	Yes	Latest
Darwin	Mac OS arm64	Yes	Latest
Windows	x64	Yes	Latest
Windows	x32	Yes	Latest

<a name="quick example"></a> Quick Example

$ python
Python 3.13.0 (main, Oct  7 2024, 05:02:14) [Clang 16.0.0 (clang-1600.0.26.4)] on darwin
Type "help", "copyright", "credits" or "l

ibm-db

Description