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:

1. Install Prerequisites (15 minutes)
2. Run Setup Utility (5-10 minutes)
3. Configure Environment (5 minutes)
4. 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):

1. Press Win + RBreak to open System Properties
2. Click Environment Variables
3. Click New (under System variables)
4. 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)
5. 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:

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):

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

Troubleshooting

Windows Errors

Linux Errors

macOS Errors

General Tips

Still have issues? Try these steps:

1. Close and reopen your terminal — Updates to environment variables won't appear until you do this
2. Verify each step — Run the verification commands in the Configuration section
3. Check internet connection — The setup utility needs to download the CLI Driver (100+ MB)
4. Look for typos — Environment variable paths are case-sensitive on Linux/macOS
5. 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:

1. Contact IBM Customer Support
2. Purchase DB2 Connect Unlimited for your platform
3. 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:

1. Report Issues: https://github.com/ibmdb/rust-ibm_db/issues
2. Submit Pull Requests: https://github.com/ibmdb/rust-ibm_db/pulls
3. 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

• IBM DB2 Documentation
• ODBC Documentation
• SQL Tutorial - Learn SQL basics

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