Skip to content

Commit

Permalink
doc update to addess issues #907, #926
Browse files Browse the repository at this point in the history
  • Loading branch information
@bimalkjha
bimalkjha committed Apr 5, 2024
1 parent 5580d78 commit 3509504
Show file tree
Hide file tree
Showing 2 changed files with 126 additions and 62 deletions.
134 changes: 76 additions & 58 deletions INSTALL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,87 +21,105 @@ DEALINGS IN THE SOFTWARE.

## Contents

1. [ibm_db Installation on Linux](#inslnx)
2. [ibm_db Installation on AIX on Power Systems](#insaix_p)
3. [ibm_db Installation on Linux on System z](#inslnx_z)
4. [ibm_db Installation on Windows](#inswin)
5. [ibm_db Installation on MacOS](#insmac)
6. [ibm_db Installation on z/OS](#inszos)
7. [ibm_db installation on MacOS M1/M2 Chip System](#m1chip)
8. [Troubleshooting Post Install Errors](#troubleshooting)
1. [ibm_db Installation on Linux, AIX, zLinux, Widnows and MaxOS(x64) with Intel Chip.](#inslnx)
2. [ibm_db Installation on z/OS](#inszos)
3. [ibm_db installation on MacOS M1/M2 Chip System](#m1chip)
4. [Troubleshooting Post Install Errors](#troubleshooting)
- [SQL30081N Error](#sql30081n)
- [Symbol not found error or malloc error](#symbolerror)


## <a name="inslnx"></a> 1. Python-ibm_db Installation on Linux.
## <a name="inslnx"></a> 1. Python-ibm_db Installation on Linux, AIX, zLinux, Windows and MaxOS(x64) with Intel Chip.

### Install python-ibm_db

Below are the steps to install [*python-ibm_db*](https://github.com/ibmdb/python-ibm_db) from github or pip.

#### 1.1 Direct Installation.
#### 1.1 Direct Installation using pip.
To install ibm_db and ibm_db_dbi module.
```
pip install ibm_db
```
or
```
pip install git+https://[email protected]/ibmdb/python-ibm_db.git
```
* `pip install ibm_db` installs python wheel images on Linux, Windows and MacOS(x64) for python v>=3.7
* If wheel image is not available or for AIX and zLiux, native C++ code of ibm_db requires in-system compilation. For such case,
you should have a C++ compiler installed in the system. Make sure the commands `gcc --version` and `make --version` works
fine on Linux and MacOS system.
* For AIX and zLinux, you should have xLC Compiler intalled in the system. Also, `make` should be installed.
* For other pre-requisite and non-wheel installation, please check [here](https://github.com/ibmdb/python-ibmdb?tab=readme-ov-file#installation).

#### 1.2 Manual Installation by using git clone.
**Note:**
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`
environment variables if set. Also, auto downloading of clidriver does not happen as clidriver is
already present inside wheel package.

To inforce auto downloading of clidriver or to make setting of environment variable `IBM_DB_HOME`
effective, install ibm_db from source distribution using below command:
```
pip install ibm_db --no-binary :all: --no-cache-dir
```
git clone https://github.com/ibmdb/python-ibm_db/
cd python-ibmdb
python setup.py build
python setup.py install
````

## <a name="insaix_p"></a> 2. Python-ibm_db Installation on AIX on Power Systems.

### 2.1 Install python-ibm_db

Follow the same steps mentioned in [Python-ibm_db Installation on Linux](#inslnx).


## <a name="inslnx_z"></a> 3. Python-ibm_db Installation on Linux on System z.

### 3.1 Install python-ibm_db

Follow the same steps mentioned in [Python-ibm_db Installation on Linux](#inslnx).


## <a name="inswin"></a> 4. Python-ibm_db Installation on Windows.

Below are the steps to install [*python-ibm_db*](https://github.com/ibmdb/python-ibm_db) from github or pip.

#### 4.1 Direct Installation.
If you have to use your own URL for clidriver.tar.gz/.zip please set environment variable
```
pip install ibm_db
IBM_DB_INSTALLER_URL=full_path_of_clidriver.tar.gz/.zip
```
or
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
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.
>>>
```
pip install git+https://github.com/ibmdb/python-ibmdb.git
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.


#### 4.2 Manual Installation by using git clone.
#### 1.2 Manual Installation by using setup.py

```
git clone https://github.com/ibmdb/python-ibm_db/
cd python-ibmdb
python setup.py build
python setup.py install
````
pip list
```

## <a name="insmac"></a> 5. Python-ibm_db Installation on MacOS.
- `python setup.py install` command, installs python egg under site_packages.

### 5.1 Install python-ibm_db
#### 1.3 Manual Installation using python wheel (Only Linux, Windows and MacOS(x64))

Follow the same steps mentioned in [python-ibm_db Installation on Linux](#inslnx).
To install ibm_db as python wheel, use below commands(recommended):
```
git clone https://github.com/ibmdb/python-ibm_db/
cd python-ibmdb
python -m build => Note down the path of generated *.whl file to use below
pip install dist/ibm_db-3.2.3-cp311-cp311-win_amd64.whl
pip list => You can see ibm_db in the output
```

## <a name="inszos"></a> 6. ibm_db Installation on z/OS
## <a name="inszos"></a> 2. ibm_db Installation on z/OS

### 6.1 Install Python for z/OS
### 2.1 Install Python for z/OS

Below steps were followed for the same:

Expand All @@ -114,7 +132,7 @@ Below steps were followed for the same:
-- UI72589 (v12)
```

### 6.2 Configure ODBC driver on z/OS
### 2.2 Configure ODBC driver on z/OS
Please refer to the [ODBC Guide and References](https://www.ibm.com/support/knowledgecenter/SSEPEK/pdf/db2z_12_odbcbook.pdf) cookbook for how to configure your ODBC driver. Specifically, you need to ensure you have:

1. Binded the ODBC packages. A sample JCL is provided in the `SDSNSAMP` dataset in member `DSNTIJCL`. Customize the JCL with specifics to your system.
Expand Down Expand Up @@ -240,7 +258,7 @@ export DB2_MACS=$IBM_DB_HOME.XXXX

Reference Chapter 3 in the [ODBC Guide and References](https://www.ibm.com/support/knowledgecenter/SSEPEK/pdf/db2z_12_odbcbook.pdf) for more instructions.

### 6.3 Verify python installation
### 2.3 Verify python installation
1. Make sure when python is installed, you validate the same by typing &quot;python3 -V&quot; and it should return 3.8.3 or greater.
- Unless you are a sysprog you'll likely not have authority to create the site-package so consider using a python virtual environment as following:
```
Expand All @@ -257,17 +275,17 @@ import ibm_db
conn = ibm_db.connect('','','')
```
### 6.4 Installing Python driver for Db2 i.e. ibm\_db &amp; Running a validation Program
### 2.4 Installing Python driver for Db2 i.e. ibm\_db &amp; Running a validation Program
Now that the Python and ODBC is ready, for connecting to Db2 you need a Db2 Python driver which we are going to install.
Follow the standard steps for the same i.e. pip3 install ibm_db
### 6.5 Install python-ibm_db
### 2.5 Install python-ibm_db
Below are the steps to install [*python-ibm_db*](https://github.com/ibmdb/python-ibm_db) from github or pip.
#### 6.5.1 Direct Installation.
#### 2.5.1 Direct Installation.
```
pip install ibm_db
```
Expand All @@ -276,7 +294,7 @@ or
pip install git+https://[email protected]/ibmdb/python-ibm_db.git
```
#### 6.5.2 Manual Installation by using git clone.
#### 2.5.2 Manual Installation by using git clone.
```
git clone https://github.com/ibmdb/python-ibm_db/
Expand Down Expand Up @@ -307,9 +325,9 @@ else:
print('ODBC Test end')
```
## <a name="m1chip"></a> 7. ibm_db installation on MacOS M1/M2 Chip System (arm64 architecture)
## <a name="m1chip"></a> 3. ibm_db installation on MacOS M1/M2 Chip System (arm64 architecture)
### 7.1 Install GCC using Homebrew
### 3.1 Install GCC using Homebrew
**Warning:** If you use the ARM version of homebrew (as recommended for M1/M2 chip systems) you will get the following error message:
```
Expand Down Expand Up @@ -345,7 +363,7 @@ Suppose path of gcc lib is `/usr/local/homebrew/lib/gcc/12`. Then update your .b
export DYLD_LIBRARY_PATH=/usr/local/homebrew/lib/gcc/12:$DYLD_LIBRARY_PATH
```
### 7.2 Steps to Install Intel Python after verifying setup
### 3.2 Steps to Install Intel Python after verifying setup
Several things might be necessary to get `ibm_db` working on the Apple Silicon architecture:
Expand Down Expand Up @@ -377,7 +395,7 @@ Several things might be necessary to get `ibm_db` working on the Apple Silicon a
* Verify the output of `gcc -v` command. It should show `Target: x86_64-apple-darwin21` in output.
* Install Intel Version of Python like: https://www.python.org/ftp/python/3.9.11/python-3.9.11-macosx10.9.pkg
### 7.3 Install ibm_db with x86_64 version of gcc12 and Python on M1/M2 Chip System
### 3.3 Install ibm_db with x86_64 version of gcc12 and Python on M1/M2 Chip System
* Open a new terminal and run below commands:
```
Expand All @@ -388,13 +406,13 @@ pip3 install ibm_db
```
Now, run your test program to verify.
## <a name="troubleshooting"></a> 8. Troubleshooting Post Install Errors
## <a name="troubleshooting"></a> 4. Troubleshooting Post Install Errors
<a name="sql30081n"></a> 8.1 SQL30081N Error
<a name="sql30081n"></a> 4.1 SQL30081N Error
* If connection fails with SQL30081N error: means `ibm_db` installation is correct and you need to provide correct connection string.
<a name="symbolerror"></a> 8.2 Symbol not found error or malloc error
<a name="symbolerror"></a> 4.2 Symbol not found error or malloc error
* If `import ibm_db` fails with `Symbol not found: ___cxa_throw_bad_array_new_length` error or `malloc` error:
You need to find the correct location of lib/gcc/12 directory and add it to DYLD_LIBRARY_PATH environment variable.
Expand Down
54 changes: 50 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,10 @@ Db2 V11.5.4 clidriver is built with GCC version 8.4.0 and hence you may need to

* You may need to install **gcc, python, pip, python-devel, libxml2 and pam** if not already installed. Refer to [Installation](#docker) 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](https://github.com/ibmdb/python-ibmdb/blob/master/INSTALL.md#inslnx).

<a name="installation"></a>
## Installation

Expand Down Expand Up @@ -271,24 +275,66 @@ True

## Example of SSL Connection String

* **Secure Database Connection using SSL/TSL** - ibm_db supports secure connection to Database Server over SSL same as ODBC/CLI driver. If you have SSL Certificate from server or an CA signed certificate, just use it in connection string as below:
```
Using SSLServerCertificate keyword

conn = ibm_db.connect("DATABASE=<DATABASE_NAME>;HOSTNAME=<HOSTNAME>;PORT=<SSL_PORT>;SECURITY=SSL;SSLServerCertificate=<FULL_PATH_TO_SERVER_CERTIFICATE>;UID=<USER_ID>;PWD=<PASSWORD>",'','')
connStr = "DATABASE=<DATABASE_NAME>;HOSTNAME=<HOSTNAME>;PORT=<SSL_PORT>;UID=<USER_ID>;PWD=<PASSWORD>;" +
"SECURITY=SSL;SSLServerCertificate=<FULL_PATH_TO_SERVER_CERTIFICATE>;"
conn = ibm_db.connect(connStr,'','')
```
> Note the two extra keywords **Security** and **SSLServerCertificate** used in connection string. `SSLServerCertificate` should point to the SSL Certificate from server or an CA signed certificate. Also, `PORT` must be `SSL` port and not the TCPI/IP port. Make sure Db2 server is configured to accept connection on SSL port else `ibm_db` will throw SQL30081N error.
> Value of `SSLServerCertificate` keyword must be full path of a certificate file generated for client authentication.
It normally has `*.arm` or `*.cert` or `*.pem` extension. `ibm_db` do not support `*.jks` format file as it is not a
certificate file but a Java KeyStore file, extract certificate from it using keytool and then use the *.cert file.
> `ibm_db` uses IBM ODBC/CLI Driver for connectivity and it do not support a `*.jks` file as keystoredb as `keystore.jks` is meant for Java applications.
Note that `*.jks` file is a `Java Key Store` file and it is not an SSL Certificate file. You can extract SSL certificate from JKS file using below `keytool` command:
```
keytool -exportcert -alias your_certificate_alias -file client_cert.cert -keystore keystore.jks
```
Now, you can use the generated `client_cert.cert` as the value of `SSLServerCertificate` in connection string.
> Do not use keyworkds like `sslConnection=true` in connection string as it is a JDBC connection keyword and ibm_db
ignores it. Corresponding ibm_db connection keyword for `sslConnection` is `Security` hence, use `Security=SSL;` in
connection string instead.
> `ibm_db` supports only ODBC/CLI Driver keywords in connection string: https://www.ibm.com/docs/en/db2/11.5?topic=odbc-cliodbc-configuration-keywords
* To connect to dashDB in IBM Cloud, use below connection string:
```
connStr = "DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=passwd;Security=SSL";
```
> We just need to add **Security=SSL** in connection string to have a secure connection against Db2 server in IBM Cloud.
**Note:** You can also create a KeyStore DB using GSKit command line tool and use it in connection string along with other keywords as documented in [DB2 Infocenter](http://www.ibm.com/support/knowledgecenter/en/SSEPGG_11.5.0/com.ibm.db2.luw.admin.sec.doc/doc/t0053518.html).
* If you have created a KeyStore DB using GSKit using password or you have got *.kdb file with *.sth file:
```
Using SSLClientKeyStoreDB and SSLClientKeyStoreDBPassword keyword

conn = ibm_db.connect("DATABASE=<DATABASE_NAME>;HOSTNAME=<HOSTNAME>;PORT=<SSL_PORT>;SECURITY=SSL;SSLClientKeyStoreDB=<FULL_PATH_TO_CLIENT_KEY_STORE_DB>;SSLClientKeyStoreDBPassword=<KEYSTORE_PASSWORD>;UID=<USER_ID>;PWD=<PASSWORD>",'','')
connStr = "DATABASE=<DATABASE_NAME>;HOSTNAME=<HOSTNAME>;PORT=<SSL_PORT>;UID=<USER_ID>;PWD=<PASSWORD>;" +
"SECURITY=SSL;SSLClientKeyStoreDB=<FULL_PATH_TO_KEY_STORE_DB>;SSLClientKeyStoreDBPassword=<KEYSTORE_PASSWD>;"
conn = ibm_db.connect(connStr,'','')
```
```
Using SSLClientKeyStoreDB and SSLClientKeyStash keyword

conn = ibm_db.connect("DATABASE=<DATABASE_NAME>;HOSTNAME=<HOSTNAME>;PORT=<SSL_PORT>;SECURITY=SSL;SSLClientKeyStoreDB=<FULL_PATH_TO_CLIENT_KEY_STORE_DB>;SSLClientKeyStash=<FULL_PATH_TO_CLIENT_KEY_STASH>;UID=<USER_ID>;PWD=<PASSWORD>",'','')
connStr = "DATABASE=<DATABASE_NAME>;HOSTNAME=<HOSTNAME>;PORT=<SSL_PORT>;UID=<USER_ID>;PWD=<PASSWORD>;" +
"SECURITY=SSL;SSLClientKeyStoreDB=<FULL_PATH_TO_KEY_STORE_DB>;" +
"SSLClientKeyStash=<FULL_PATH_TO_CLIENT_KEY_STASH>;"
conn = ibm_db.connect(connStr,'','')
```
> If you have downloaded `IBMCertTrustStore` from IBM site, ibm_db will not work with it; you need to
download `Secure Connection Certificates.zip` file that comes for IBM DB2 Command line tool(CLP).
`Secure Connection Certificates.zip` has *.kdb and *.sth files that should be used as the value of
`SSLClientKeystoreDB` and `SSLClientKeystash` in connection string.
* More examples can be found under ['ibm_db_tests'](https://github.com/ibmdb/python-ibmdb/tree/master/IBM_DB/ibm_db/ibm_db_tests) folder.
* [API Documentation](https://github.com/ibmdb/python-ibmdb/wiki/APIs) has examples for each API.
Expand Down Expand Up @@ -595,4 +641,4 @@ docker build -t <image_name> .
- These steps are tailored for M1 Macs to ensure seamless installation and configuration of IBM DB and Docker support.
- Verify that your Dockerfile and any dependencies are compatible with the specified platform architecture.
Follow these steps carefully to set up IBM DB and Docker support on your M1 Mac environment. If you encounter any issues or have further questions, feel free to seek assistance from the community or relevant support channels.
Happy coding!
Happy coding!

0 comments on commit 3509504

Please sign in to comment.