SQLAlchemy IBM i (Db2)

0.9.3 verified Mon Apr 27 auth: no python

Provides SQLAlchemy dialects for Db2 on IBM i (AS/400), enabling ORM and core SQL access. Current version 0.9.3, supporting Python >=3.6.2. Maintained as part of the IBM i open source ecosystem.

pip install sqlalchemy-ibmi

Common errors

error sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:ibmi ↓

cause The sqlalchemy-ibmi package is not installed, or the version is too old to register the dialect.

fix

pip install sqlalchemy-ibmi>=0.9.0

error ModuleNotFoundError: No module named 'ibmi_db_api' ↓

cause Missing DB-API driver. pyodbc is the recommended driver but not installed or not found.

fix

pip install sqlalchemy-ibmi[pyodbc] (installs pyodbc) or install an alternative driver like itoolkit.

Warnings

gotcha The default driver is pyodbc. If pyodbc is not installed, you will get an ImportError about 'ibmi_db_api'. Install sqlalchemy-ibmi with the 'pyodbc' extra: pip install sqlalchemy-ibmi[pyodbc] ↓

fix pip install sqlalchemy-ibmi[pyodbc]

breaking SQLAlchemy 2.0 changed the future import pattern. sqlalchemy-ibmi <0.9.x may not support SQLAlchemy 2.0 fully. Ensure you are on 0.9.3 and use SQLAlchemy 2.0 compatible code. ↓

fix Use create_engine with future=True: create_engine('ibmi://...', future=True) or simply upgrade to latest.

deprecated The old connection string format with pyodbc:// is being deprecated. Prefer ibmi://. ↓

fix Switch to ibmi://user:password@host/database

Imports

ibmi

wrong

import sqlalchemy_ibmi
engine = sqlalchemy_ibmi.connect()

correct

from sqlalchemy import create_engine
engine = create_engine('ibmi://user:password@host/database')

The library registers itself as a SQLAlchemy dialect; you never import sqlalchemy_ibmi directly. Use the ibmi:// URL scheme.

Quickstart

Minimal working example: connect to IBM i via ibmi:// URL and run a query.

from sqlalchemy import create_engine
engine = create_engine('ibmi://user:password@host/database')
with engine.connect() as conn:
    result = conn.execute("SELECT * FROM SYSIBM.SYSDUMMY1")
    print(result.fetchone())