rust_ibm_db

A Rust interface for connecting to IBM DB2 databases (z/OS, LUW, i) with connection pooling support using r2d2.

📋 Table of Contents

Quick Start
Prerequisites
Installation
Configuration
Running Examples
Documentation
Troubleshooting
License Requirements
Contributing

Quick Start for Beginners

If you're new to Rust and want to get started quickly:

Install Prerequisites (15 minutes)
Run Setup Utility (5-10 minutes)
Configure Environment (5 minutes)
Run First Example (2 minutes)

Total time: ~30 minutes to your first database connection!

Prerequisites

Required Software

Before starting, make sure you have installed:

Rust (version 1.45 or newer) — Install Rust
Git — Install Git
A C compiler:
- Windows: Microsoft Visual Studio Build Tools
- Linux: GCC or Clang (usually pre-installed)
- macOS: Xcode Command Line Tools

Verify Your Setup

Open a terminal/command prompt and run:

rustc --version     # Should show Rust version ≥ 1.45
git --version       # Should show Git version

If either command fails, follow the installation links above.

System Dependencies

Depending on your operating system, you'll need to install additional libraries. These contain the necessary files for database connections.

🪟 Windows

# Option 1: Using Chocolatey (recommended)
choco install openssl

# Option 2: Manual installation
# Download from: https://slproweb.com/products/Win32OpenSSL.html
# Choose "Win64 OpenSSL v3.0.x" (for 64-bit Windows)

✅ ODBC is included: Windows comes with ODBC development files pre-installed, so you don't need to install anything extra!

🐧 Linux (Ubuntu/Debian)

# Install OpenSSL and ODBC development files
sudo apt-get update
sudo apt-get install -y libssl-dev unixodbc-dev

🐧 Linux (RedHat/CentOS/Fedora)

# Install OpenSSL and ODBC development files
sudo yum install -y openssl-devel unixODBC-devel

🍎 macOS

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install OpenSSL and ODBC
brew install openssl unixodbc

# Set up environment variables (add to your shell profile)
echo 'export LDFLAGS="-L/usr/local/opt/openssl/lib"' >> ~/.zshrc
echo 'export CPPFLAGS="-I/usr/local/opt/openssl/include"' >> ~/.zshrc
source ~/.zshrc

Verify System Dependencies

Check that your system dependencies are installed:

Windows (Command Prompt):

openssl version

Linux/macOS (Terminal):

openssl version

You should see output like: OpenSSL 3.0.x ...

Installation

Step 1: Get the Code

# Clone the repository (or download the zip file)
git clone https://github.com/ibmdb/rust-ibm_db.git
cd rust-ibm_db

Step 2: Download & Install IBM DB2 CLI Driver

The setup utility will automatically download the correct driver for your system. Simply run:

cargo run --bin setup

What happens:

✅ Detects your operating system (Windows / Linux / macOS)
✅ Detects your system architecture (32-bit / 64-bit)
✅ Downloads the appropriate IBM DB2 CLI Driver
✅ Extracts the files to your system
✅ Sets up environment variables (see next step)

Expected output:

Setting up IBM DB2 CLI Driver...
Downloading CLI Driver for your platform...
[Download progress...]
Installation complete! IBM_DB_HOME is now set to: /path/to/clidriver

Step 3: Verify Installation

Let's make sure everything was installed correctly:

Windows (Command Prompt):

echo %IBM_DB_HOME%    # Should print the path
dir %IBM_DB_HOME%     # Should show many files

Linux/macOS (Terminal):

echo $IBM_DB_HOME       # Should print the path
ls -la $IBM_DB_HOME     # Should show many files

Both commands should show output. If you see errors, check Troubleshooting.

Step 4: Install the ibm_db Crate

Now that the CLI driver is installed, you need to install the Rust crate that provides the Rust API.

Option A: Install from crates.io (recommended)

cargo install ibm_db

Option B: Install from current repository

cargo install --path .

Why two options?

Option A: Always gets the latest published version from crates.io
Option B: Installs from the repo you cloned, useful if you're modifying the code

✅ Installation complete! You now have:

✅ IBM DB2 CLI Driver installed
✅ ibm_db Rust crate installed
✅ Environment variables configured

When is setup.rs Needed?

You ONLY need setup.rs if:

✅ The CLI driver is NOT yet installed
✅ You're setting up on a fresh machine

You DON'T need setup.rs if:

✅ CLI driver is already installed
✅ You're using a project that already has the driver
✅ You're installing from crates.io

Configuration

Setting Environment Variables

After the setup utility completes, your environment variables should be configured. However, you may need to set them manually in a new terminal session. Follow the steps for your operating system:

🪟 Windows (Command Prompt)

Temporary (current session only):

set IBM_DB_HOME=C:\IBM\IBM_DATA_SERVER_DRIVER\clidriver
set PATH=%IBM_DB_HOME%\bin;%PATH%

Permanent (recommended):

Press Win + RBreak to open System Properties
Click Environment Variables
Click New (under System variables)
Add two variables:
- Name: IBM_DB_HOME | Value: C:\IBM\IBM_DATA_SERVER_DRIVER\clidriver
- Name: PATH | Value: C:\IBM\IBM_DATA_SERVER_DRIVER\clidriver\bin; (prefix to existing PATH)
Click OK and restart your terminal

🐧 Linux (Bash/Zsh)

Temporary (current session):

export IBM_DB_HOME=/IBM/IBM_DATA_SERVER_DRIVER/clidriver
export LD_LIBRARY_PATH=$IBM_DB_HOME/bin:$LD_LIBRARY_PATH

Permanent (recommended):

# Add to ~/.bashrc or ~/.zshrc
echo 'export IBM_DB_HOME=/IBM/IBM_DATA_SERVER_DRIVER/clidriver' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=$IBM_DB_HOME/bin:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

🍎 macOS (Zsh/Bash)

Temporary (current session):

export IBM_DB_HOME=/IBM/IBM_DATA_SERVER_DRIVER/clidriver
export DYLD_LIBRARY_PATH=$IBM_DB_HOME/bin:$DYLD_LIBRARY_PATH

Permanent (recommended):

# For Zsh (default in modern macOS)
echo 'export IBM_DB_HOME=/IBM/IBM_DATA_SERVER_DRIVER/clidriver' >> ~/.zshrc
echo 'export DYLD_LIBRARY_PATH=$IBM_DB_HOME/bin:$DYLD_LIBRARY_PATH' >> ~/.zshrc
source ~/.zshrc

# OR for Bash
echo 'export IBM_DB_HOME=/IBM/IBM_DATA_SERVER_DRIVER/clidriver' >> ~/.bash_profile
echo 'export DYLD_LIBRARY_PATH=$IBM_DB_HOME/bin:$DYLD_LIBRARY_PATH' >> ~/.bash_profile
source ~/.bash_profile

Connecting to Your Database

When you connect to a database, you'll need a connection string. This tells the driver where to find your database.

Connection String Format:

DRIVER={IBM DB2 ODBC DRIVER};DATABASE=mydb;HOSTNAME=server.com;PORT=50000;UID=myuser;PWD=mypassword

Breaking it down:

DRIVER={IBM DB2 ODBC DRIVER} — Always use this (it's the driver name)
DATABASE=mydb — Your database name
HOSTNAME=server.com — Your server address
PORT=50000 — Your database port
UID=myuser — Your username
PWD=mypassword — Your password

Example with real values:

let connection_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=SAMPLE;HOSTNAME=db.mycompany.com;PORT=60000;UID=admin;PWD=secretpass123";

Running Examples

Important: Set IBM_DB_HOME Before Running

To use the CLI driver in your cargo commands, you must set the IBM_DB_HOME environment variable:

Windows (Command Prompt):

cargo run --package ibm_db --example connect

IBM_DB_HOME should already be set from Configuration section

Linux/macOS (Terminal):

IBM_DB_HOME=. cargo run --package ibm_db --example connect

Or use the path where you installed the clidriver

Your First Program: Connect to Database

Windows:

cargo run --package ibm_db --example connect

Linux/macOS:

IBM_DB_HOME=. cargo run --package ibm_db --example connect

You'll be prompted to enter a SQL query. Try:

SELECT * FROM SYSCAT.TABLES

Other Examples

The project includes many examples to learn from:

Example	What it does
`connect`	Basic database connection
`list_tables`	Lists all tables in a database
`execute_query`	Runs SQL queries
`bind_params`	Uses parameterized queries (safe for user input)
`transaction_control`	Demonstrates transactions (commit/rollback)
`data_types`	Shows how to work with different DB2 data types
`error_handling`	Proper error handling patterns
`connect_pool`	Connection pooling for performance

Run any example:

Windows:

cargo run --package ibm_db --example <example_name>

Linux/macOS:

IBM_DB_HOME=. cargo run --package ibm_db --example <example_name>

Example commands:

# Windows
cargo run --package ibm_db --example connect
cargo run --package ibm_db --example list_tables

# Linux/macOS
IBM_DB_HOME=. cargo run --package ibm_db --example connect
IBM_DB_HOME=. cargo run --package ibm_db --example list_tables

Documentation

Complete API Reference: https://docs.rs/ibm_db/
Crates.io Page: https://crates.io/crates/ibm_db
GitHub Repository: https://github.com/ibmdb/rust-ibm_db
Examples Folder: See examples/ directory in this repository

How to Use in Your Own Project

Step 1: Create a New Rust Project

cargo new my_db_app
cd my_db_app

Step 2: Add IBM DB2 to Cargo.toml

Edit Cargo.toml and add:

[dependencies]
ibm_db = "1.0.6"

Step 3: Write Code to Connect

Edit src/main.rs:

use ibm_db::environment::Environment;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create an ODBC environment
    let env = Environment::new()?;
    
    // Connect to the database
    let connection_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=SAMPLE;HOSTNAME=your.server.com;PORT=60000;UID=youruser;PWD=yourpass";
    let conn = env.connect_with_connection_string(connection_string)?;
    
    println!("✅ Connected to database!");
    
    Ok(())
}

Step 4: Run It!

Windows:

REM Make sure IBM_DB_HOME is set (from Configuration section)
cargo run

Linux/macOS:

IBM_DB_HOME=. cargo run

You should see: ✅ Connected to database!

Components Overview

What's Inside?

This project contains several key parts (don't worry if you don't understand all of this yet):

Component	Purpose	Example Use
Setup Utility	Downloads and installs the DB2 driver	Run once: `cargo run --bin setup`
Connection Module	Opens/manages database connections	Used internally by functions
ODBC Interface	Communicates with the database	Used internally by functions
Statement Processor	Executes SQL queries	`execute_query.rs` example
Error Handler	Shows detailed error messages	When something goes wrong
Connection Pooling	Reuses connections efficiently	For advanced applications

Technology Stack (In Plain English)

ODBC: The "universal language" that lets Rust talk to database drivers
OpenSSL: Encryption library for secure communication
IBM DB2 CLI Driver: The translator between ODBC and the actual DB2 database

Prerequisite

RUST should be installed (Rust version should be >=1.45) Confirm by typing below in command prompt:

>rustc --version

GIT should be installed Confirm by typing below in command prompt:

>git --version

System Dependencies

Windows

OpenSSL: Download and install from https://slproweb.com/products/Win32OpenSSL.html (or use choco install openssl)
ODBC Development Files: Included with Windows SDK

Linux (Ubuntu/Debian)

# Install OpenSSL development files
sudo apt-get install libssl-dev

# Install ODBC development files
sudo apt-get install unixodbc-dev

Linux (RedHat/CentOS/Fedora)

# Install OpenSSL development files
sudo yum install openssl-devel

# Install ODBC development files
sudo yum install unixODBC-devel

macOS

# Install OpenSSL using Homebrew
brew install openssl

# Install ODBC (if not already installed)
brew install unixodbc

After installing OpenSSL on macOS, you may need to set environment variables:

export LDFLAGS="-L/usr/local/opt/openssl/lib"
export CPPFLAGS="-I/usr/local/opt/openssl/include"

OpenSSL Configuration Details

Why Is OpenSSL Important?

OpenSSL handles the security aspects of your database connection. It ensures:

🔒 Encryption: Your data is scrambled in transit
🔐 Authentication: The server proves it's really who it claims to be
✅ Security: Prevents eavesdropping and man-in-the-middle attacks

Verify OpenSSL is Working

Windows:

openssl version -a
where openssl

Linux/macOS:

openssl version -a
pkg-config --cflags --libs openssl

If you see error messages, go back to the System Dependencies section.

Common OpenSSL Problems & Fixes

❌ Problem	🔍 Reason	✅ Solution
`undefined reference to 'SSL_CTX_new'`	OpenSSL not installed	Install OpenSSL (see System Dependencies)
`library not found for -lssl` (macOS)	OpenSSL in wrong location	Run: `export LDFLAGS="-L/usr/local/opt/openssl/lib"`
`libssl.so.1.1: cannot open shared object`	Missing runtime library	Ubuntu: `sudo apt-get install libssl1.1`

Troubleshooting

Windows Errors

❌ Error	🔧 What to Try
`"libssl-1_1-x64.dll not found"`	Install OpenSSL: https://slproweb.com/products/Win32OpenSSL.html
`"IBM DB2 ODBC DRIVER not found"`	Set `IBM_DB_HOME` and `PATH` (see Configuration section)
`"The setup.rs crashed/hung"`	Close the terminal and try again. Check internet connection.

Linux Errors

❌ Error	🔧 What to Try
`"libssl.so.1.1: cannot open shared object file"`	Run: `sudo apt-get install libssl1.1`
`"unixodbc-dev not found"`	Run: `sudo apt-get install unixodbc-dev`
`"LD_LIBRARY_PATH not persisting"`	Add export statements to `~/.bashrc` and run: `source ~/.bashrc`

macOS Errors

❌ Error	🔧 What to Try
`"dyld: Library not loaded: libdb2.dylib"`	Set `DYLD_LIBRARY_PATH` before running (see Configuration section)
`"library not found for -lssl"`	Set: `export LDFLAGS="-L/usr/local/opt/openssl/lib"`
`"Homebrew OpenSSL not found"`	Run: `brew install openssl` and set LDFLAGS/CPPFLAGS

General Tips

Still have issues? Try these steps:

Close and reopen your terminal — Updates to environment variables won't appear until you do this
Verify each step — Run the verification commands in the Configuration section
Check internet connection — The setup utility needs to download the CLI Driver (100+ MB)
Look for typos — Environment variable paths are case-sensitive on Linux/macOS
Ask for help — Visit https://github.com/ibmdb/rust-ibm_db/issues

License Requirements

Free Databases

You can connect to these without additional licenses:

✅ DB2 for Linux/Unix/Windows (LUW)
✅ DB2 on premises
✅ IBM Cloud Db2

Licensed Databases

Connecting to these requires purchased licenses:

⚠️ DB2 for z/OS (mainframe)
⚠️ DB2 for i (AS/400)

What to do if you need a license:

Contact IBM Customer Support
Purchase DB2 Connect Unlimited for your platform
Copy the license file to: $IBM_DB_HOME/license/

Contributing

We welcome contributions! Whether you find a bug, want to add a feature, or improve documentation:

Report Issues: https://github.com/ibmdb/rust-ibm_db/issues
Submit Pull Requests: https://github.com/ibmdb/rust-ibm_db/pulls
Read Guidelines: See CONTRIBUTING.md

When contributing, please include:

What problem you're solving
How to test your changes
Any new dependencies (with versions)

Developer Sign-Off

All contributions require a sign-off referencing the DCO:

DCO 1.1 Signed-off-by: Your Name <your.email@example.com>

Project Structure

rust-ibm_db/
├── src/
│   ├── lib.rs                 # Main library file
│   ├── connection.rs          # Database connection logic
│   ├── statement/             # SQL statement execution
│   ├── environment/           # ODBC environment setup
│   ├── diagnostics.rs         # Error handling
│   └── ffi.rs                 # Low-level C bindings
├── src/bin/
│   └── setup.rs               # CLI Driver download utility
├── examples/
│   ├── connect.rs             # Basic connection example
│   ├── execute_query.rs       # Run SQL example
│   ├── bind_params.rs         # Parameterized queries
│   └── ...                    # More examples
├── build.rs                   # Build script (compiles C code)
├── Cargo.toml                 # Project dependencies
└── README.md                  # This file

Resources for Learning

Rust Fundamentals

The Rust Book - Official Rust guide
Rust by Example - Learn by doing
Rustlings - Micro-lessons

DB2 & Databases

rust_ibm_db Specific

API Documentation - Full function reference
GitHub Repository - Source code
Examples Folder - Real code examples

Frequently Asked Questions (FAQ)

Q: Do I need to know Rust to use this?

A: You need basic Rust knowledge. Check out The Rust Book for a quick introduction.

Q: What if I can't install the CLI Driver?

A: The setup utility automates this, but if it fails: Check your internet, ensure you have 500MB free disk space, and see Troubleshooting section.

Q: Can I use this on macOS?

A: Yes! Ensure you install OpenSSL via Homebrew and set the LDFLAGS/CPPFLAGS environment variables.

Q: Do I need to set environment variables in every terminal?

A: No, if you make the changes permanent (see Configuration section), they'll persist.

Q: What if my database uses a non-standard port?

A: That's fine! Just include the port in your connection string (e.g., PORT=52000).

Q: How do I secure my database password?

A: Never hardcode passwords! Use environment variables:

let password = std::env::var("DB_PASSWORD")?;
let conn_str = format!("DRIVER={{IBM DB2 ODBC DRIVER}};...;PWD={}", password);

Related Projects

ibm_db (Python) - IBM DB2 for Python
ibm_db_nodejs - IBM DB2 for Node.js
ibm_db_go - IBM DB2 for Go

License

This project is licensed under the Apache License 2.0. See LICENSE file for details

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
examples		examples
src		src
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
build.rs		build.rs
rust-ibm_db.iml		rust-ibm_db.iml

Folders and files

Latest commit

History

Repository files navigation

rust_ibm_db

📋 Table of Contents

Quick Start for Beginners

Prerequisites

Required Software

Verify Your Setup

System Dependencies

🪟 Windows

🐧 Linux (Ubuntu/Debian)

🐧 Linux (RedHat/CentOS/Fedora)

🍎 macOS

Verify System Dependencies

Installation

Step 1: Get the Code

Step 2: Download & Install IBM DB2 CLI Driver

Step 3: Verify Installation

Step 4: Install the ibm_db Crate

When is setup.rs Needed?

Configuration

Setting Environment Variables

🪟 Windows (Command Prompt)

🐧 Linux (Bash/Zsh)

🍎 macOS (Zsh/Bash)

Connecting to Your Database

Running Examples

Important: Set IBM_DB_HOME Before Running

Your First Program: Connect to Database

Other Examples

Documentation

How to Use in Your Own Project

Step 1: Create a New Rust Project

Step 2: Add IBM DB2 to Cargo.toml

Step 3: Write Code to Connect

Step 4: Run It!

Components Overview

What's Inside?

Technology Stack (In Plain English)

Prerequisite

System Dependencies

Windows

Linux (Ubuntu/Debian)

Linux (RedHat/CentOS/Fedora)

macOS

OpenSSL Configuration Details

Why Is OpenSSL Important?

Verify OpenSSL is Working

Common OpenSSL Problems & Fixes

Troubleshooting

Windows Errors

Linux Errors

macOS Errors

General Tips

License Requirements

Free Databases

Licensed Databases

Contributing

Developer Sign-Off

Project Structure

Resources for Learning

Rust Fundamentals

DB2 & Databases

rust_ibm_db Specific

Frequently Asked Questions (FAQ)

Q: Do I need to know Rust to use this?

Q: What if I can't install the CLI Driver?

Q: Can I use this on macOS?

Q: Do I need to set environment variables in every terminal?

Q: What if my database uses a non-standard port?

Q: How do I secure my database password?

Related Projects

License

About

Resources

License

Code of conduct

Contributing

Packages