# SQLAlchemy adapter for IBM i
[](https://pypi.org/project/sqlalchemy-ibmi)
[](https://sqlalchemy-ibmi.readthedocs.io/en/latest/?badge=latest)
The IBM i SQLAlchemy adapter provides an [SQLAlchemy](https://www.sqlalchemy.org/)
interface to Db2 for [IBM i](https://en.wikipedia.org/wiki/IBM_i).
**Please note that this project is still under active development. Please
report any bugs in the issue tracker** :rotating_light:
## Requirements
### SQLAlchemy
| SQLAlchemy Version | Supported | Notes |
|--------------------|-----------|-------------------------------------------------|
| SQLAlchemy 1.3 | ✅ | Most tested. |
| SQLAlchemy 1.4 | ✅ | Preliminary support added in 0.9.3. |
| SQLAlchemy 2.0+ | ❌ | Currently not supported, but planned for 0.9.4. |
### Python
Python 3.6 - 3.11 are supported. Support for Python 3.12 and
up is [currently broken](https://github.com/IBM/sqlalchemy-ibmi/issues/149).
NOTE: sqlalchemy-ibmi 0.9.3 is the last version to support Python 3.6.
### IBM i Access ODBC Driver
It is best to use the latest version of the driver, which is currently available in the
IBM i Access Client Solutions Application Package 1.1.0.27.
Some options may require certain minimum driver versions to be enabled. Because the
driver ignores any unknown options, using them on older driver versions will not cause
an error but instead be silently ignored.
| Connection Option | Required Version |
|--------------------|-------------------|
| `trim_char_fields` | 1.1.0.25 |
### IBM i
This adapter is only tested against IBM i 7.3 and up. It may support older IBM i
releases, but no support is guaranteed.
## Installation
```sh
pip install sqlalchemy-ibmi
```
## Getting Started
You will need to have the [IBM i Access ODBC Driver](https://www.ibm.com/support/pages/ibm-i-access-client-solutions)
installed in order to use this adapter. Please read
[these docs](https://ibmi-oss-docs.readthedocs.io/en/latest/odbc/installation.html)
for the simplest way to install for your platform.
```python
import sqlalchemy as sa
engine = sa.create_engine("ibmi://user:password@host.example.com")
cnxn = engine.connect()
metadata = sa.MetaData()
table = sa.Table('table_name', metadata, autoload=True, autoload_with=engine)
query = sa.select([table])
result = cnxn.execute(query)
result = result.fetchall()
# print first entry
print(result[0])
```
For more details on connection options, check
[our docs](https://sqlalchemy-ibmi.readthedocs.io/en/latest#connection-arguments)
If you're new to SQLAlchemy, please refer to the
[SQLAlchemy Unified Tutorial](https://docs.sqlalchemy.org/en/14/tutorial/index.html).
## Documentation
The documentation for the SQLAlchemy adapter for IBM i can be found at:
<https://sqlalchemy-ibmi.readthedocs.io/en/latest/>
## Known Limitations
1) Non-standard SQL queries are not supported. e.g. "SELECT ? FROM TAB1"
2) For updations involving primary/foreign key references, the entries should be made in correct order. Integrity check is always on and thus the primary keys referenced by the foreign keys in the referencing tables should always exist in the parent table.
3) Unique key which contains nullable column not supported
4) UPDATE CASCADE for foreign keys not supported
5) DEFERRABLE INITIALLY deferred not supported
6) Subquery in ON clause of LEFT OUTER JOIN not supported
## Contributing to the IBM i SQLAlchemy adapter
Please read the [contribution guidelines](contributing/CONTRIBUTING.md).
```text
The developer sign-off should include the reference to the DCO in remarks(example below):
DCO 1.1 Signed-off-by: Random J Developer <random@developer.org>
```
## Releasing a New Version
```sh
# checkout and pull the latest code from main
git checkout main
git pull
# bump to a release version (a tag and commit are made)
bumpversion release
# To skip a release candidate
bumpversion --no-tag --no-commit release
bumpversion --allow-dirty release
# bump to the new dev version (a commit is made)
bumpversion --no-tag patch
# push the new tag and commits
git push origin main --tags
```
## License
[Apache 2.0](LICENSE)
## Credits
- ibm_db_sa for SQLAlchemy was first produced by IBM Inc., targeting version 0.4.
- The library was ported for version 0.6 and 0.7 by Jaimy Azle.
- Port for version 0.8 and modernization of test suite by Mike Bayer.
- Port for sqlalchemy-ibmi by Naveen Ram/Kevin Adler.
Raw data
{
"_id": null,
"home_page": "",
"name": "sqlalchemy-ibmi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6.2",
"maintainer_email": "",
"keywords": "sqlalchemy,database,ibm,ibmi,db2",
"author": "Naveen Ram",
"author_email": "naveen.ram@ibm.com",
"download_url": "https://files.pythonhosted.org/packages/52/37/7d351881dfc0e063f9fcf90a17e947b41801c5f0e42e09f6cbc1df2fd559/sqlalchemy_ibmi-0.9.3.tar.gz",
"platform": null,
"description": "# SQLAlchemy adapter for IBM i\n\n[](https://pypi.org/project/sqlalchemy-ibmi)\n\n[](https://sqlalchemy-ibmi.readthedocs.io/en/latest/?badge=latest)\n\nThe IBM i SQLAlchemy adapter provides an [SQLAlchemy](https://www.sqlalchemy.org/)\ninterface to Db2 for [IBM i](https://en.wikipedia.org/wiki/IBM_i).\n\n**Please note that this project is still under active development. Please\n report any bugs in the issue tracker** :rotating_light:\n\n## Requirements\n\n### SQLAlchemy\n\n| SQLAlchemy Version | Supported | Notes |\n|--------------------|-----------|-------------------------------------------------|\n| SQLAlchemy 1.3 | \u2705 | Most tested. |\n| SQLAlchemy 1.4 | \u2705 | Preliminary support added in 0.9.3. |\n| SQLAlchemy 2.0+ | \u274c | Currently not supported, but planned for 0.9.4. |\n\n### Python\n\nPython 3.6 - 3.11 are supported. Support for Python 3.12 and\nup is [currently broken](https://github.com/IBM/sqlalchemy-ibmi/issues/149).\n\nNOTE: sqlalchemy-ibmi 0.9.3 is the last version to support Python 3.6.\n\n### IBM i Access ODBC Driver\n\nIt is best to use the latest version of the driver, which is currently available in the\nIBM i Access Client Solutions Application Package 1.1.0.27.\n\nSome options may require certain minimum driver versions to be enabled. Because the\ndriver ignores any unknown options, using them on older driver versions will not cause\nan error but instead be silently ignored.\n\n| Connection Option | Required Version |\n|--------------------|-------------------|\n| `trim_char_fields` | 1.1.0.25 |\n\n### IBM i\n\nThis adapter is only tested against IBM i 7.3 and up. It may support older IBM i\nreleases, but no support is guaranteed.\n\n## Installation\n\n```sh\npip install sqlalchemy-ibmi\n```\n\n## Getting Started\n\nYou will need to have the [IBM i Access ODBC Driver](https://www.ibm.com/support/pages/ibm-i-access-client-solutions)\ninstalled in order to use this adapter. Please read\n[these docs](https://ibmi-oss-docs.readthedocs.io/en/latest/odbc/installation.html)\nfor the simplest way to install for your platform.\n\n```python\nimport sqlalchemy as sa\nengine = sa.create_engine(\"ibmi://user:password@host.example.com\")\n\ncnxn = engine.connect()\nmetadata = sa.MetaData()\ntable = sa.Table('table_name', metadata, autoload=True, autoload_with=engine)\n\nquery = sa.select([table])\n\nresult = cnxn.execute(query)\nresult = result.fetchall()\n\n# print first entry\nprint(result[0])\n```\n\nFor more details on connection options, check\n[our docs](https://sqlalchemy-ibmi.readthedocs.io/en/latest#connection-arguments)\n\nIf you're new to SQLAlchemy, please refer to the\n[SQLAlchemy Unified Tutorial](https://docs.sqlalchemy.org/en/14/tutorial/index.html).\n\n## Documentation\n\nThe documentation for the SQLAlchemy adapter for IBM i can be found at:\n<https://sqlalchemy-ibmi.readthedocs.io/en/latest/>\n\n## Known Limitations\n\n1) Non-standard SQL queries are not supported. e.g. \"SELECT ? FROM TAB1\"\n2) For updations involving primary/foreign key references, the entries should be made in correct order. Integrity check is always on and thus the primary keys referenced by the foreign keys in the referencing tables should always exist in the parent table.\n3) Unique key which contains nullable column not supported\n4) UPDATE CASCADE for foreign keys not supported\n5) DEFERRABLE INITIALLY deferred not supported\n6) Subquery in ON clause of LEFT OUTER JOIN not supported\n\n## Contributing to the IBM i SQLAlchemy adapter\n\nPlease read the [contribution guidelines](contributing/CONTRIBUTING.md).\n\n```text\nThe developer sign-off should include the reference to the DCO in remarks(example below):\nDCO 1.1 Signed-off-by: Random J Developer <random@developer.org>\n```\n\n## Releasing a New Version\n\n```sh\n# checkout and pull the latest code from main\ngit checkout main\ngit pull\n\n# bump to a release version (a tag and commit are made)\nbumpversion release\n\n# To skip a release candidate\nbumpversion --no-tag --no-commit release\nbumpversion --allow-dirty release\n\n# bump to the new dev version (a commit is made)\nbumpversion --no-tag patch\n\n# push the new tag and commits\ngit push origin main --tags\n```\n\n## License\n\n[Apache 2.0](LICENSE)\n\n## Credits\n\n- ibm_db_sa for SQLAlchemy was first produced by IBM Inc., targeting version 0.4.\n- The library was ported for version 0.6 and 0.7 by Jaimy Azle.\n- Port for version 0.8 and modernization of test suite by Mike Bayer.\n- Port for sqlalchemy-ibmi by Naveen Ram/Kevin Adler.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "SQLAlchemy support for Db2 on IBM i",
"version": "0.9.3",
"project_urls": null,
"split_keywords": [
"sqlalchemy",
"database",
"ibm",
"ibmi",
"db2"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a3ba7729256041185552c25e8ef4f93a2cef9c81e6dc4050d04f8e5df01e3063",
"md5": "b85ecd11ff04b18d33223d9c111b173e",
"sha256": "28ef283d391133b8164fca86ecff95d40ee3b060357dc193c66f9481c990b48c"
},
"downloads": -1,
"filename": "sqlalchemy_ibmi-0.9.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b85ecd11ff04b18d33223d9c111b173e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6.2",
"size": 24657,
"upload_time": "2023-12-14T19:15:37",
"upload_time_iso_8601": "2023-12-14T19:15:37.370451Z",
"url": "https://files.pythonhosted.org/packages/a3/ba/7729256041185552c25e8ef4f93a2cef9c81e6dc4050d04f8e5df01e3063/sqlalchemy_ibmi-0.9.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "52377d351881dfc0e063f9fcf90a17e947b41801c5f0e42e09f6cbc1df2fd559",
"md5": "11849f3e05dc77cbbccfc26ed97da575",
"sha256": "c9bdd33e2a4901cd840d691996ea048ca62750847ebd2d6aa7a6dc802576180a"
},
"downloads": -1,
"filename": "sqlalchemy_ibmi-0.9.3.tar.gz",
"has_sig": false,
"md5_digest": "11849f3e05dc77cbbccfc26ed97da575",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.2",
"size": 30640,
"upload_time": "2023-12-14T19:15:39",
"upload_time_iso_8601": "2023-12-14T19:15:39.382313Z",
"url": "https://files.pythonhosted.org/packages/52/37/7d351881dfc0e063f9fcf90a17e947b41801c5f0e42e09f6cbc1df2fd559/sqlalchemy_ibmi-0.9.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-14 19:15:39",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sqlalchemy-ibmi"
}
JSON